RPC Mode Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The RPC Mode Protocol in Autohand provides a structured interface for non-interactive execution of agent tasks using the JSON-RPC 2.0 standard. Unlike the interactive CLI loop, this mode allows external programs to programmatically control the agent, send instructions, and receive machine-readable updates on task progress, tool execution, and reasoning steps.
The protocol is designed to facilitate automation and integration with other tools or IDEs, ensuring that every action taken by the agent—from thinking to file modification—is emitted as a discrete, parsable event. Sources: [src/index.ts:153-155], [src/core/agent.ts:316-335]
Architecture and Design
The RPC system is built upon a standard request-response and notification model. It utilizes a LineReader to process incoming JSON-RPC 2.0 messages from standard input and a serialization layer to send responses and notifications via standard output.
The diagram above illustrates the data flow where a client communicates with the agent through standard streams using the JSON-RPC protocol. Sources: [src/modes/rpc/protocol.ts:161-197], [tests/modes/rpc/protocol.spec.ts:14-40]
Component Breakdown
| Component | Responsibility | Relevant Files |
|---|---|---|
| LineReader | Buffers and parses incoming byte streams into discrete string lines. | [src/modes/rpc/protocol.ts:161-197] |
| Protocol Parser | Validates JSON-RPC 2.0 structure, handling single and batch requests. | [src/modes/rpc/protocol.ts:14-106] |
| AutohandAgent | Executes instructions, manages ReAct loops, and triggers tool calls. | [src/core/agent.ts:316-340] |
| ActionExecutor | Performs the actual system mutations (file writes, git commands). | [src/core/actionExecutor.ts:108-115] |
Communication Protocol
The system adheres to JSON-RPC 2.0. Every message must include a jsonrpc: "2.0" field. Requests require a unique id, while notifications (like status updates) omit it. Sources: [src/modes/rpc/protocol.ts:14-25], [tests/modes/rpc/protocol.spec.ts:117-140]
Request Handling
The protocol supports both single and batch requests. Batch requests allow multiple method calls to be sent in a single JSON array, which the parser filters for validity before processing. Sources: [src/modes/rpc/protocol.ts:40-65], [tests/modes/rpc/protocol.spec.ts:42-53]
This sequence shows a standard synchronous request-response cycle managed by the protocol. Sources: [src/modes/rpc/protocol.ts:108-119], [tests/modes/rpc/protocol.spec.ts:14-40]
Event Types and Notifications
During the execution of a runInstruction call, the agent emits several types of output events to keep the client synchronized with the internal state.
- Thinking: Emitted when the LLM provides internal reasoning. Sources:
[src/core/agent.ts:1064-1066] - Tool Start: Indicates a tool is about to be executed, providing the tool name and arguments. Sources:
[src/core/agent.ts:223-228] - Tool End: Provides the result or error message from a tool execution. Sources:
[src/core/agent.ts:251-257] - Message: The final response intended for the user. Sources:
[src/core/agent.ts:1067] - Error: Critical failures during the ReAct loop. Sources:
[src/core/agent.ts:896-898]
Agent RPC Lifecycle
When initialized for RPC mode, the agent skips the interactive loop and waits for method calls. It maintains session persistence and telemetry similarly to CLI mode but relies on explicit confirmation callbacks for dangerous operations.
The flowchart describes the specialized lifecycle of the agent when operating under RPC control. Sources: [src/core/agent.ts:316-340], [src/core/agent.ts:233-257]
Tool Execution with RPC Callbacks
In RPC mode, the AutohandAgent uses a confirmationCallback to handle dangerous operations like write_file or delete_path. This prevents the agent from hanging on a terminal prompt and instead allows the RPC client to approve or deny the action programmatically. Sources: [src/core/agent.ts:1451-1454], [src/core/actionExecutor.ts:133-150]
| Tool Category | Example Tool | RPC Output Event |
|---|---|---|
| Filesystem | write_file | tool_start / tool_end |
| Git | git_commit | tool_start / tool_end |
| Command | run_command | tool_start / tool_end |
| Context | smart_context_cropper | tool_start / tool_end |
Sources: [src/core/agent.ts:221-278], [src/core/toolManager.ts:50-100]
Error Handling
The protocol defines specific error codes for failures in communication or execution, adhering to JSON-RPC 2.0 standards. Sources: [tests/modes/rpc/protocol.spec.ts:55-83]
- Parse Error (-32700): Invalid JSON was received by the server.
- Invalid Request (-32600): The JSON sent is not a valid Request object.
- Method Not Found (-32601): The method does not exist / is not available.
- Invalid Params (-32602): Invalid method parameter(s).
- Internal Error (-32603): Internal JSON-RPC error.
The agent also tracks retryable errors during the session, attempting recovery for network timeouts or transient provider failures before emitting a final RPC error event. Sources: [src/core/agent.ts:1240-1300]
Summary
The RPC Mode Protocol transforms the Autohand agent into a programmable backend service. By leveraging JSON-RPC 2.0 and a structured event emission system, it provides high visibility into the agent's internal reasoning and tool usage. This architecture supports advanced integrations where a parent process can monitor, intercept, and confirm agent actions in real-time. Sources: [src/core/agent.ts:316-340], [src/modes/rpc/protocol.ts:14-106]