server.h File Reference

ACP server — exposes a NeoGraph as an Agent Client Protocol agent. More...

#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>

Include dependency graph for server.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	neograph::acp::ACPClient
	Agent-side handle for issuing requests back to the editor. More...
class	neograph::acp::ACPClientError
	A JSON-RPC error the client answered to a request of the agent. More...
class	neograph::acp::ACPClientRefusal
	An ACPClientError whose code says the request cannot succeed (#500). More...
class	neograph::acp::ACPGraphAdapter
	Map between ACP ContentBlock[] and the engine's channels. More...
struct	neograph::acp::ACPInterrupt
	A NodeInterrupt raised during a prompt turn. More...
struct	neograph::acp::ACPInterruptPermission
	The session/request_permission request that asks the user about an interrupt (see ACPGraphAdapter::interrupt_permission). More...
class	neograph::acp::ACPServer
	HTTP-less, stdio-first ACP server hosting a NeoGraph engine. More...
struct	neograph::acp::ACPSessionContext
	What a prompt turn knows about its session. More...

Detailed Description

ACP server — exposes a NeoGraph as an Agent Client Protocol agent.

Speaks JSON-RPC 2.0 over a transport. The default transport is newline-delimited JSON over stdio (one message per line on stdin, one per line on stdout) — the form used by Zed's agent-client-protocol Rust crate and by every editor that launches an agent as a sub-process. The implementation targets ACP protocol version 1 and is checked against the official schema v1.25.0 (agent-client-protocol commit 4cf3dd85, 2026-10-09) and the official Python and TypeScript SDKs.

Methods served (client → agent):

• initialize (exactly once, before all session methods)
• session/new
• session/resume
• session/prompt
• session/cancel (notification — no response)
• $/cancel_request (notification) for an in-flight session/prompt, which it cancels as session/cancel does; other request ids are ignored

Methods emitted (agent → client):

• session/update (streaming notification while a prompt is in flight)
• session/request_permission, when a node asks for it or when the graph raises a NodeInterrupt (see ACPGraphAdapter::interrupt_permission)
• fs/read_text_file, fs/write_text_file and terminal/* only when the client advertised the matching capability in initialize.

A failed turn is a JSON-RPC error on session/prompt (-32603) whose message is a public message and whose data carries the NeoGraph failure code and the retry hint; exception text never reaches the client. A provider refusal ends the turn with stopReason refusal, a step limit with max_turn_requests.

Client-supplied stdio MCP servers (session/new mcpServers) are started with NeoGraph's MCP client when the library is built with NEOGRAPH_BUILD_MCP_CLIENT; their tools are available to nodes through ACPClient::session_tools(). A server gets the agent's PATH (and on Windows SystemRoot) plus the client's env entries, never the rest of the agent's environment, which may hold provider API keys. One that does not start fails the request with a clear error.

Adapter pattern mirrors neograph::a2a — by default the inbound prompt text is dropped into the prompt channel and the response channel is sent back. Subclass ACPGraphAdapter to plug in a richer mapping (multi-modal blocks, system prompts, conversation history).

Definition in file server.h.