delegation.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include <entropic/entropic.h>  // ent_decision_t + ent_delegation_* (gh#29, v2.1.5)
#include <entropic/core/engine_types.h>
#include <entropic/core/sandbox.h>
#include <entropic/types/message.h>
 
#include <functional>
#include <optional>
#include <string>
#include <vector>
 
namespace entropic {
 
class AgentEngine; // forward declaration
 
struct DelegationResult {
    std::string summary;                  
    bool success = false;                 
    std::string target_tier;              
    std::string task;                     
    int turns_used = 0;                   
    std::vector<Message> child_messages;  
    std::string terminal_reason;
    bool coverage_gap = false;
    std::string gap_description;
    std::vector<std::string> suggested_files;
};
 
using RunChildLoopFn = void (*)(LoopContext& ctx, void* user_data);
 
struct TodoCallbacks {
    std::string (*save)(void* user_data) = nullptr;
    void (*install_fresh)(void* user_data) = nullptr;
    void (*restore)(const std::string& saved, void* user_data) = nullptr;
    void* user_data = nullptr; 
};
 
class DelegationManager {
public:
    DelegationManager(RunChildLoopFn run_child,
                      void* run_child_data,
                      const TierResolutionInterface& tier_resolution,
                      const std::filesystem::path& repo_dir = {},
                      SandboxManager* sandbox_mgr = nullptr);
 
    void set_todo_callbacks(const TodoCallbacks& callbacks);
 
    void set_dir_swap(ScopedSandbox::SwapDirFn swap_fn, void* user_data);
 
    void set_storage(const struct StorageInterface* storage);
 
    void 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);
 
    DelegationResult execute_delegation(
        LoopContext& parent_ctx,
        const std::string& target_tier,
        const std::string& task,
        std::optional<int> max_turns = std::nullopt,
        const std::vector<ContextRef>& context = {});
 
    DelegationResult 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 = std::nullopt,
        const std::vector<ContextRef>& context = {});
 
    DelegationResult execute_pipeline(
        LoopContext& parent_ctx,
        const std::vector<std::string>& stages,
        const std::string& task,
        std::vector<DelegationResult>& stage_log,
        const std::vector<ContextRef>& context = {});
 
private:
    std::string mint_delegation_id(const std::string& prefix);
 
    std::filesystem::path restore_root_for(
        const LoopContext& parent_ctx) const;
 
    static std::string format_context_block(
        const std::vector<ContextRef>& context);
 
    LoopContext build_child_context(
        const LoopContext& parent_ctx,
        const ChildContextInfo& info,
        const std::string& task,
        const std::vector<ContextRef>& context = {});
 
    LoopContext 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);
 
    std::string extract_summary(const LoopContext& child_ctx) const;
 
    std::optional<DelegationResult> 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_out);
 
    DelegationResult run_child(
        LoopContext& child_ctx,
        const std::string& target_tier,
        const std::string& task,
        std::optional<int> max_turns);
 
    DelegationResult build_child_result(
        const std::string& target_tier,
        const std::string& task,
        LoopContext& child_ctx);
 
    void log_child_result(const DelegationResult& result);
 
    void finalize_sandbox_for(
        const std::optional<SandboxInfo>& sb_info,
        const DelegationResult& result);
 
    std::string create_storage_record(
        LoopContext& child_ctx, const std::string& target_tier,
        const std::string& task, std::optional<int> max_turns);
 
    void complete_storage_record(
        const std::string& delegation_id,
        const DelegationResult& result);
 
    RunChildLoopFn run_child_fn_;                      
    void* run_child_data_;                             
    TierResolutionInterface tier_res_;                 
    TodoCallbacks todo_callbacks_;                     
    ScopedSandbox::SwapDirFn swap_dir_fn_ = nullptr;   
    void* swap_dir_data_ = nullptr;                    
    SandboxManager* sandbox_mgr_ = nullptr;            
    std::filesystem::path repo_dir_;                   
    const struct StorageInterface* storage_ = nullptr; 
 
    // ── Delegation callbacks (gh#29, v2.1.5) ───────────────
    ent_decision_t (*delegation_start_cb_)(
        const ent_delegation_request_t*, void*) = nullptr;     
    ent_decision_t (*delegation_complete_cb_)(
        const ent_delegation_result_t*, void*) = nullptr;      
    void* delegation_cb_data_ = nullptr;                       
 
    ent_decision_t fire_start_cb(
        const std::string& delegation_id,
        const std::string& target_tier,
        const std::string& task,
        int depth,
        bool is_pipeline);
 
    void deliver_sandbox_result(
        const SandboxInfo& sb_info,
        const SandboxResult& sandbox_result,
        const DelegationResult& result);
 
    ent_decision_t invoke_complete_cb(const ent_delegation_result_t& res,
                                      const std::string& delegation_id);
 
    void persist_pending_patch(
        const SandboxInfo& sb_info,
        const SandboxResult& sandbox_result,
        const char* reason);
 
    bool 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);
};
 
} // namespace entropic