nexu-io__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:

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:

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:

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'.