mirror of
https://github.com/nexu-io/open-design.git
synced 2026-06-01 03:14:35 +07:00
320bd4c303
* docs: document ACP runtime integration * docs: link ACP runtime guide from entrypoints Generated-By: looper 0.7.5 (runner=fixer, agent=opencode, model=openai/gpt-5.4)
116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
# New agent runtime expectations: ACP over stdio
|
|
|
|
This note documents the preferred integration shape for a new Open Design agent runtime.
|
|
|
|
## Recommendation
|
|
|
|
New agent runtimes should expose an **ACP over stdio** CLI mode.
|
|
|
|
In practice, Open Design expects to spawn a local executable and speak JSON-RPC over the child process streams:
|
|
|
|
```text
|
|
Open Design 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 Open Design 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. Open Design's implemented ACP adapters therefore use stdio subprocesses today.
|
|
|
|
## Messages Open Design sends
|
|
|
|
For `streamFormat: 'acp-json-rpc'`, Open Design currently drives a session with these JSON-RPC methods:
|
|
|
|
1. `initialize`
|
|
- Sent first.
|
|
- Includes Open Design client metadata and `clientCapabilities`.
|
|
2. `session/new`
|
|
- Creates a working session.
|
|
- Includes the project working directory.
|
|
- May include MCP server descriptors when the runtime is allowed to use Open Design-provided tools.
|
|
3. `session/set_config_option` or `session/set_model` *(optional)*
|
|
- Sent when the user selected a non-default model.
|
|
- Open Design 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 text content.
|
|
- 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 Open Design expects from the agent
|
|
|
|
The runtime should support the corresponding JSON-RPC responses and notifications:
|
|
|
|
1. Response to `initialize`.
|
|
2. Response to `session/new`.
|
|
- Must include a usable `sessionId`.
|
|
- 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`.
|
|
- Open Design currently maps:
|
|
- `agent_thought_chunk` to thinking output.
|
|
- `agent_message_chunk` to assistant text output.
|
|
4. Optional `session/request_permission` requests.
|
|
- Open Design 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 Open Design 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 Open Design sending `SIGTERM` after a short grace period.
|
|
- Implement `session/cancel` if possible. Open Design 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.
|
|
|
|
## Open Design adapter shape
|
|
|
|
An ACP runtime definition in Open Design 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;
|
|
```
|
|
|
|
Existing examples include Devin, Hermes, Kimi, Kiro, Kilo, 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.
|
|
- Open Design implementation:
|
|
- `apps/daemon/src/acp.ts` implements the ACP JSON-RPC session lifecycle.
|
|
- `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'`.
|