server.h

Go to the documentation of this file.

 
#pragma once
 
#include <neograph/api.h>
#include <neograph/acp/types.h>
#include <neograph/graph/execution.h>
#include <neograph/tool_execution.h>
 
#include <chrono>
#include <functional>
#include <iosfwd>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <vector>
 
namespace neograph {
class Tool;
}
 
namespace neograph::acp {
 
class ACPServer;
struct ACPServerTestAccess;
 
struct NEOGRAPH_API ACPSessionContext {
    std::string              session_id;
    std::string              cwd;
    std::vector<std::string> additional_directories;
    neograph::json           mcp_tools = neograph::json::array();
};
 
struct NEOGRAPH_API ACPInterrupt {
    std::string    session_id;
    std::string    node;
    std::string    reason;
    neograph::json payload;
    std::string    checkpoint_id;
};
 
struct NEOGRAPH_API ACPInterruptPermission {
    ToolCallUpdate                tool_call;
    std::vector<PermissionOption> options;
};
 
class NEOGRAPH_API ACPGraphAdapter {
  public:
    virtual ~ACPGraphAdapter() = default;
 
    virtual std::string input_channel() const { return "prompt"; }
 
    virtual std::string output_channel() const { return "response"; }
 
    virtual std::string extract_user_text(
        const std::vector<ContentBlock>& blocks) const;
 
    virtual neograph::json build_initial_state(
        const std::vector<ContentBlock>& blocks,
        const std::string& session_id) const;
 
    virtual neograph::json build_session_state(
        const std::vector<ContentBlock>& blocks,
        const ACPSessionContext& session) const;
 
    virtual std::string extract_agent_text(
        const neograph::json& output) const;
 
    virtual std::optional<ACPInterruptPermission> interrupt_permission(
        const ACPInterrupt& interrupt) const;
 
    virtual neograph::json interrupt_resume_value(
        const ACPInterrupt& interrupt, const std::string& option_id) const;
};
 
class NEOGRAPH_API ACPClientError : public std::runtime_error {
public:
    ACPClientError(std::string method, const neograph::json& error);
    ~ACPClientError() override;
 
    [[nodiscard]] const std::string& method() const noexcept { return method_; }
    [[nodiscard]] int code() const noexcept { return code_; }
    [[nodiscard]] const std::string& message() const noexcept { return message_; }
    [[nodiscard]] const neograph::json& data() const noexcept { return data_; }
 
private:
    std::string    method_;
    int            code_ = -32603;
    std::string    message_;
    neograph::json data_;
};
 
class NEOGRAPH_API ACPClientRefusal final : public ACPClientError, public ToolRequestRefusal {
public:
    using ACPClientError::ACPClientError;
    ~ACPClientRefusal() override;
    [[nodiscard]] bool retryable() const noexcept override { return false; }
};
 
class NEOGRAPH_API ACPClient {
  public:
    using ServerResolver =
        std::function<std::shared_ptr<ACPServer>(std::string_view session_id)>;
 
    ACPClient();
 
    explicit ACPClient(ACPServer* server);
 
    explicit ACPClient(ServerResolver resolver);
 
    void bind(ACPServer* server);
 
    void bind(ServerResolver resolver);
 
    bool bound() const noexcept;
 
    void set_timeout(std::chrono::milliseconds t);
 
    void set_permission_timeout(std::optional<std::chrono::milliseconds> t);
 
    std::string read_text_file(std::string_view session_id,
                               std::string_view path,
                               std::optional<int> line  = {},
                               std::optional<int> limit = {});
 
    void write_text_file(std::string_view session_id,
                         std::string_view path,
                         std::string_view content);
 
    RequestPermissionOutcome request_permission(
        std::string_view session_id,
        const ToolCallUpdate&  tool_call,
        const std::vector<PermissionOption>& options);
 
    std::vector<std::shared_ptr<neograph::Tool>> session_tools(
        std::string_view session_id) const;
 
  private:
    ACPServer* target(std::string_view session_id,
                      std::shared_ptr<ACPServer>& keep,
                      const char* caller) const;
 
    ACPServer*               server_ = nullptr;
    ServerResolver           resolver_;
    std::chrono::milliseconds timeout_{std::chrono::seconds(30)};
    std::optional<std::chrono::milliseconds> permission_timeout_;
};
 
class NEOGRAPH_API ACPServer {
  public:
    using NotificationSink = std::function<void(const neograph::json&)>;
 
    ACPServer(std::shared_ptr<neograph::graph::GraphEngine> engine,
              neograph::json info,
              std::shared_ptr<ACPGraphAdapter> adapter = {});
    ACPServer(neograph::graph::GraphExecution execution,
              neograph::json info,
              std::shared_ptr<ACPGraphAdapter> adapter = {});
 
    ~ACPServer();
 
    AgentCapabilities&       capabilities();
    const AgentCapabilities& capabilities() const;
 
    void run(std::istream& in, std::ostream& out);
 
    void run();
 
    bool is_running() const;
 
    neograph::json handle_message(const neograph::json& envelope);
 
    void set_notification_sink(NotificationSink sink);
 
    void stop();
    void set_max_inflight_prompts(std::size_t limit);
    bool initialized() const;
 
    void set_pre_armed_cancel(bool enabled);
 
    void set_eof_grace(std::chrono::milliseconds grace);
 
    std::vector<std::shared_ptr<neograph::Tool>> session_tools(
        std::string_view session_id) const;
 
    std::shared_ptr<ACPClient> client();
 
    void attach_client(std::shared_ptr<ACPClient> c);
 
    neograph::json call_client(std::string method,
                                neograph::json params,
                                std::chrono::milliseconds timeout
                                    = std::chrono::seconds(30));
 
  private:
    friend struct ACPServerTestAccess;
 
    // Defined only in test builds. Kept private so the deterministic thread
    // failure seams are not part of the production ACP API.
    void fail_next_worker_launch_for_testing();
    void fail_next_handle_message_for_testing();
 
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
}  // namespace neograph::acp