open-design/docs/new-agent-runtime-acp.md

# New agent runtime expectations: ACP over stdio

This note documents the preferred integration shape for a new OpenDesign agent runtime.

## Recommendation

New agent runtimes should expose an **ACP over stdio** CLI mode.

In practice, OpenDesign expects to spawn a local executable and speak JSON-RPC over the child process streams:

```text
OpenDesign daemon
  └─ spawn your-agent acp
       ├─ stdin  <- ACP JSON-RPC requests/responses
       ├─ stdout -> ACP JSON-RPC responses/notifications
       └─ stderr -> logs and diagnostics only
```

If the runtime's real implementation is a local or remote server, keep that detail behind a thin CLI wrapper:

```text
your-agent acp
  └─ connects to your runtime server / SDK / model backend
```

That wrapper keeps OpenDesign on the standard ACP subprocess transport and avoids requiring a daemon-side network transport adapter.

## Why stdio, not an ACP server?

The ACP protocol uses JSON-RPC, but transport matters.

The ACP transport documentation defines **stdio** as communication over standard input and standard output. In that transport, the client launches the agent as a subprocess, the agent reads from `stdin`, writes protocol messages to `stdout`, and writes logs to `stderr`.

ACP's remote HTTP/WebSocket transport is still described as a draft/proposal rather than the established compatibility path. OpenDesign's implemented ACP adapters therefore use stdio subprocesses today.

## Messages OpenDesign sends

For `streamFormat: 'acp-json-rpc'`, OpenDesign currently drives a session with these JSON-RPC methods:

1. `initialize`
   - Sent first.
   - Includes OpenDesign client metadata and `clientCapabilities`.
2. `session/new` or `session/load`
   - Creates a working session, or resumes the durable upstream session from a
     prior turn when OpenDesign has a saved session handle.
   - Includes the project working directory.
   - `session/new` may include MCP server descriptors when the runtime is
     allowed to use OpenDesign-provided tools.
3. `session/set_config_option` or `session/set_model` *(optional)*
   - Sent when the user selected a non-default model.
   - OpenDesign prefers `session/set_config_option` when `session/new` reports a model config option; otherwise it falls back to `session/set_model`.
4. `session/prompt`
   - Sends the composed user/system prompt as a text block, followed by
     `resource_link` blocks for staged image attachments when present.
   - A successful response marks the prompt as complete.
5. `session/cancel`
   - Sent on user cancellation when a session exists and stdin is still writable.

## Messages OpenDesign expects from the agent

The runtime should support the corresponding JSON-RPC responses and notifications:

1. Response to `initialize`.
2. Response to `session/new` or `session/load`.
   - Must include a usable `sessionId`.
   - A new session may also return the durable upstream session handle that
     OpenDesign records for the next turn.
   - Should report the current model if available.
   - Should report model config options if model selection is supported through config options.
3. Notifications using `session/update`.
   - OpenDesign currently maps:
     - `agent_thought_chunk` to thinking output.
     - `agent_message_chunk` to assistant text output.
     - `tool_call` and `tool_call_update` to tool-use/result events, including
       artifact-write accounting when the update carries a real file path.
     - Other update kinds to bounded status/diagnostic events.
4. Optional `session/request_permission` requests.
   - OpenDesign auto-selects an approve/allow-style option when available.
   - If no acceptable option is present, the turn fails fast.
5. Response to `session/prompt`.
   - Should include usage metadata when available.
   - This response tells OpenDesign the turn is finished.

## Process lifecycle expectations

- Keep protocol messages on `stdout` parseable as JSON-RPC lines.
- Write human-readable logs and diagnostics to `stderr`.
- Return clear JSON-RPC errors for protocol failures.
- After `session/prompt` completes, either exit cleanly when stdin closes or tolerate OpenDesign sending `SIGTERM` after a short grace period.
- Implement `session/cancel` if possible. OpenDesign falls back to process termination when the transport is no longer usable.
- Avoid interactive terminal prompts. If permission is required, use ACP permission requests instead.

## OpenDesign adapter shape

An ACP runtime definition in OpenDesign is intentionally small:

```ts
export const myAgentDef = {
  id: 'my-agent',
  name: 'My Agent',
  bin: 'my-agent',
  versionArgs: ['--version'],
  fallbackModels: [{ id: 'default', label: 'default' }],
  buildArgs: () => ['acp'],
  streamFormat: 'acp-json-rpc',
} satisfies RuntimeAgentDef;
```

Current examples include AMR, Devin, Hermes, Kimi, Kiro, Kilo, Reasonix, Trae CLI,
and Vibe runtime definitions under `apps/daemon/src/runtimes/defs/`.

## Fact sources

- ACP transport documentation: <https://agentclientprotocol.com/protocol/transports>
  - ACP uses JSON-RPC.
  - The stdio transport uses standard input and standard output.
  - In stdio mode, the client launches the agent as a subprocess.
  - The agent reads from `stdin`, writes protocol messages to `stdout`, and uses `stderr` for logs.
- ACP remote transport RFD: <https://agentclientprotocol.com/rfds/streamable-http-websocket-transport>
  - Describes Streamable HTTP / WebSocket as the proposed remote transport direction.
  - Notes that ACP's standard transport has historically been stdio and that a standard remote transport is still being defined.
- OpenDesign implementation:
  - `apps/daemon/src/agent-protocol/acp/session.ts` implements the ACP JSON-RPC session lifecycle and is exposed through `apps/daemon/src/agent-protocol/index.ts`.
  - `apps/daemon/src/server.ts` spawns ACP runtimes as child processes with piped stdio.
  - `apps/daemon/src/runtimes/defs/*.ts` contains existing ACP runtime definitions using `streamFormat: 'acp-json-rpc'`.