delegation.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#include <entropic/core/delegation.h>
#include <entropic/core/engine_types.h>
#include <entropic/mcp/utf8_sanitize.h>
#include <entropic/types/logging.h>
 
#include <nlohmann/json.hpp>
 
#include <algorithm>
 
static auto logger = entropic::log::get("core.delegation");
 
namespace entropic {
 
// ── Construction ─────────────────────────────────────────
 
DelegationManager::DelegationManager(
    RunChildLoopFn run_child,
    void* run_child_data,
    const TierResolutionInterface& tier_resolution,
    const std::filesystem::path& repo_dir,
    SandboxManager* sandbox_mgr)
    : run_child_fn_(run_child),
      run_child_data_(run_child_data),
      tier_res_(tier_resolution),
      sandbox_mgr_(sandbox_mgr),
      repo_dir_(repo_dir) {
}
 
void DelegationManager::set_todo_callbacks(const TodoCallbacks& callbacks) {
    todo_callbacks_ = callbacks;
}
 
void DelegationManager::set_dir_swap(
    ScopedSandbox::SwapDirFn swap_fn, void* user_data) {
    swap_dir_fn_ = swap_fn;
    swap_dir_data_ = user_data;
}
 
void DelegationManager::set_storage(const StorageInterface* storage) {
    storage_ = storage;
}
 
void DelegationManager::set_delegation_callbacks(
    ent_decision_t (*on_start)(const ent_delegation_request_t*, void*),
    ent_decision_t (*on_complete)(const ent_delegation_result_t*, void*),
    void* user_data) {
    delegation_start_cb_ = on_start;
    delegation_complete_cb_ = on_complete;
    delegation_cb_data_ = user_data;
}
 
ent_decision_t DelegationManager::fire_start_cb(
    const std::string& delegation_id,
    const std::string& target_tier,
    const std::string& task,
    int depth,
    bool is_pipeline) {
    if (delegation_start_cb_ == nullptr) {
        return ENT_DECISION_ACCEPT;
    }
    ent_delegation_request_t req{};
    req.delegation_id = delegation_id.c_str();
    req.target_tier  = target_tier.c_str();
    req.task         = task.c_str();
    req.depth        = depth;
    req.is_pipeline  = is_pipeline ? 1 : 0;
    // Exception shield: per docs/architecture-cpp.md design rule #6,
    // exceptions do not cross .so boundaries. A buggy consumer
    // throwing a C++ exception out of the callback would otherwise
    // unwind through the engine's stack with undefined cleanup. Fail
    // safe by treating a throw as REJECT (gh#29 hardening).
    try {
        return delegation_start_cb_(&req, delegation_cb_data_);
    } catch (...) {
        logger->warn("delegation_start_cb threw for {}; treating as "
                     "REJECT (gh#29 exception shield)",
                     delegation_id);
        return ENT_DECISION_REJECT;
    }
}
 
static ent_delegation_result_t build_delegation_result_struct(
    const SandboxInfo& sb_info, const SandboxResult& sandbox_result,
    const DelegationResult& result,
    const std::vector<const char*>& files_c, size_t files_len) {
    ent_delegation_result_t res{};
    res.delegation_id     = sb_info.delegation_id.c_str();
    res.target_tier       = result.target_tier.c_str();
    res.success           = result.success ? 1 : 0;
    res.summary           = result.summary.c_str();
    res.patch             = sandbox_result.patch.c_str();
    res.patch_len         = sandbox_result.patch.size();
    res.files_touched     = files_c.data();
    res.files_touched_len = files_len;
    return res;
}
 
void DelegationManager::deliver_sandbox_result(
    const SandboxInfo& sb_info,
    const SandboxResult& sandbox_result,
    const DelegationResult& result) {
 
    if (delegation_complete_cb_ == nullptr) {
        persist_pending_patch(sb_info, sandbox_result,
                              "no complete callback registered");
        return;
    }
 
    std::vector<std::string> files_owned;
    files_owned.reserve(sandbox_result.files_touched.size());
    for (const auto& p : sandbox_result.files_touched) {
        files_owned.push_back(p.string());
    }
    std::vector<const char*> files_c;
    files_c.reserve(files_owned.size() + 1);
    for (const auto& s : files_owned) { files_c.push_back(s.c_str()); }
    files_c.push_back(nullptr);
 
    ent_delegation_result_t res = build_delegation_result_struct(
        sb_info, sandbox_result, result, files_c, files_owned.size());
 
    ent_decision_t decision =
        invoke_complete_cb(res, sb_info.delegation_id);
    if (decision == ENT_DECISION_REJECT) {
        persist_pending_patch(sb_info, sandbox_result,
                              "consumer REJECTED");
    } else {
        logger->info("Delegation {}: consumer ACCEPTED ({} files, "
                     "{} bytes)",
                     sb_info.delegation_id,
                     sandbox_result.files_touched.size(),
                     sandbox_result.patch.size());
    }
}
 
ent_decision_t DelegationManager::invoke_complete_cb(
    const ent_delegation_result_t& res, const std::string& delegation_id) {
    // Exception shield: a buggy consumer must never unwind through the
    // engine. Treat throw as REJECT so the patch is preserved on disk
    // for inspection (gh#29 hardening — same policy as fire_start_cb).
    try {
        return delegation_complete_cb_(&res, delegation_cb_data_);
    } catch (...) {
        logger->warn("delegation_complete_cb threw for {}; treating as "
                     "REJECT (patch preserved to pending/)", delegation_id);
        return ENT_DECISION_REJECT;
    }
}
 
void DelegationManager::persist_pending_patch(
    const SandboxInfo& sb_info,
    const SandboxResult& sandbox_result,
    const char* reason) {
    auto path = sandbox_mgr_->write_pending_patch(
        sb_info.delegation_id, sandbox_result.patch);
    if (path) {
        logger->warn("Delegation {}: {}; patch saved to {} "
                     "({} files, {} bytes)",
                     sb_info.delegation_id, reason, path->string(),
                     sandbox_result.files_touched.size(),
                     sandbox_result.patch.size());
    }
}
 
// ── Single delegation ────────────────────────────────────
 
std::optional<DelegationResult>
DelegationManager::check_delegation_preconditions(
    const ChildContextInfo& info,
    const std::string& target_tier,
    const std::string& task,
    const std::string& del_id,
    int depth,
    std::optional<SandboxInfo>& sb_info) {
    std::optional<DelegationResult> early;
    if (!info.valid) {
        logger->error("Tier '{}' not found", target_tier);
        early = DelegationResult{
            "Unknown tier: " + target_tier, false, target_tier, task};
    } else if (fire_start_cb(del_id, target_tier, task, depth, false)
               == ENT_DECISION_REJECT) {
        logger->info("Delegation {} ({}) rejected by start callback",
                     del_id, target_tier);
        early = DelegationResult{
            "Delegation rejected by consumer", false, target_tier, task};
    } else if (sandbox_mgr_ != nullptr) {
        sb_info = sandbox_mgr_->create_sandbox(del_id);
        if (!sb_info.has_value()) {
            // gh#33 bug 2 (v2.1.6): pre-2.1.6 a failed create_sandbox
            // silently fell through to running the child against the
            // parent's cwd and surfaced an opaque
            // "(No response from delegate)" on later failure. The
            // sandbox-unavailable mode is now consumer-visible.
            logger->error(
                "Delegation {} ({}): session sandbox unavailable",
                del_id, target_tier);
            early = DelegationResult{
                "(DELEGATION FAILED: session sandbox unavailable)",
                false, target_tier, task};
        }
    }
    return early;
}
 
DelegationResult DelegationManager::execute_delegation(
    LoopContext& parent_ctx,
    const std::string& target_tier,
    const std::string& task,
    std::optional<int> max_turns) {
 
    logger->info("Delegation: target_tier='{}', task='{}', depth={}",
                 target_tier, task,
                 parent_ctx.delegation_depth + 1);
    auto info = tier_res_.resolve_tier
        ? tier_res_.resolve_tier(target_tier, tier_res_.user_data)
        : ChildContextInfo{};
 
    std::string del_id =
        "d" + std::to_string(parent_ctx.delegation_depth + 1);
    std::optional<SandboxInfo> sb_info;
    if (auto early = check_delegation_preconditions(
            info, target_tier, task, del_id,
            parent_ctx.delegation_depth + 1, sb_info)) {
        return *early;
    }
 
    auto child_ctx = build_child_context(parent_ctx, info, task);
    child_ctx.locked_tier = target_tier;
 
    DelegationResult result;
 
    if (sb_info && swap_dir_fn_ != nullptr) {
        ScopedSandbox scope(swap_dir_fn_, swap_dir_data_,
                            sb_info->path, repo_dir_);
        result = run_child(child_ctx, target_tier, task, max_turns);
    } else {
        result = run_child(child_ctx, target_tier, task, max_turns);
    }
 
    finalize_sandbox_for(sb_info, result);
    return result;
}
 
LoopContext DelegationManager::build_resumed_child_context(
        const LoopContext& parent_ctx,
        const ChildContextInfo& info,
        const std::string& target_tier,
        const std::string& task,
        std::vector<Message> seed_history) {
    LoopContext child_ctx;
    child_ctx.delegation_depth = parent_ctx.delegation_depth + 1;
    child_ctx.delegation_ancestor_tiers =
        parent_ctx.delegation_ancestor_tiers;
    child_ctx.delegation_ancestor_tiers.push_back(target_tier);
    child_ctx.parent_conversation_id = parent_ctx.conversation_id;
    child_ctx.all_tools = info.tools;
    child_ctx.active_phase = "default";
    child_ctx.locked_tier = target_tier;
    child_ctx.messages = std::move(seed_history);
    bool has_system = !child_ctx.messages.empty()
                       && child_ctx.messages.front().role == "system";
    if (!has_system && !info.system_prompt.empty()) {
        Message sys;
        sys.role = "system";
        sys.content = info.system_prompt;
        child_ctx.messages.insert(child_ctx.messages.begin(),
                                  std::move(sys));
    }
    Message user;
    user.role = "user";
    user.content = task;
    if (!info.completion_instructions.empty()) {
        user.content += "\n\n" + info.completion_instructions;
    }
    child_ctx.messages.push_back(std::move(user));
    return child_ctx;
}
 
DelegationResult DelegationManager::execute_resume_delegation(
    LoopContext& parent_ctx,
    const std::string& target_tier,
    const std::string& task,
    std::vector<Message> seed_history,
    std::optional<int> max_turns) {
 
    logger->info("Resume delegation: target_tier='{}' task='{}' "
                 "history_messages={}",
                 target_tier, task, seed_history.size());
    auto info = tier_res_.resolve_tier
        ? tier_res_.resolve_tier(target_tier, tier_res_.user_data)
        : ChildContextInfo{};
 
    std::string del_id =
        "d" + std::to_string(parent_ctx.delegation_depth + 1) + "r";
    std::optional<SandboxInfo> sb_info;
    if (auto early = check_delegation_preconditions(
            info, target_tier, task, del_id,
            parent_ctx.delegation_depth + 1, sb_info)) {
        return *early;
    }
 
    auto child_ctx = build_resumed_child_context(
        parent_ctx, info, target_tier, task, std::move(seed_history));
 
    DelegationResult result;
    if (sb_info && swap_dir_fn_ != nullptr) {
        ScopedSandbox scope(swap_dir_fn_, swap_dir_data_,
                            sb_info->path, repo_dir_);
        result = run_child(child_ctx, target_tier, task, max_turns);
    } else {
        result = run_child(child_ctx, target_tier, task, max_turns);
    }
    finalize_sandbox_for(sb_info, result);
    return result;
}
 
// ── Pipeline ─────────────────────────────────────────────
 
static std::string pipeline_context(
    size_t stage_idx, size_t total,
    const std::vector<std::string>& stages,
    const std::string& prior_output) {
    std::string ctx = "[PIPELINE CONTEXT]\n";
    ctx += "Stage " + std::to_string(stage_idx + 1) +
           " of " + std::to_string(total) + "\n";
    ctx += "Role: " + stages[stage_idx] + "\n";
    ctx += "Stay within your role. Do not perform work "
           "outside your stage's responsibility.\n";
    if (!prior_output.empty()) {
        ctx += "\n[PRIOR STAGE OUTPUT]\n";
        ctx += prior_output;
        ctx += "\n";
    }
    ctx += "\n";
    return ctx;
}
 
DelegationResult DelegationManager::execute_pipeline(
    LoopContext& parent_ctx,
    const std::vector<std::string>& stages,
    const std::string& task,
    std::vector<DelegationResult>& stage_log) {
 
    logger->info("Pipeline: {} stages, task='{}'", stages.size(), task);
 
    // gh#29 (v2.1.5): single pre-flight gate for the whole pipeline.
    auto first = stages.empty() ? std::string{} : stages.front();
    if (fire_start_cb("pipeline", first, task,
                      parent_ctx.delegation_depth + 1, true)
        == ENT_DECISION_REJECT) {
        logger->info("Pipeline rejected by start callback");
        return {"Pipeline rejected by consumer", false, first, task};
    }
 
    // Shared sandbox for the entire pipeline (gh#29). Each stage runs
    // inside the same directory so later stages observe earlier stages'
    // file edits — preserving the v2.1.4 forward-carry behavior.
    std::optional<SandboxInfo> shared_sb;
    if (sandbox_mgr_ != nullptr) {
        shared_sb = sandbox_mgr_->create_sandbox("pipeline");
        if (!shared_sb.has_value()) {
            // gh#33 bug 2 (v2.1.6): see execute_delegation comment.
            logger->error(
                "Pipeline ({} stages): session sandbox unavailable",
                stages.size());
            return {"(DELEGATION FAILED: session sandbox unavailable)",
                    false, first, task};
        }
    }
 
    DelegationResult last_result;
    last_result.task = task;
 
    for (size_t i = 0; i < stages.size(); ++i) {
        if (!run_pipeline_stage(parent_ctx, stages, i, task,
                                shared_sb, stage_log, last_result)) {
            break;
        }
    }
 
    finalize_sandbox_for(shared_sb, last_result);
    return last_result;
}
 
bool DelegationManager::run_pipeline_stage(
    LoopContext& parent_ctx,
    const std::vector<std::string>& stages,
    size_t stage_idx,
    const std::string& task,
    const std::optional<SandboxInfo>& shared_sb,
    std::vector<DelegationResult>& stage_log,
    DelegationResult& last_result) {
 
    const auto& tier_name = stages[stage_idx];
    std::string prior = (stage_idx == 0) ? std::string{} : last_result.summary;
    std::string stage_task =
        pipeline_context(stage_idx, stages.size(), stages, prior) + task;
 
    auto info = tier_res_.resolve_tier
        ? tier_res_.resolve_tier(tier_name, tier_res_.user_data)
        : ChildContextInfo{};
 
    if (!info.valid) {
        logger->error("Pipeline stage {}: tier '{}' not found",
                      stage_idx, tier_name);
        last_result.success = false;
        last_result.summary = "Unknown tier: " + tier_name;
        return false;
    }
 
    auto child_ctx = build_child_context(parent_ctx, info, stage_task);
    child_ctx.locked_tier = tier_name;
 
    if (shared_sb && swap_dir_fn_ != nullptr) {
        ScopedSandbox scope(swap_dir_fn_, swap_dir_data_,
                            shared_sb->path, repo_dir_);
        last_result = run_child(child_ctx, tier_name, stage_task,
                                std::nullopt);
    } else {
        last_result = run_child(child_ctx, tier_name, stage_task,
                                std::nullopt);
    }
 
    stage_log.push_back(last_result);
    logger->info("Pipeline stage {} ({}): {}", stage_idx, tier_name,
                 last_result.success ? "complete" : "failed");
    return last_result.success;
}
 
// ── Child context ────────────────────────────────────────
 
LoopContext DelegationManager::build_child_context(
    const LoopContext& parent_ctx,
    const ChildContextInfo& info,
    const std::string& task) {
 
    LoopContext child;
    child.delegation_depth = parent_ctx.delegation_depth + 1;
    // gh#48 (regression fix, v2.7.4): propagate the parent conversation id so
    // the storage create_delegation INSERT satisfies the delegations→
    // conversations FK. Without this the row is rejected, the delegations
    // table stays empty, and entropic.followup returns the no-matches
    // sentinel. (Present in build_resumed_child_context; lost here when the
    // child-context builders were extracted.)
    child.parent_conversation_id = parent_ctx.conversation_id;
    // P1-9: propagate ancestor chain + append parent tier so the
    // child can reject cycles (A→B→A) before executing.
    child.delegation_ancestor_tiers = parent_ctx.delegation_ancestor_tiers;
    if (!parent_ctx.locked_tier.empty()) {
        child.delegation_ancestor_tiers.push_back(parent_ctx.locked_tier);
    }
    child.locked_tier = info.system_prompt.empty()
        ? parent_ctx.locked_tier : "";
    child.all_tools = info.tools;
    child.active_phase = "default";
 
    // System prompt as first message
    Message sys;
    sys.role = "system";
    sys.content = info.system_prompt;
    child.messages.push_back(std::move(sys));
 
    // Task as user message (with completion instructions)
    std::string user_content = task;
    if (!info.completion_instructions.empty()) {
        user_content += "\n\n" + info.completion_instructions;
    }
    Message user;
    user.role = "user";
    user.content = std::move(user_content);
    child.messages.push_back(std::move(user));
 
    return child;
}
 
std::string DelegationManager::extract_summary(
    const LoopContext& child_ctx) const {
    // Prefer explicit completion summary
    auto it = child_ctx.metadata.find("explicit_completion_summary");
    if (it != child_ctx.metadata.end() && !it->second.empty()) {
        return mcp::sanitize_utf8(it->second);
    }
 
    // Fall back to last assistant message
    for (auto rit = child_ctx.messages.rbegin();
         rit != child_ctx.messages.rend(); ++rit) {
        if (rit->role == "assistant" && !rit->content.empty()) {
            return mcp::sanitize_utf8(rit->content);
        }
    }
 
    return "(No response from delegate)";
}
 
std::string DelegationManager::create_storage_record(
    LoopContext& child_ctx, const std::string& target_tier,
    const std::string& task, std::optional<int> max_turns) {
    if (!storage_ || !storage_->create_delegation) {
        return "";
    }
    std::string del_id, child_conv_id;
    auto src_tier = child_ctx.locked_tier.empty()
        ? "root" : child_ctx.locked_tier.c_str();
    storage_->create_delegation(
        child_ctx.parent_conversation_id.c_str(),
        src_tier, target_tier.c_str(), task.c_str(),
        max_turns.value_or(0), del_id, child_conv_id,
        storage_->user_data);
    child_ctx.conversation_id = child_conv_id;
    return del_id;
}
 
void DelegationManager::complete_storage_record(
    const std::string& delegation_id,
    const DelegationResult& result) {
    if (!storage_ || !storage_->complete_delegation
        || delegation_id.empty()) {
        return;
    }
    const char* status = result.success ? "completed" : "failed";
    storage_->complete_delegation(
        delegation_id.c_str(), status,
        result.summary.c_str(), storage_->user_data);
}
 
DelegationResult DelegationManager::run_child(
    LoopContext& child_ctx,
    const std::string& target_tier,
    const std::string& task,
    std::optional<int> max_turns) {
 
    // Save parent todo list
    std::string saved_todo;
    if (todo_callbacks_.save != nullptr) {
        saved_todo = todo_callbacks_.save(todo_callbacks_.user_data);
    }
    if (todo_callbacks_.install_fresh != nullptr) {
        todo_callbacks_.install_fresh(todo_callbacks_.user_data);
    }
 
    auto delegation_id = create_storage_record(
        child_ctx, target_tier, task, max_turns);
 
    logger->info("Running child loop: tier={} depth={} msgs={} "
                 "system_hash={:016x}",
                 target_tier, child_ctx.delegation_depth,
                 child_ctx.messages.size(),
                 std::hash<std::string>{}(
                     child_ctx.messages.empty()
                         ? std::string{}
                         : child_ctx.messages[0].content));
 
    if (run_child_fn_ != nullptr) {
        run_child_fn_(child_ctx, run_child_data_);
    }
 
    // Restore parent todo list
    if (todo_callbacks_.restore != nullptr && !saved_todo.empty()) {
        todo_callbacks_.restore(saved_todo, todo_callbacks_.user_data);
    }
 
    auto result = build_child_result(
        target_tier, task, child_ctx);
    complete_storage_record(delegation_id, result);
    log_child_result(result);
    return result;
}
 
DelegationResult DelegationManager::build_child_result(
    const std::string& target_tier,
    const std::string& task,
    LoopContext& child_ctx) {
    DelegationResult result;
    result.target_tier = target_tier;
    result.task = task;
    auto tr = child_ctx.metadata.find("terminal_reason");
    if (tr != child_ctx.metadata.end()) {
        result.terminal_reason = tr->second;
    }
    result.success = (child_ctx.state == AgentState::COMPLETE
                      && result.terminal_reason.empty());
    result.turns_used = child_ctx.metrics.iterations;
    result.summary = extract_summary(child_ctx);
    // Issue #10 (v2.1.4): hoist coverage_gap signal from child
    // metadata onto DelegationResult so the parent's
    // finalize_delegation_result can branch on it without re-parsing
    // ctx.metadata. dir_complete writes these keys when the child
    // calls entropic.complete with coverage_gap=true.
    auto cg = child_ctx.metadata.find("coverage_gap");
    if (cg != child_ctx.metadata.end() && cg->second == "true") {
        result.coverage_gap = true;
        auto gd = child_ctx.metadata.find("gap_description");
        if (gd != child_ctx.metadata.end()) {
            result.gap_description = gd->second;
        }
        auto sf = child_ctx.metadata.find("suggested_files_json");
        if (sf != child_ctx.metadata.end()) {
            auto parsed = nlohmann::json::parse(
                sf->second, nullptr, false);
            if (parsed.is_array()) {
                result.suggested_files =
                    parsed.get<std::vector<std::string>>();
            }
        }
    }
    result.child_messages = std::move(child_ctx.messages);
    return result;
}
 
void DelegationManager::log_child_result(
    const DelegationResult& result) {
    if (result.terminal_reason.empty()) {
        logger->info("Child loop done: tier={} success={} turns={}",
                     result.target_tier, result.success,
                     result.turns_used);
    } else {
        logger->warn("Child loop done: tier={} success=false "
                     "turns={} reason={}",
                     result.target_tier, result.turns_used,
                     result.terminal_reason);
    }
}
 
void DelegationManager::finalize_sandbox_for(
    const std::optional<SandboxInfo>& sb_info,
    const DelegationResult& result) {
    if (!sb_info || !sandbox_mgr_) {
        return;
    }
 
    if (result.success) {
        auto patch_result = sandbox_mgr_->finalize_sandbox(*sb_info);
        if (patch_result) {
            deliver_sandbox_result(*sb_info, *patch_result, result);
        } else {
            logger->error("Delegation {}: finalize_sandbox failed; "
                          "no patch delivered", sb_info->delegation_id);
        }
    } else {
        logger->info("Delegation {} failed: discarding sandbox without "
                     "generating patch", sb_info->delegation_id);
    }
    sandbox_mgr_->discard_sandbox(*sb_info);
}
 
} // namespace entropic