simse uses the Agent Client Protocol (ACP) to communicate with AI backends. This reference documents the message types, lifecycle, and field conventions for ACP v1.
simse launches the backend as a local subprocess and exchanges newline-delimited JSON-RPC messages over its stdin/stdout. All messages use camelCase field names: sessionId, stopReason, agentInfo, timeoutMs, and so on.
AgentInfo identifies the backend agent. It is returned by the initialize handshake.
| Field | Type | Description |
|---|---|---|
name | string | Agent name |
version | string | Agent version string |
A session follows this sequence:
client → session/new → backend
client ← session/new (resp) ← backend (sessionId)
client → session/prompt → backend
client ← session/update ← backend (streaming, multiple)
client ← session/prompt (resp) ← backend
Creates a new session on the backend. The backend allocates a session and returns an identifier used for all subsequent calls.
Request fields:
| Field | Type | Required | Description |
|---|---|---|---|
cwd | string | Yes | Working directory for the session |
mcpServers | object[] | No | MCP server configurations to make available in the session |
Response fields:
| Field | Type | Description |
|---|---|---|
sessionId | string | Session identifier for subsequent calls |
Sends a message to an existing session. The backend processes it and eventually responds. Streaming updates arrive as session/update notifications before the final response.
Request fields:
| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | Yes | Session from session/new |
prompt | string | Yes | User message content |
timeoutMs | number | No | Request timeout in milliseconds (default 60,000) |
Response fields:
| Field | Type | Description |
|---|---|---|
sessionId | string | Echo of the session ID |
stopReason | string | Why generation stopped ("end_turn", "max_tokens", "tool_use") |
content | string | Final response text |
Streamed notifications from the backend during response generation. Multiple session/update messages arrive between session/prompt and its final response.
Fields:
| Field | Type | Description |
|---|---|---|
sessionId | string | Session identifier |
sessionUpdate | string | Discriminator for the update kind: "agent_message_chunk", "tool_call", "tool_call_update" |
The remaining fields on a session/update depend on the sessionUpdate value (see below).
When a backend wants to execute a tool action, it issues a permission request. simse presents the request to the user (or responds automatically based on the configured permission mode) and sends back a permission decision.
Permission request payload:
| Field | Type | Description |
|---|---|---|
permissionId | string | Unique ID for this permission request |
toolName | string | Name of the tool to be executed |
args | object | Tool arguments the backend wants to use |
description | string | Human-readable explanation of the action |
Permission response values:
| Value | Meaning |
|---|---|
allow_once | Permit this specific invocation only |
allow_always | Permit this tool for the rest of the session |
reject_once | Deny this specific invocation |
reject_always | Deny this tool for the rest of the session |
allow_always and reject_always decisions are remembered for the session duration and are not persisted across sessions.
Tool calls follow their own sub-lifecycle within a session, reported via session/update notifications discriminated by sessionUpdate:
session/update (sessionUpdate: "tool_call")
→ simse executes the tool
session/update (sessionUpdate: "tool_call_update", status: "in_progress")
→ execution underway
session/update (sessionUpdate: "tool_call_update", status: "completed")
→ result returned to backend
| Field | Type | Description |
|---|---|---|
toolCallId | string | Unique ID for this tool invocation |
toolName | string | Tool to invoke |
args | object | Tool input arguments |
| Field | Type | Description |
|---|---|---|
toolCallId | string | Matches the originating toolCallId |
status | string | "in_progress" or "completed" |
result | object | Present when status is "completed" |
error | string | Present when the tool call failed |
| Timeout | Default | Config key | Description |
|---|---|---|---|
timeoutMs | 60,000 ms | timeoutMs | Time allowed for any request to complete |
Configurable per server in acp.json under servers.