engine_types.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include <entropic/core/directives.h>
#include <entropic/types/enums.h>
#include <entropic/types/message.h>
#include <entropic/types/tool_call.h>
 
#include <atomic>
#include <filesystem>
#include <optional>
#include <string>
#include <unordered_map>
#include <vector>
 
namespace entropic {
 
enum class AgentState : int {
    IDLE          = ENTROPIC_AGENT_STATE_IDLE,
    PLANNING      = ENTROPIC_AGENT_STATE_PLANNING,
    EXECUTING     = ENTROPIC_AGENT_STATE_EXECUTING,
    WAITING_TOOL  = ENTROPIC_AGENT_STATE_WAITING_TOOL,
    VERIFYING     = ENTROPIC_AGENT_STATE_VERIFYING,
    DELEGATING    = ENTROPIC_AGENT_STATE_DELEGATING,
    COMPLETE      = ENTROPIC_AGENT_STATE_COMPLETE,
    ERROR         = ENTROPIC_AGENT_STATE_ERROR,
    INTERRUPTED   = ENTROPIC_AGENT_STATE_INTERRUPTED,
    PAUSED        = ENTROPIC_AGENT_STATE_PAUSED,
};
 
enum class InterruptMode {
    CANCEL,  
    PAUSE,   
    INJECT,  
};
 
enum class ToolApproval {
    DENY,         
    ALLOW,        
    ALWAYS_DENY,  
    ALWAYS_ALLOW, 
};
 
enum class BudgetMode {
    off,         
    tokens,      
    wall_clock,  
};
 
struct LoopConfig {
    int max_iterations = 15;            
    int max_consecutive_errors = 3;     
    int max_tool_calls_per_turn = 10;   
    int idle_timeout_seconds = 300;     
    int context_length = 16384;         
    bool require_plan_for_complex = true; 
    bool stream_output = true;          
    bool speculative_enabled = false;
    bool auto_approve_tools = false;    
    int max_consecutive_same_tool = 5;
    int max_consecutive_same_tool_hard_block = -1;
    int max_consecutive_failed_delegations = 2;
    int max_tool_result_bytes = 16384;
    int message_queue_capacity = 8;
 
    BudgetMode budget_mode = BudgetMode::off;
 
    int budget_limit = 0;
};
 
struct LoopMetrics {
    int iterations = 0;     
    int tool_calls = 0;     
    int tokens_used = 0;    
    int errors = 0;         
    double start_time = 0.0; 
    double end_time = 0.0;  
 
    int duration_ms() const;
};
 
struct PendingDelegation {
    std::string target;                    
    std::string task;                      
    int max_turns = -1;                    
    std::string resume_from_delegation_id; 
};
 
struct PendingPipeline {
    std::vector<std::string> stages; 
    std::string task;                
};
 
struct ChildContextInfo {
    std::string system_prompt;              
    std::vector<std::string> tools;         
    std::vector<std::string> allowed_tools; 
    bool explicit_completion = false;       
    std::string completion_instructions;    
    bool valid = false;                     
    int max_iterations_override = -1;              
    int max_tool_calls_per_turn_override = -1;     
    int max_consecutive_empty_turns_override = -1; 
};
 
struct TierResolutionInterface {
    ChildContextInfo (*resolve_tier)(
        const std::string& tier_name, void* user_data) = nullptr;
 
    std::string (*get_tier_param)(
        const std::string& tier_name,
        const std::string& param_name,
        void* user_data) = nullptr;
 
    std::vector<std::string> (*get_handoff_targets)(
        const std::string& tier_name, void* user_data) = nullptr;
 
    bool (*tier_exists)(
        const std::string& tier_name, void* user_data) = nullptr;
 
    void* user_data = nullptr; 
};
 
struct LoopContext {
    std::vector<Message> messages;                         
    std::vector<ToolCall> pending_tool_calls;              
    AgentState state = AgentState::IDLE;                   
    LoopMetrics metrics;                                   
    int consecutive_errors = 0;                            
    int consecutive_duplicate_attempts = 0;                
    int effective_tool_calls = 0;                          
    bool has_pending_tool_results = false;                 
    std::string locked_tier;                               
    std::string task_id;                                   
    std::string conversation_id;                             
    std::string source = "human";                          
    std::vector<std::string> all_tools;                    
    std::string base_system;                               
    std::unordered_map<std::string, std::string> metadata; 
    int delegation_depth = 0;                              
    std::vector<std::string> delegation_ancestor_tiers;    
    std::string parent_conversation_id;                    
    std::vector<std::string> child_conversation_ids;       
    std::string active_phase = "default";                  
    std::unordered_map<std::string, std::string> recent_tool_calls; 
    std::optional<PendingDelegation> pending_delegation;  
    std::optional<PendingPipeline> pending_pipeline;      
    int effective_max_iterations = -1;           
    int effective_max_tool_calls_per_turn = -1;  
    std::string pending_validation_feedback;
 
    std::string pending_anti_spiral_warning;
 
    std::string last_tool_name;
 
    int consecutive_same_tool_calls = 0;
 
    int budget_tokens_since_tool = 0;
 
    double budget_window_start_s = 0.0;
 
    bool budget_completion_nudged = false;
 
    std::string last_failed_delegation_target;
 
    int consecutive_failed_delegations = 0;
};
 
struct EngineCallbacks {
    void (*on_state_change)(int state, void* ud) = nullptr;            
    void (*on_stream_chunk)(const char* chunk, size_t len,
                            void* ud) = nullptr;                       
    void (*on_tier_selected)(const char* tier, void* ud) = nullptr;    
    void (*on_routing_complete)(const char* json, void* ud) = nullptr; 
    void (*on_tool_call)(const char* json, void* ud) = nullptr;        
    void (*on_tool_start)(const char* json, void* ud) = nullptr;       
    void (*on_tool_complete)(const char* json, const char* result,
                             double ms, void* ud) = nullptr;           
    void (*on_presenter_notify)(const char* key, const char* json,
                                void* ud) = nullptr;                   
    void (*on_compaction)(const char* json, void* ud) = nullptr;       
    void (*on_pause_prompt)(const char* partial, char** injection,
                            void* ud) = nullptr;                       
    void (*on_tool_record)(const char* tier, const char* json,
                           const char* result, const char* error,
                           double ms, void* ud) = nullptr;             
    void (*on_delegation_start)(const char* child_id, const char* tier,
                                const char* task, void* ud) = nullptr; 
    void (*on_delegation_complete)(const char* child_id, const char* tier,
                                   const char* summary, int success,
                                   void* ud) = nullptr;                
    const char* (*error_sanitizer)(const char* raw, void* ud) = nullptr; 
    void* user_data = nullptr; 
};
 
using ToolExecutionFn = std::vector<Message> (*)(
    LoopContext& ctx,
    const std::vector<ToolCall>& tool_calls,
    void* user_data);
 
struct ToolExecutionInterface {
    ToolExecutionFn process_tool_calls = nullptr; 
    void* user_data = nullptr;                     
 
    char* (*history_json)(size_t count, void* user_data) = nullptr;
 
    void (*free_fn)(char*) = nullptr;
};
 
struct ToolExecutorHooks {
    void (*after_tool)(LoopContext& ctx, void* user_data) = nullptr;
 
    DirectiveResult (*process_directives)(
        LoopContext& ctx,
        const std::vector<const Directive*>& directives,
        void* user_data) = nullptr;
 
    void* user_data = nullptr; 
};
 
struct StorageInterface {
    bool (*create_conversation)(
        const char* title,
        std::string& conversation_id,
        void* user_data) = nullptr;
 
    bool (*save_snapshot)(
        const char* conversation_id,
        const char* messages_json,
        void* user_data) = nullptr;
 
    bool (*create_delegation)(
        const char* parent_id,
        const char* delegating_tier,
        const char* target_tier,
        const char* task,
        int max_turns,
        std::string& delegation_id,
        std::string& child_conversation_id,
        void* user_data) = nullptr;
 
    bool (*complete_delegation)(
        const char* delegation_id,
        const char* status,
        const char* summary,
        void* user_data) = nullptr;
 
    bool (*save_conversation)(
        const char* conversation_id,
        const char* messages_json,
        void* user_data) = nullptr;
 
    bool (*load_delegation_with_messages)(
        const char* delegation_id,
        std::string& result_json,
        void* user_data) = nullptr;
 
    void* user_data = nullptr; 
};
 
using PermissionPersistFn = void (*)(
    const char* pattern, bool allow, void* user_data);
 
struct PermissionPersistInterface {
    PermissionPersistFn persist = nullptr; 
    void* user_data = nullptr;             
};
 
struct GenerationEvents {
    std::atomic<bool>* interrupt = nullptr; 
    std::atomic<bool>* pause = nullptr;     
};
 
struct InterruptContext {
    std::string partial_content;             
    std::vector<ToolCall> partial_tool_calls; 
    std::string injection;                   
    InterruptMode mode = InterruptMode::PAUSE; 
};
 
const char* agent_state_name(AgentState state);
 
} // namespace entropic