engine_handle.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include <entropic/config/bundled_models.h>
#include <entropic/core/compactor_registry.h>
#include <entropic/core/constitutional_validator.h>
#include <entropic/core/engine.h>
#include <entropic/core/hook_registry.h>
#include <entropic/core/identity_manager.h>
#include <entropic/entropic.h>  // ent_path_approval_cb (v2.13.0)
#include <entropic/inference/orchestrator.h>
#include <entropic/mcp/mcp_authorization.h>
#include <entropic/mcp/external_bridge.h>
 
#include "http_listener.h"
#include <entropic/mcp/server_manager.h>
#include <entropic/mcp/tool_executor.h>
#include <entropic/storage/audit_logger.h>
#include <entropic/types/session_logger.h>
#include <entropic/storage/backend.h>
#include <entropic/types/config.h>
#include <entropic/types/error.h>
#include <entropic/types/logging.h>
#include <entropic/types/run_scope.h>
 
#include <atomic>
#include <filesystem>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
 
// Forward declarations for Phase 1+ subsystems.
// Headers included as each phase wires them.
namespace entropic {
class ModelOrchestrator;
class ServerManager;
class ToolExecutor;
class IdentityManager;
class MCPAuthorizationManager;
class AgentEngine;
class SqliteStorageBackend;
class AuditLogger;
class ConstitutionalValidator;
class CompactorRegistry;
struct ParsedConfig;
class BundledModels;
struct InterfaceContext;  // gh#58 follow-up (v2.2.6): per-handle iface ctx
} // namespace entropic
 
struct EntropicWorkspace {
    std::string name;                    
    std::filesystem::path root;          
    std::unique_ptr<entropic::ServerManager> servers;
    std::optional<std::string> app_context;
};
 
struct entropic_engine {
    // ── Phase 0: Lifecycle ──────────────────────────────────
    entropic::HookRegistry hook_registry;     
    std::mutex api_mutex;                     
    std::string last_error;                   
    std::atomic<bool> configured{false};      
    std::atomic<bool> running{false};         
    int log_id = 0;
 
    // ── Phase 1: Configuration ────────────────────────────────
    entropic::ParsedConfig config;                    
    entropic::config::BundledModels bundled_models;   
 
    // ── Phase 2: Inference ─────────────────────────────────────
    std::unique_ptr<entropic::ModelOrchestrator> orchestrator; 
    entropic::InferenceInterface inference_iface;              
    entropic::InterfaceContext* inference_iface_ctx = nullptr;
 
    // ── Phase 3: MCP + Identity + Authorization ──────────────
    std::unique_ptr<entropic::ServerManager> server_manager;           
    std::unique_ptr<entropic::ToolExecutor> tool_executor;             
    std::unique_ptr<entropic::IdentityManager> identity_manager;       
    std::unique_ptr<entropic::MCPAuthorizationManager> mcp_auth;       
 
    // ── Phase 3b: Delegation isolation + workspaces (gh#160/gh#166) ──
    // gh#158: the DEFAULT workspace's sandbox swap lock is
    // `server_manager`'s own `ToolRootLock` — exclusive from `ScopedSandbox`
    // construction to destruction, re-entrant for a nested delegation, and
    // taken SHARED by every in-process dispatch on the set. The facade
    // `recursive_mutex` it replaces serialized swaps against each other
    // only, not against another session's tool calls.
 
    std::map<std::string, std::unique_ptr<EntropicWorkspace>> workspaces;
    std::map<std::string, std::string> session_workspace;
    mutable std::mutex workspace_mutex;
 
    // ── Phase 4: Engine Loop + Storage + Audit ─────────────────
    std::unique_ptr<entropic::AgentEngine> engine;                     
    std::unique_ptr<entropic::SqliteStorageBackend> storage;           
    std::unique_ptr<entropic::AuditLogger> audit_logger;               
    std::unique_ptr<entropic::SessionLogger> session_logger;           
 
    // ── Phase 5: Constitutional + Compaction ────────────────────
    std::unique_ptr<entropic::ConstitutionalValidator> validator;       
    std::unique_ptr<entropic::CompactorRegistry> compactor_registry;   
 
    // ── Phase 6: Tier metadata (v2.0.4) ───────────────────────
    std::unordered_map<std::string, std::vector<std::string>> tier_allowed_tools;
    std::unordered_map<std::string, std::vector<std::string>> tier_validation_rules;
 
    // ── Phase 7: External MCP bridge (v2.0.8) ──────────────────
    std::unique_ptr<entropic::ExternalBridge> external_bridge;   
    std::unique_ptr<entropic::http::HttpListener> http_listener;
 
    // ── Stream observer (v2.0.10) ────────────────────────────
    void (*stream_observer)(const char*, size_t, void*) = nullptr;
    void* stream_observer_data = nullptr;                        
 
    // ── State-change observer (P1-5 follow-up, 2.0.6-rc16.2) ─
    void (*state_observer)(int, void*) = nullptr;
    void* state_observer_data = nullptr;
 
    // ── Mid-gen queue observer (gh#40, v2.1.10) ───────────────
    void (*queue_observer)(const char*, size_t, void*) = nullptr;
    void* queue_observer_data = nullptr;
 
    // ── Critique start/end callbacks (gh#50, v2.1.12) ─────────
    void (*critique_start_cb)(void*) = nullptr;
    void (*critique_end_cb)(void*) = nullptr;
    void* critique_cb_data = nullptr;
 
    // ── Outside-root path approver (v2.13.0) ───────────────────
    ent_path_approval_cb path_approval_cb = nullptr;
    void* path_approval_data = nullptr;       
    std::mutex path_approval_mutex;
};
 
namespace entropic {
 
inline EntropicWorkspace* workspace_for(entropic_handle_t h,
                                        const std::string& key) {
    if (h == nullptr) { return nullptr; }
    std::lock_guard<std::mutex> lock(h->workspace_mutex);
    auto bound = h->session_workspace.find(key);
    if (bound == h->session_workspace.end()) { return nullptr; }
    auto ws = h->workspaces.find(bound->second);
    return ws == h->workspaces.end() ? nullptr : ws->second.get();
}
 
inline entropic::ServerManager* workspace_servers(entropic_handle_t h,
                                                  const std::string& key) {
    auto* ws = workspace_for(h, key);
    if (ws != nullptr && ws->servers) { return ws->servers.get(); }
    return h != nullptr ? h->server_manager.get() : nullptr;
}
 
void wire_outside_root_approver(entropic_handle_t h);
 
std::filesystem::path expected_bridge_socket(entropic_handle_t h);
 
std::filesystem::path bridge_project_dir(entropic_handle_t h);
 
void wire_external_server_policy(entropic_handle_t h,
                                 ServerManager& servers, bool with_declared);
 
void apply_workspace_app_context(entropic_handle_t h,
                                 const std::string& workspace,
                                 const std::optional<std::string>& app_context);
 
ENTROPIC_EXPORT void swap_session_tool_dir(
    const std::string& session_key, const std::filesystem::path& path,
    bool entering, void* ud);
 
std::size_t release_session_tool_state(entropic_handle_t h,
                                       const std::string& key);
 
class HandleApiLock {
public:
    explicit HandleApiLock(entropic_handle_t h)
        : lock_(h->api_mutex), log_scope_(h->log_id) {}
    HandleApiLock(const HandleApiLock&) = delete;
    HandleApiLock& operator=(const HandleApiLock&) = delete;
private:
    // Order matters: api_mutex acquired first, log_scope second.
    // Destruction reverses (scope first, mutex second) — fine.
    std::lock_guard<std::mutex> lock_;
    entropic::log::HandleLogScope log_scope_;
};
 
class HandleTurnGuard {
public:
    explicit HandleTurnGuard(entropic_handle_t h,
                             const char* session_key = nullptr)
        : engine_(h != nullptr ? h->engine.get() : nullptr),
          log_scope_(h != nullptr ? h->log_id : 0),
          key_(session_key != nullptr ? session_key : ""),
          // gh#166: publish the key to THIS thread for the whole call, so
          // the tool-prompt callback — which arrives through an interface
          // header that takes only a tier name — can resolve the
          // workspace this turn belongs to.
          session_scope_(session_key != nullptr ? session_key : "") {}
 
    ~HandleTurnGuard() {
        if (claimed_) { engine_->end_turn(key_); }
    }
 
    HandleTurnGuard(const HandleTurnGuard&) = delete;
    HandleTurnGuard& operator=(const HandleTurnGuard&) = delete;
 
    bool claim() {
        if (!claimed_ && engine_ != nullptr) {
            claimed_ = engine_->try_begin_turn(key_);
        }
        return claimed_;
    }
 
    const std::string& key() const { return key_; }
 
    bool claimed() const { return claimed_; }
 
private:
    entropic::AgentEngine* engine_;
    entropic::log::HandleLogScope log_scope_;
    std::string key_;
    entropic::RunSessionScope session_scope_;
    bool claimed_ = false;
};
 
}  // namespace entropic