entropic_server.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#include <entropic/mcp/servers/entropic_server.h>
#include <entropic/mcp/tool_base.h>
#include <entropic/mcp/server_base.h>
#include <entropic/mcp/utf8_sanitize.h>
#include <entropic/core/directives.h>
#include <entropic/types/logging.h>
#include <entropic/types/run_scope.h>
 
#include <nlohmann/json.hpp>
 
#include <algorithm>
#include <chrono>
#include <cstdlib>
#include <mutex>
#include <string>
#include <vector>
 
static auto logger = entropic::log::get("mcp.entropic");
 
namespace entropic {
 
// ── TodoItem ────────────────────────────────────────────────────
 
struct TodoItem {
    std::string content; 
    std::string status;  
};
 
// ── TodoTool ────────────────────────────────────────────────────
 
class TodoTool : public ToolBase {
public:
    explicit TodoTool(ToolDefinition def)
        : ToolBase(std::move(def)) {}
 
    ServerResponse execute(const std::string& args_json) override;
 
    std::string anchor_key(
        const std::string& args_json) const override;
 
    bool release(const std::string& key) { return lists_.release(key); }
 
    std::size_t session_count() const { return lists_.session_count(); }
 
private:
    SessionScoped<std::vector<TodoItem>> lists_;
};
 
std::string TodoTool::anchor_key(
    const std::string& /*args_json*/) const {
    return "todo_state";
}
 
namespace {
 
std::string format_todo_list(const std::vector<TodoItem>& items) {
    if (items.empty()) {
        return "(empty)";
    }
    std::string out;
    for (size_t i = 0; i < items.size(); ++i) {
        out += std::to_string(i) + ". [" +
               items[i].status + "] " +
               items[i].content + "\n";
    }
    return out;
}
 
std::string todo_index_error(const std::vector<TodoItem>& items,
                             const std::string& action, long idx) {
    std::string err;
    if (0 > idx || idx >= static_cast<long>(items.size())) {
        logger->warn("[todo] {} #{}: out of range (list has {})",
                     action, idx, items.size());
        err = tool_error_json("out_of_range", "index " + std::to_string(idx)
            + " is not in the list, which has " + std::to_string(items.size())
            + " item(s) (indices start at 0)");
    }
    return err;
}
 
std::string apply_todo_action(std::vector<TodoItem>& items,
                              const std::string& action,
                              const nlohmann::json& args) {
    std::string err;
    const long idx = args.value<long>("index", -1);
    if (action == "add") {
        std::string content = args.at("content").get<std::string>();
        items.push_back({content, args.value("status", std::string("pending"))});
        logger->info("[todo] add: {}", content);
    } else if (action != "update" && action != "remove") {
        err = tool_error_json("invalid_args", "unknown action '" + action
                         + "' (add, update or remove)");
    } else if (err = todo_index_error(items, action, idx); err.empty()) {
        auto& item = items[static_cast<size_t>(idx)];
        if (action == "update") {
            item.status = args.value("status", item.status);
            item.content = args.value("content", item.content);
            logger->info("[todo] update #{}: {}", idx, item.status);
        } else {
            logger->info("[todo] remove #{}", idx);
            items.erase(items.begin() + idx);
        }
    }
    return err;
}
 
}  // namespace
 
ServerResponse TodoTool::execute(const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json);
    std::string action = args.at("action").get<std::string>();
 
    const auto session = current_run_session();
    std::string err;
    std::string rendered = lists_.with(session, [&](auto& items) {
        err = apply_todo_action(items, action, args);
        return format_todo_list(items);
    });
    logger->info("[todo] session='{}' action={}", session, action);
    if (!err.empty()) { return {err, {}}; }
 
    nlohmann::json result;
    result["action"] = action;
    result["todo_state"] = rendered;
 
    Directive anchor_d;
    anchor_d.type = ENTROPIC_DIRECTIVE_CONTEXT_ANCHOR;
    Directive notify_d;
    notify_d.type = ENTROPIC_DIRECTIVE_NOTIFY_PRESENTER;
    return {result.dump(), {anchor_d, notify_d}};
}
 
// ── DelegateTool ────────────────────────────────────────────────
 
class DelegateTool : public ToolBase {
public:
    DelegateTool(ToolDefinition def,
                 const std::vector<std::string>& tier_names,
                 std::vector<std::string> require_context_tiers = {});
 
    ServerResponse execute(const std::string& args_json) override;
 
private:
    std::vector<std::string> require_context_tiers_;
};
 
DelegateTool::DelegateTool(
    ToolDefinition def,
    const std::vector<std::string>& tier_names,
    std::vector<std::string> require_context_tiers)
    : ToolBase(std::move(def)),
      require_context_tiers_(std::move(require_context_tiers)) {
 
    auto schema = nlohmann::json::parse(definition_.input_schema);
    schema["properties"]["target"]["enum"] = tier_names;
    definition_.input_schema = schema.dump();
 
    logger->info("[delegate] patched enum with {} tiers ({} require context)",
                 tier_names.size(), require_context_tiers_.size());
}
 
static size_t carry_context(const nlohmann::json& args,
                            nlohmann::json& result) {
    auto out = nlohmann::json::array();
    if (args.contains("context") && args["context"].is_array()) {
        for (const auto& ref : args["context"]) {
            if (!ref.is_object()) { continue; }
            auto path = ref.value("path", std::string{});
            if (path.empty()) { continue; }
            nlohmann::json entry;
            entry["path"] = path;
            entry["lines"] = ref.value("lines", std::string{});
            entry["note"] = ref.value("note", std::string{});
            out.push_back(std::move(entry));
        }
    }
    size_t n = out.size();
    result["context"] = std::move(out);
    return n;
}
 
ServerResponse DelegateTool::execute(const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json);
    std::string target = args.at("target").get<std::string>();
    std::string task = args.at("task").get<std::string>();
    int max_turns = args.value("max_turns", -1);
 
    nlohmann::json result;
    result["action"] = "delegate";
    result["target"] = target;
    result["task"] = task;
    result["max_turns"] = max_turns;
    auto refs = carry_context(args, result);
 
    // gh#162: a tier that declares requires_context cannot succeed on a
    // contextless task, so refuse HERE — a tool error the lead can act on
    // in the same turn, rather than a burned child loop whose transcript
    // nobody reads.
    if (refs == 0
        && std::find(require_context_tiers_.begin(),
                     require_context_tiers_.end(), target)
           != require_context_tiers_.end()) {
        logger->warn("[delegate] refused: tier '{}' requires context", target);
        return {tool_error_json("requires_context", "tier \"" + target
                + "\" requires context. Re-issue entropic.delegate with a "
                "`context` array naming at least one file path (optionally "
                "lines/note) the delegate should read."), {}};
    }
 
    logger->info("[delegate] target='{}' task='{}' max_turns={} context={}",
                 target, task, max_turns, refs);
 
    Directive delegate_d;
    delegate_d.type = ENTROPIC_DIRECTIVE_DELEGATE;
 
    Directive stop_d;
    stop_d.type = ENTROPIC_DIRECTIVE_STOP_PROCESSING;
 
    return {result.dump(), {delegate_d, stop_d}};
}
 
// ── PipelineTool ────────────────────────────────────────────────
 
class PipelineTool : public ToolBase {
public:
    PipelineTool(ToolDefinition def,
                 const std::vector<std::string>& tier_names,
                 std::vector<std::string> require_context_tiers = {});
 
    ServerResponse execute(const std::string& args_json) override;
 
private:
    std::vector<std::string> tier_names_;  
    std::vector<std::string> require_context_tiers_;
};
 
PipelineTool::PipelineTool(
    ToolDefinition def,
    const std::vector<std::string>& tier_names,
    std::vector<std::string> require_context_tiers)
    : ToolBase(std::move(def)), tier_names_(tier_names),
      require_context_tiers_(std::move(require_context_tiers)) {
 
    auto schema = nlohmann::json::parse(definition_.input_schema);
    schema["properties"]["stages"]["items"]["enum"] = tier_names;
    definition_.input_schema = schema.dump();
 
    logger->info("[pipeline] patched enum with {} tiers",
                 tier_names.size());
}
 
static std::string pipeline_rejection(
    const std::vector<std::string>& stages,
    const std::vector<std::string>& tier_names,
    const std::vector<std::string>& require_context_tiers,
    size_t refs) {
    std::string err;
    if (stages.size() < 2) {
        logger->warn("[pipeline] rejected: fewer than 2 stages");
        err = tool_error_json("too_few_stages", "pipeline requires at least 2 stages");
    }
    for (const auto& s : stages) {
        if (!err.empty()) { break; }
        if (std::find(tier_names.begin(), tier_names.end(), s)
            == tier_names.end()) {
            logger->warn("[pipeline] invalid stage: '{}'", s);
            err = tool_error_json("unknown_stage", "unknown stage \"" + s
                + "\". Valid stages: " + nlohmann::json(tier_names).dump());
        } else if (refs == 0
                   && std::find(require_context_tiers.begin(),
                                require_context_tiers.end(), s)
                      != require_context_tiers.end()) {
            // gh#162: one context list seeds every stage, so a stage that
            // requires context refuses the whole pipeline — before any
            // stage runs, not after the first has burned its turns.
            logger->warn("[pipeline] refused: stage '{}' requires context", s);
            err = tool_error_json("requires_context", "stage \"" + s
                + "\" requires context. Re-issue entropic.pipeline with a "
                "`context` array naming at least one file path the stages "
                "should read.");
        }
    }
    return err;
}
 
ServerResponse PipelineTool::execute(const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json);
    auto stages = args.at("stages").get<std::vector<std::string>>();
    std::string task = args.at("task").get<std::string>();
 
    nlohmann::json result;
    result["action"] = "pipeline";
    result["stages"] = stages;
    result["task"] = task;
    auto refs = carry_context(args, result);  // gh#162
 
    auto rejection = pipeline_rejection(
        stages, tier_names_, require_context_tiers_, refs);
    if (!rejection.empty()) {
        return {rejection, {}};
    }
 
    logger->info("[pipeline] stages={} task='{}' context={}",
                 stages.size(), task, refs);
 
    Directive pipeline_d;
    pipeline_d.type = ENTROPIC_DIRECTIVE_PIPELINE;
 
    Directive stop_d;
    stop_d.type = ENTROPIC_DIRECTIVE_STOP_PROCESSING;
 
    return {result.dump(), {pipeline_d, stop_d}};
}
 
// ── CompleteTool ────────────────────────────────────────────────
 
class CompleteTool : public ToolBase {
public:
    explicit CompleteTool(ToolDefinition def)
        : ToolBase(std::move(def)) {}
 
    ServerResponse execute(const std::string& args_json) override;
};
 
ServerResponse CompleteTool::execute(const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json);
    std::string summary = args.at("summary").get<std::string>();
    bool coverage_gap = args.value("coverage_gap", false);
    std::string gap_description =
        args.value("gap_description", std::string{});
    std::vector<std::string> suggested;
    if (args.contains("suggested_files")
        && args["suggested_files"].is_array()) {
        suggested = args["suggested_files"]
            .get<std::vector<std::string>>();
    }
 
    // Issue #10 (v2.1.4): coverage_gap=true REQUIRES a non-empty
    // gap_description so the lead context's [COVERAGE GAP] message
    // tells the next specialist what to fill in. An empty
    // gap_description with coverage_gap=true would be a bare
    // "I don't know" with no signal — refuse it at the tool boundary.
    if (coverage_gap && gap_description.empty()) {
        nlohmann::json err;
        err["error"] = "missing_gap_description";
        err["message"] =
            "coverage_gap=true requires a non-empty gap_description "
            "(what's missing from this answer and why).";
        return {err.dump(), {}};
    }
 
    logger->info("[complete] summary='{}' coverage_gap={} "
                 "gap_description_len={} suggested_files={}",
                 summary, coverage_gap,
                 gap_description.size(), suggested.size());
 
    nlohmann::json result;
    result["action"] = "complete";
    result["summary"] = entropic::mcp::sanitize_utf8(summary);
    result["coverage_gap"] = coverage_gap;
    result["gap_description"] = entropic::mcp::sanitize_utf8(gap_description);
    result["suggested_files"] = suggested;
 
    Directive complete_d;
    complete_d.type = ENTROPIC_DIRECTIVE_COMPLETE;
 
    Directive stop_d;
    stop_d.type = ENTROPIC_DIRECTIVE_STOP_PROCESSING;
 
    return {result.dump(), {complete_d, stop_d}};
}
 
// ── PhaseChangeTool ─────────────────────────────────────────────
 
class PhaseChangeTool : public ToolBase {
public:
    PhaseChangeTool();
 
    ServerResponse execute(const std::string& args_json) override;
};
 
static ToolDefinition phase_change_definition() {
    ToolDefinition def;
    def.name = "phase_change";
    def.description = "Switch inference phase";
    def.input_schema =
        R"({"type":"object","properties":{"phase":{"type":"string"}},"required":["phase"]})";
    def.output_schema =
        R"({"type":"object","required":["action","phase"],"properties":{"action":{"enum":["phase_change"]},"phase":{"type":"string","description":"the phase requested"}}})";
    def.description += render_response_format(def.output_schema);
    return def;
}
 
PhaseChangeTool::PhaseChangeTool()
    : ToolBase(phase_change_definition()) {}
 
ServerResponse PhaseChangeTool::execute(
    const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json);
    std::string phase = args.at("phase").get<std::string>();
 
    logger->info("[phase_change] phase='{}'", phase);
 
    nlohmann::json result;
    result["action"] = "phase_change";
    result["phase"] = phase;
 
    Directive phase_d;
    phase_d.type = ENTROPIC_DIRECTIVE_PHASE_CHANGE;
 
    return {result.dump(), {phase_d}};
}
 
// ── PruneContextTool ────────────────────────────────────────────
 
class PruneContextTool : public ToolBase {
public:
    explicit PruneContextTool(ToolDefinition def)
        : ToolBase(std::move(def)) {}
 
    ServerResponse execute(const std::string& args_json) override;
};
 
ServerResponse PruneContextTool::execute(
    const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json);
 
    static constexpr int default_keep = 2;
    int keep_recent = args.value("keep_recent", default_keep);
 
    logger->info("[prune_context] keep_recent={}", keep_recent);
 
    nlohmann::json result;
    result["action"] = "prune_context";
    result["keep_recent"] = keep_recent;
 
    Directive prune_d;
    prune_d.type = ENTROPIC_DIRECTIVE_PRUNE_MESSAGES;
 
    return {result.dump(), {prune_d}};
}
 
// ── DiagnoseTool ────────────────────────────────────────────────
 
class DiagnoseTool : public ToolBase {
public:
    explicit DiagnoseTool(ToolDefinition def)
        : ToolBase(std::move(def)) {}
 
    ServerResponse execute(const std::string& args_json) override;
 
    MCPAccessLevel required_access_level() const override {
        return MCPAccessLevel::READ;
    }
 
    void set_provider(const entropic_state_provider_t* p) {
        provider_ = p;
    }
 
private:
    const entropic_state_provider_t* provider_ = nullptr;
};
 
static std::string call_provider(
    char* (*fn)(void*), void* ud) {
    if (fn == nullptr) {
        return "{}";
    }
    char* raw = fn(ud);
    if (raw == nullptr) {
        return "{}";
    }
    std::string result(raw);
    free(raw);
    return result;
}
 
static std::string call_history_provider(
    char* (*fn)(int, void*), int max_entries, void* ud) {
    if (fn == nullptr) {
        return "[]";
    }
    char* raw = fn(max_entries, ud);
    if (raw == nullptr) {
        return "[]";
    }
    std::string result(raw);
    free(raw);
    return result;
}
 
static std::string call_docs_provider(
    char* (*fn)(const char*, void*),
    const char* section, void* ud) {
    if (fn == nullptr) {
        return "";
    }
    char* raw = fn(section, ud);
    if (raw == nullptr) {
        return "";
    }
    std::string result(raw);
    free(raw);
    return result;
}
 
static nlohmann::json build_snapshot(
    const entropic_state_provider_t& p,
    bool include_docs, int history_limit) {
 
    nlohmann::json snap;
 
    auto now = std::chrono::system_clock::now();
    auto ms = std::chrono::duration_cast<
        std::chrono::milliseconds>(
        now.time_since_epoch()).count();
    snap["snapshot_timestamp_ms"] = ms;
 
    snap["engine"] = nlohmann::json::parse(
        call_provider(p.get_state, p.user_data));
    snap["config"] = nlohmann::json::parse(
        call_provider(p.get_config, p.user_data));
    snap["identities"] = nlohmann::json::parse(
        call_provider(p.get_identities, p.user_data));
    snap["tools"] = nlohmann::json::parse(
        call_provider(p.get_tools, p.user_data));
    snap["history"] = nlohmann::json::parse(
        call_history_provider(
            p.get_history, history_limit, p.user_data));
    snap["metrics"] = nlohmann::json::parse(
        call_provider(p.get_metrics, p.user_data));
 
    if (include_docs) {
        snap["docs"] = call_docs_provider(
            p.get_docs, nullptr, p.user_data);
    } else {
        snap["docs"] = nullptr;
    }
    return snap;
}
 
ServerResponse DiagnoseTool::execute(const std::string& args_json) {
    if (provider_ == nullptr) {
        logger->error("[diagnose] no state provider set");
        return {tool_error_json("provider_unavailable",
                           "engine state provider not configured"), {}};
    }
 
    auto args = nlohmann::json::parse(args_json);
    bool include_docs = args.value("include_docs", false);
    int history_limit = args.value("history_limit", 20);
 
    logger->info("[diagnose] include_docs={} history_limit={}",
                 include_docs, history_limit);
 
    auto snap = build_snapshot(
        *provider_, include_docs, history_limit);
    return {snap.dump(), {}};
}
 
// ── InspectTool ─────────────────────────────────────────────────
 
class InspectTool : public ToolBase {
public:
    explicit InspectTool(ToolDefinition def)
        : ToolBase(std::move(def)) {}
 
    ServerResponse execute(const std::string& args_json) override;
 
    MCPAccessLevel required_access_level() const override {
        return MCPAccessLevel::READ;
    }
 
    void set_provider(const entropic_state_provider_t* p) {
        provider_ = p;
    }
 
private:
    const entropic_state_provider_t* provider_ = nullptr;
};
 
// ── ContextInspectTool ──────────────────────────────────────────
 
class ContextInspectTool : public ToolBase {
public:
    explicit ContextInspectTool(ToolDefinition def)
        : ToolBase(std::move(def)) {}
 
    ServerResponse execute(const std::string& args_json) override;
 
    MCPAccessLevel required_access_level() const override {
        return MCPAccessLevel::READ;
    }
 
    void set_provider(const entropic_state_provider_t* p) {
        provider_ = p;
    }
 
private:
    const entropic_state_provider_t* provider_ = nullptr;
};
 
static std::vector<std::string> collect_object_keys(
    const nlohmann::json& j) {
    std::vector<std::string> keys;
    for (auto it = j.begin(); it != j.end(); ++it) {
        keys.push_back(it.key());
    }
    return keys;
}
 
static std::vector<std::string> collect_array_names(
    const nlohmann::json& j) {
    std::vector<std::string> names;
    for (const auto& item : j) {
        if (item.is_object() && item.contains("name")) {
            names.push_back(item["name"].get<std::string>());
        }
    }
    return names;
}
 
static std::string list_available_keys(const nlohmann::json& j) {
    auto keys = j.is_object() ? collect_object_keys(j)
                               : collect_array_names(j);
    std::string result;
    for (const auto& k : keys) {
        if (!result.empty()) { result += ", "; }
        result += k;
    }
    return result;
}
 
static std::string filter_json_by_key(
    const std::string& json_str,
    const std::string& key,
    const std::string& label,
    nlohmann::json& data) {
    auto j = nlohmann::json::parse(json_str);
    if (j.is_object() && j.contains(key)) {
        data = j[key];
    } else if (j.is_array()) {
        for (const auto& item : j) {
            if (item.value("name", "") == key) { data = item; }
        }
    }
    return data.is_null()
        ? tool_error_json("not_found", label + " '" + key
              + "' not found. Available: " + list_available_keys(j))
        : std::string{};
}
 
static std::string inspect_filterable(
    char* (*fn)(void*), void* ud,
    const std::string& key, const std::string& label,
    nlohmann::json& data) {
    auto raw = call_provider(fn, ud);
    std::string err;
    if (key.empty()) {
        data = nlohmann::json::parse(raw);
    } else {
        err = filter_json_by_key(raw, key, label, data);
    }
    return err;
}
 
static bool dispatch_simple_target(
    const entropic_state_provider_t& p,
    const std::string& target,
    const std::string& key,
    nlohmann::json& data) {
    bool handled = true;
    if (target == "state") {
        data = nlohmann::json::parse(call_provider(p.get_state, p.user_data));
    } else if (target == "metrics") {
        data = nlohmann::json::parse(call_provider(p.get_metrics, p.user_data));
    } else if (target == "history") {
        int limit = key.empty() ? 10 : std::atoi(key.c_str());
        data = nlohmann::json::parse(
            call_history_provider(p.get_history, limit, p.user_data));
    } else if (target == "docs") {
        const char* sec = key.empty() ? nullptr : key.c_str();
        data = call_docs_provider(p.get_docs, sec, p.user_data);
    } else {
        handled = false;
    }
    return handled;
}
 
 
 
static std::string dispatch_inspect(
    const entropic_state_provider_t& p,
    const std::string& target,
    const std::string& key,
    nlohmann::json& data) {
    std::string err;
    if (target == "config") {
        err = inspect_filterable(p.get_config, p.user_data, key, "config section", data);
    } else if (target == "identity") {
        err = inspect_filterable(p.get_identities, p.user_data, key, "identity", data);
    } else if (target == "tool") {
        err = inspect_filterable(p.get_tools, p.user_data, key, "tool", data);
    } else if (!dispatch_simple_target(p, target, key, data)) {
        err = tool_error_json("unknown_target", "unknown target '" + target
            + "'. Supported: config, identity, tool, state, metrics, "
              "history, docs");
    }
    return err;
}
 
ServerResponse InspectTool::execute(const std::string& args_json) {
    if (provider_ == nullptr) {
        logger->error("[inspect] no state provider set");
        return {tool_error_json("provider_unavailable",
                           "engine state provider not configured"), {}};
    }
    auto args = nlohmann::json::parse(args_json, nullptr, false);
    if (args.is_discarded() || !args.is_object()) {
        args = nlohmann::json::object();
    }
    std::string target = args.value("target", "");
    std::string key = args.value("key", "");
    if (target.empty()) {
        logger->info("[inspect] full state dump (no target)");
        target = "state";
        key.clear();
    }
    logger->info("[inspect] target='{}' key='{}'", target, key);
    nlohmann::json data;
    auto err = dispatch_inspect(*provider_, target, key, data);
    nlohmann::json result;
    result["target"] = target;
    result["data"] = data;
    if (!key.empty()) { result["key"] = key; }
    return {err.empty() ? result.dump() : err, {}};
}
 
ServerResponse ContextInspectTool::execute(
    const std::string& args_json) {
    if (provider_ == nullptr) {
        logger->error("[context_inspect] no state provider set");
        return {tool_error_json("provider_unavailable",
                           "engine state provider not configured"), {}};
    }
 
    auto args = nlohmann::json::parse(args_json, nullptr, false);
    // gh#143 (v2.12.0): coerce a non-object (including `null`) to {} so an
    // argument-free call takes the defaults instead of throwing.
    if (args.is_discarded() || !args.is_object()) {
        args = nlohmann::json::object();
    }
    int max_messages = args.value("max_messages", 0);
 
    logger->info("[context_inspect] max_messages={}", max_messages);
    nlohmann::json result;
    result["messages"] = nlohmann::json::parse(call_history_provider(
        provider_->get_history, max_messages, provider_->user_data));
    return {result.dump(), {}};
}
 
// ── FollowupTool (gh#32, v2.1.6) ────────────────────────────────
 
class FollowupTool : public ToolBase {
public:
    explicit FollowupTool(ToolDefinition def)
        : ToolBase(std::move(def)) {}
 
    ServerResponse execute(const std::string& args_json) override;
 
    MCPAccessLevel required_access_level() const override {
        return MCPAccessLevel::READ;
    }
 
    void set_provider(const entropic_state_provider_t* p) {
        provider_ = p;
    }
 
private:
    const entropic_state_provider_t* provider_ = nullptr;
};
 
static std::string followup_results(const char* raw) {
    auto rows = nlohmann::json::parse(raw == nullptr ? "[]" : raw, nullptr, false);
    nlohmann::json results = nlohmann::json::array();
    for (const auto& r : rows.is_array() ? rows : nlohmann::json::array()) {
        nlohmann::json rec;
        rec["delegation_id"] = r.value("delegation_id", "");
        rec["target_tier"] = r.value("target_tier", "");
        rec["summary"] = r.value("summary", "");
        rec["completed_at"] = r.value("completed_at", "");
        results.push_back(std::move(rec));
    }
    nlohmann::json out;
    out["results"] = std::move(results);
    return out.dump();
}
 
ServerResponse FollowupTool::execute(const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json, nullptr, false);
    std::string body;
    if (args.is_discarded() || !args.is_object()
        || args.value("query", "").empty()) {
        body = tool_error_json("invalid_args", "'query' is required and must be non-empty");
    } else if (provider_ == nullptr || provider_->search_delegations == nullptr) {
        logger->warn("[followup] no search_delegations provider configured");
        body = tool_error_json("storage_unavailable", "delegation storage not available");
    } else {
        std::string query = args.value("query", "");
        int max_results = args.value("max_results", 3);
        char* raw = provider_->search_delegations(
            query.c_str(), max_results, provider_->user_data);
        body = followup_results(raw);
        std::free(raw);
        logger->info("[followup] query='{}' max_results={} -> {}",
                     query, max_results, body);
    }
    return {body, {}};
}
 
// ── ResumeDelegationTool (gh#32, v2.1.6) ────────────────────────
 
class ResumeDelegationTool : public ToolBase {
public:
    ResumeDelegationTool(ToolDefinition def,
                         const std::vector<std::string>& tier_names)
        : ToolBase(std::move(def)) {
        auto schema = nlohmann::json::parse(definition_.input_schema);
        schema["properties"]["target"]["enum"] = tier_names;
        definition_.input_schema = schema.dump();
    }
 
    ServerResponse execute(const std::string& args_json) override;
};
 
ServerResponse ResumeDelegationTool::execute(const std::string& args_json) {
    auto args = nlohmann::json::parse(args_json, nullptr, false);
    if (args.is_discarded() || !args.is_object()) {
        return {tool_error_json("invalid_args", "an arguments object is required"), {}};
    }
    std::string delegation_id = args.value("delegation_id", "");
    std::string target = args.value("target", "");
    std::string task = args.value("task", "");
    int max_turns = args.value("max_turns", -1);
    // gh#162: an id OR a tier. Reaching this tool used to cost a followup
    // round trip on a slow local model before any work started.
    if (task.empty() || (delegation_id.empty() && target.empty())) {
        return {tool_error_json("invalid_args",
                           "'task' and one of 'delegation_id' or 'target' are required"),
                {}};
    }
    bool by_target = delegation_id.empty();
    logger->info("[resume_delegation] id='{}' target='{}' task='{}' "
                 "max_turns={}", delegation_id, target, task, max_turns);
 
    nlohmann::json result;
    result["action"] = "resume_delegation";
    result["delegation_id"] = delegation_id;
    result["target"] = target;
    result["resume_by_target"] = by_target;
    result["task"] = task;
    result["max_turns"] = max_turns;
 
    Directive delegate_d;
    delegate_d.type = ENTROPIC_DIRECTIVE_DELEGATE;
    Directive stop_d;
    stop_d.type = ENTROPIC_DIRECTIVE_STOP_PROCESSING;
    return {result.dump(), {delegate_d, stop_d}};
}
 
// ── EntropicServer ──────────────────────────────────────────────
 
int EntropicServer::register_core_tools(
    const std::string& tools_dir) {
    auto todo_def = load_tool_definition(
        "todo", "entropic", tools_dir);
    todo_ = std::make_unique<TodoTool>(std::move(todo_def));
    register_tool(todo_.get());
 
    auto complete_def = load_tool_definition(
        "complete", "entropic", tools_dir);
    complete_ = std::make_unique<CompleteTool>(
        std::move(complete_def));
    register_tool(complete_.get());
 
    phase_change_ = std::make_unique<PhaseChangeTool>();
    register_tool(phase_change_.get());
 
    auto prune_def = load_tool_definition(
        "prune_context", "entropic", tools_dir);
    prune_context_ = std::make_unique<PruneContextTool>(
        std::move(prune_def));
    register_tool(prune_context_.get());
 
    return 4;
}
 
int EntropicServer::register_delegation_tools(
    const std::string& tools_dir,
    const std::vector<std::string>& tier_names,
    const std::vector<std::string>& require_context_tiers) {
    if (tier_names.empty()) {
        return 0;
    }
    auto delegate_def = load_tool_definition(
        "delegate", "entropic", tools_dir);
    delegate_ = std::make_unique<DelegateTool>(
        std::move(delegate_def), tier_names, require_context_tiers);
    register_tool(delegate_.get());
 
    auto pipeline_def = load_tool_definition(
        "pipeline", "entropic", tools_dir);
    pipeline_ = std::make_unique<PipelineTool>(
        std::move(pipeline_def), tier_names, require_context_tiers);
    register_tool(pipeline_.get());
 
    // gh#32 (v2.1.6): resume_delegation lives alongside delegate
    // because it produces the same directive kind (resume-flavored).
    auto resume_def = load_tool_definition(
        "resume_delegation", "entropic", tools_dir);
    resume_delegation_ = std::make_unique<ResumeDelegationTool>(
        std::move(resume_def), tier_names);
    register_tool(resume_delegation_.get());
 
    return 3;
}
 
int EntropicServer::register_introspection_tools(
    const std::string& tools_dir) {
    diagnose_ = std::make_unique<DiagnoseTool>(
        load_tool_definition("diagnose", "entropic", tools_dir));
    register_tool(diagnose_.get());
 
    inspect_ = std::make_unique<InspectTool>(
        load_tool_definition("inspect", "entropic", tools_dir));
    register_tool(inspect_.get());
 
    context_inspect_ = std::make_unique<ContextInspectTool>(
        load_tool_definition("context_inspect", "entropic", tools_dir));
    register_tool(context_inspect_.get());
 
    // gh#32 (v2.1.6): followup is read-only and consumes the same
    // state_provider plumbing as diagnose/inspect.
    followup_ = std::make_unique<FollowupTool>(
        load_tool_definition("followup", "entropic", tools_dir));
    register_tool(followup_.get());
 
    return 4;
}
 
EntropicServer::EntropicServer(
    const std::vector<std::string>& tier_names,
    const std::string& data_dir,
    const std::vector<std::string>& require_context_tiers)
    : MCPServerBase("entropic") {
 
    std::string tools_dir = data_dir + "/tools";
    int count = register_core_tools(tools_dir);
    count += register_delegation_tools(tools_dir, tier_names,
                                       require_context_tiers);
    count += register_introspection_tools(tools_dir);
 
    logger->info("EntropicServer initialized with {} tools "
                 "({} tiers)", count, tier_names.size());
}
 
EntropicServer::~EntropicServer() = default;
 
bool EntropicServer::skip_duplicate_check(
    const std::string& tool_name) const {
    return tool_name == "delegate" || tool_name == "pipeline";
}
 
void EntropicServer::set_state_provider(
    const entropic_state_provider_t& provider) {
    state_provider_ = provider;
    diagnose_->set_provider(&state_provider_);
    inspect_->set_provider(&state_provider_);
    context_inspect_->set_provider(&state_provider_);
    if (followup_) {
        followup_->set_provider(&state_provider_);
    }
    logger->info("State provider set for introspection tools");
}
 
bool EntropicServer::release_session(const std::string& key) {
    return todo_->release(key);
}
 
std::size_t EntropicServer::session_count() const {
    return todo_->session_count();
}
 
} // namespace entropic