engine.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include <entropic/entropic.h>  // for ent_decision_t and ent_delegation_* (gh#29, v2.1.5)
#include <entropic/core/compaction.h>
#include <entropic/core/context_manager.h>
#include <entropic/core/directives.h>
#include <entropic/core/engine_types.h>
#include <entropic/core/response_generator.h>
#include <entropic/core/sandbox.h>  // gh#33 (v2.1.6): engine-owned session sandbox
#include <entropic/interfaces/i_hook_handler.h>
#include <entropic/core/stream_think_filter.h>
#include <entropic/interfaces/i_inference_callbacks.h>
#include <entropic/types/session_logger.h>
 
#include <atomic>
#include <deque>
#include <filesystem>
#include <mutex>
#include <optional>
#include <string>
#include <unordered_map>
#include <unordered_set>
#include <vector>
 
#include <nlohmann/json_fwd.hpp>  // gh#32 (v2.1.6) resume payload type
 
namespace entropic {
 
class AgentEngine {
public:
    static constexpr int MAX_DELEGATION_DEPTH = 2;
 
    AgentEngine(const InferenceInterface& inference,
                const LoopConfig& loop_config,
                const CompactionConfig& compaction_config);
 
    struct DelegationCallbacks {
        ent_decision_t (*start)(const ent_delegation_request_t*, void*)
            = nullptr;
        ent_decision_t (*complete)(const ent_delegation_result_t*, void*)
            = nullptr;
        void* user_data = nullptr;
    };
 
    std::vector<Message> run(std::vector<Message> messages,
                             const std::string& tier_override = "");
 
    void set_callbacks(const EngineCallbacks& callbacks);
 
    void set_tool_executor(const ToolExecutionInterface& tool_exec);
 
    void set_tier_resolution(const TierResolutionInterface& tier_res);
 
    void set_storage(const StorageInterface& storage);
 
    void set_hooks(const HookInterface& hooks);
 
    void set_project_dir(const std::filesystem::path& project_dir);
 
    void set_stream_observer(TokenCallback observer, void* user_data);
 
    void set_validation_provider(char* (*provider)(void*),
                                 void* user_data);
 
    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);
 
    DelegationCallbacks delegation_callbacks_snapshot() const;
 
    void set_external_interrupt(void (*cb)(void* user_data),
                                void* user_data);
 
    void run_loop(LoopContext& ctx, bool inherit_interrupt = false);
 
    const TierResolutionInterface& tier_resolution() const;
 
    void interrupt();
 
    void reset_interrupt();
 
    void pause();
 
    void cancel_pause();
 
    std::pair<int, int> context_usage(
        const std::vector<Message>& messages) const;
 
    EngineCallbacks& callbacks() { return callbacks_; }
 
    const LoopConfig& loop_config() const { return loop_config_; }
 
    DirectiveProcessor& directive_processor() { return directive_processor_; }
 
    LoopMetrics last_loop_metrics() const { return last_metrics_; }
 
    std::unordered_map<std::string, LoopMetrics>
        per_tier_metrics() const { return per_tier_metrics_; }
 
    // ── Conversation state (v2.0.2) ─────────────────────────
 
    void set_system_prompt(const std::string& prompt);
 
    void set_session_logger(SessionLogger* logger);
 
    std::vector<Message> run_turn(const std::string& input);
 
    std::vector<Message> run_turn_as(const std::string& tier,
                                     const std::string& input);
 
    std::vector<Message> run_turn(std::vector<Message> new_messages);
 
    void seed_system_prompt(const std::vector<Message>& new_messages);
 
    std::vector<Message> run_drain_loop(std::string pending,
                                        const std::string& tier_override);
 
    void seed_system_prompt_for_tier(const std::string& tier);
 
    bool prepare_next_turn(std::vector<Message>& pending);
 
    int run_streaming(const std::string& input,
                      TokenCallback on_token,
                      void* user_data,
                      int* cancel_flag);
 
    int run_streaming(std::vector<Message> new_messages,
                      TokenCallback on_token,
                      void* user_data,
                      int* cancel_flag);
 
    void clear_conversation();
 
    size_t message_count() const;
 
    const std::vector<Message>& get_messages() const;
 
    // ── Mid-generation user-message queue (gh#40, v2.1.10) ──
 
    bool queue_user_message(const std::string& message);
 
    size_t user_message_queue_depth() const;
 
    void clear_user_message_queue();
 
    void set_message_queue_capacity(int cap);
 
    bool is_running() const { return running_flag_.load(); }
 
    void set_queue_observer(
        void (*observer)(const char*, size_t, void*),
        void* user_data);
 
    void set_state_observer(
        void (*observer)(int state, void* user_data),
        void* user_data);
 
    // ── Directive hooks (v2.0.2) ────────────────────────────
 
    ToolExecutorHooks build_directive_hooks();
 
    // ── Tier info (v2.0.2) ──────────────────────────────────
 
    void set_tier_info(const std::string& name,
                       const ChildContextInfo& info);
 
    bool has_tier(const std::string& name) const;
 
    std::vector<std::string> get_tier_allowed_tools(
        const std::string& name) const;
 
    const std::string& tier_system_prompt(const std::string& name) const;
 
    void set_relay_single_delegate(const std::string& name);
 
    void set_handoff_rules(
        const std::unordered_map<std::string,
            std::vector<std::string>>& rules);
 
    bool tier_requires_explicit_completion(
        const std::string& tier) const;
 
    bool is_delegation_cycle(
        const LoopContext& ctx, const std::string& target) const;
 
    bool is_delegation_repeat_blocked(
        const LoopContext& ctx, const std::string& target) const;
 
    int64_t seconds_since_last_activity() const;
 
    bool fold_complete_into_assistant(
        LoopContext& ctx, const Message& tool_result_msg) const;
 
    void defang_meta_action_envelope(Message& msg) const;
 
    CompactionManager& compaction_manager() { return compaction_manager_; }
 
private:
    void init_session_conversation(LoopContext& ctx);
 
    void accumulate_run_metrics(LoopContext& ctx);
 
    void loop(LoopContext& ctx);
 
    void execute_iteration(LoopContext& ctx);
 
    void evaluate_no_tool_decision(LoopContext& ctx,
                                   const std::string& content,
                                   const std::string& finish_reason);
 
    bool handle_terminal_finish_reasons(
        LoopContext& ctx, const std::string& finish_reason);
 
    bool record_explicit_completion_failure(
        LoopContext& ctx, const std::string& finish_reason);
 
    void finalize_delegation_result(
        LoopContext& ctx, const struct DelegationResult& result);
 
    void relay_partial_result(LoopContext& ctx, const std::string& summary);
 
    void log_relay_status(LoopContext& ctx,
                          const std::string& terminal_reason = {});
 
    bool should_stop(const LoopContext& ctx) const;
 
    static bool is_terminal_state(const LoopContext& ctx);
 
    void set_state(LoopContext& ctx, AgentState state);
 
    void reinject_context_anchors(LoopContext& ctx);
 
    void register_directive_handlers();
 
    // ── Directive handlers ───────────────────────────────
    void dir_stop(LoopContext&, const Directive&, DirectiveResult&);         
    void dir_tier_change(LoopContext&, const Directive&, DirectiveResult&);  
    void dir_delegate(LoopContext&, const Directive&, DirectiveResult&);     
    void dir_pipeline(LoopContext&, const Directive&, DirectiveResult&);     
    void dir_complete(LoopContext&, const Directive&, DirectiveResult&);     
    void dir_clear_todos(LoopContext&, const Directive&, DirectiveResult&);  
    void dir_inject(LoopContext&, const Directive&, DirectiveResult&);       
    void dir_prune(LoopContext&, const Directive&, DirectiveResult&);        
    void dir_anchor(LoopContext&, const Directive&, DirectiveResult&);       
    void dir_phase(LoopContext&, const Directive&, DirectiveResult&);        
    void dir_notify(LoopContext&, const Directive&, DirectiveResult&);       
 
    std::pair<std::string, std::vector<ToolCall>> parse_tool_calls(
        const std::string& raw_content);
 
    bool process_tool_results(LoopContext& ctx,
                              const std::vector<ToolCall>& tool_calls);
 
    // ── Delegation (v1.8.6) ──────────────────────────────
 
    void execute_pending_delegation(LoopContext& ctx);           
 
    bool reject_delegation_if_guarded(LoopContext& ctx,
                                      const PendingDelegation& pending);
 
    void execute_pending_pipeline(LoopContext& ctx);             
 
    bool should_auto_chain(const LoopContext& ctx,
                           const std::string& finish_reason,
                           const std::string& content);         
 
    bool try_auto_chain(LoopContext& ctx,
                        const std::string& finish_reason,
                        const std::string& content);            
 
    bool fire_pre_hook(entropic_hook_point_t point, int iteration); 
 
    void fire_post_generate_hook(GenerateResult& result,
                                    const std::string& tier,
                                    const std::vector<Message>& messages); 
 
    void capture_validation_feedback(LoopContext& ctx);
 
    void dispatch_post_generate(LoopContext& ctx,
                                GenerateResult& result);
 
    void process_generation_result(LoopContext& ctx,
                                   GenerateResult& result);
 
    void dispatch_pending_or_halt(LoopContext& ctx);
 
    void charge_thinking_budget(LoopContext& ctx, size_t content_len,
                                bool made_tool_call);
 
    int budget_units_consumed(LoopContext& ctx, size_t content_len);
 
    void nudge_budget_completion(LoopContext& ctx);
 
    void hard_cut_budget(LoopContext& ctx);
 
    bool fire_complete_hook(const std::string& summary,
                            const LoopContext& ctx);                
 
    bool fire_delegate_pre_hook(const PendingDelegation& pending,
                                int depth);                         
 
    void fire_delegate_complete_hook(const std::string& target,
                                     bool success,
                                     const std::string& summary = "");
 
    std::filesystem::path get_repo_dir();                       
 
    SandboxManager* ensure_sandbox_manager();                   
 
    bool resolve_resume_delegation(
        LoopContext& ctx,
        PendingDelegation& pending,
        std::vector<Message>& out_history);
 
    bool fetch_resume_payload(
        LoopContext& ctx,
        const std::string& id,
        nlohmann::json& parsed);
 
    DelegationResult run_pending_delegation(
        LoopContext& ctx,
        const PendingDelegation& pending,
        std::vector<Message> resume_history);
 
    void fire_delegation_start(const LoopContext& ctx,
                               const std::string& tier,
                               const std::string& task);      
 
    void fire_delegation_complete(const LoopContext& ctx,
                                  const std::string& tier,
                                  const struct DelegationResult& result); 
 
    // ── Members ──────────────────────────────────────────
    LoopMetrics last_metrics_;                           
    std::unordered_map<std::string, LoopMetrics>
        per_tier_metrics_;                               
    InferenceInterface inference_;                       
    LoopConfig loop_config_;                             
    EngineCallbacks callbacks_;                          
    std::atomic<bool> interrupt_flag_{false};             
    std::atomic<bool> pause_flag_{false};                 
    void (*external_interrupt_cb_)(void*) = nullptr;      
    void* external_interrupt_data_ = nullptr;             
    // ── Delegation callbacks (gh#29, v2.1.5) ────────────────
    DelegationCallbacks delegation_cb_;
    mutable std::mutex delegation_cb_mutex_;
    char* (*validation_provider_)(void*) = nullptr;       
    void* validation_provider_data_ = nullptr;            
    std::unordered_map<std::string, std::string> context_anchors_; 
    ToolExecutionInterface tool_exec_;                     
    TierResolutionInterface tier_res_;                    
    StorageInterface storage_;                             
    DirectiveProcessor directive_processor_;              
    TokenCounter token_counter_;                          
    CompactionManager compaction_manager_;                
    ContextManager context_manager_;                      
    ResponseGenerator response_generator_;                
    HookInterface hooks_;                                    
    std::optional<std::filesystem::path> cached_repo_dir_; 
    bool repo_dir_checked_ = false;                        
    std::filesystem::path project_dir_override_;           
    std::optional<SandboxManager> sandbox_mgr_;            
 
    // ── Mid-generation user-message queue (gh#40, v2.1.10) ──
    mutable std::mutex queue_mutex_;          
    std::deque<std::string> user_message_queue_; 
    std::atomic<bool> running_flag_{false};   
    std::atomic<int64_t> last_activity_epoch_s_{0};
    void (*queue_observer_)(const char*, size_t, void*) = nullptr; 
    void* queue_observer_data_ = nullptr;     
    void (*state_observer_)(int, void*) = nullptr;
    void* state_observer_data_ = nullptr;     
    std::optional<std::string> pop_queued_user_message();
 
    void fire_queue_consumed(const std::string& consumed, size_t remaining);
 
    // ── Conversation state (v2.0.2) ─────────────────────────
    std::vector<Message> conversation_;                    
    std::string system_prompt_;                            
    SessionLogger* session_logger_ = nullptr;              
 
    // ── Pre-resolved tier data (v2.0.2) ─────────────────────
    std::unordered_map<std::string, ChildContextInfo> tier_info_;  
    std::unordered_map<std::string, std::vector<std::string>> handoff_rules_; 
    std::unordered_set<std::string> relay_single_delegate_tiers_;
 
    void wire_internal_tier_resolution();
 
    void apply_identity_overrides(LoopContext& ctx);
 
    int resolve_max_iterations(const LoopContext& ctx) const;
 
    int resolve_max_tool_calls(const LoopContext& ctx) const;
 
    /* ── TierResolutionInterface trampolines (static — accept void* ud) ── */
    static ChildContextInfo tri_resolve_tier(
        const std::string& name, void* ud);
    static bool tri_tier_exists(
        const std::string& name, void* ud);
    static std::vector<std::string> tri_get_handoff_targets(
        const std::string& name, void* ud);
    static std::string tri_get_tier_param(
        const std::string& name, const std::string& param, void* ud);
};
 
} // namespace entropic