git:20260527.1cf4452 to git:20260815.b3edc81
3 added, 3 removed. Audit A to A.
# ACP Integration Notes (kimi-cli)
## Protocol summary (ACP overview)
- ACP is JSON-RPC 2.0 with request/response methods plus one-way notifications.
- Typical flow: `initialize` -> optional `authenticate` -> `session/new` or `session/load`
-> `session/prompt`
with `session/update` notifications and optional `session/cancel`.
- Clients provide `session/request_permission` and optional terminal/filesystem methods.
- All ACP file paths must be absolute; line numbers are 1-based.
## Entry points and server modes
- **Single-session server**: `KimiCLI.run_acp()` uses `ACP` -> `ACPServerSingleSession`.
- Code: `src/kimi_cli/app.py`, `src/kimi_cli/ui/acp/__init__.py`.
- Used when running CLI with `--acp` UI mode.
- **Multi-session server**: `acp_main()` runs `ACPServer` with `use_unstable_protocol=True`.
- Code: `src/kimi_cli/acp/__init__.py`, `src/kimi_cli/acp/server.py`.
- Exposed via the `kimi acp` command in `src/kimi_cli/cli/__init__.py`.
## Capabilities advertised
- `prompt_capabilities`: `embedded_context=False`, `image=True`, `audio=False`.
- `mcp_capabilities`: `http=True`, `sse=False`.
- Single-session: `load_session=False`, no session list capabilities.
- Multi-session: `load_session=True`, `session_capabilities.list` supported.
- `auth_methods=[]` (no authentication methods advertised).
## Session lifecycle (implemented behavior)
- `session/new`
- Multi-session: creates a persisted `Session`, builds `KimiCLI`, stores `ACPSession`.
- Single-session: wraps the existing `Soul` into a `Wire` loop and creates `ACPSession`.
- Both send `AvailableCommandsUpdate` for slash commands on session creation.
- MCP servers passed by ACP are converted via `acp_mcp_servers_to_mcp_config`.
- `session/load`
- Multi-session only: loads by `Session.find`, then builds `KimiCLI` and `ACPSession`.
- No history replay yet (TODO).
- Single-session: not implemented.
- `session/list`
- Multi-session only: lists sessions via `Session.list`, no pagination.
- Single-session: not implemented.
- `session/prompt`
- Uses `ACPSession.prompt()` to stream updates and produce a `stop_reason`.
- Stop reasons: `end_turn`, `max_turn_requests`, `cancelled`.
- `session/cancel`
- Sets the per-turn cancel event to stop the prompt.
## Streaming updates and content mapping
- Text chunks -> `AgentMessageChunk`.
- Think chunks -> `AgentThoughtChunk`.
- Tool calls:
- Start -> `ToolCallStart` with JSON args as text content.
- Streaming args -> `ToolCallProgress` with updated title/args.
- Results -> `ToolCallProgress` with `completed` or `failed`.
- Tool call IDs are prefixed with turn ID to avoid collisions across turns.
- Plan updates:
- `TodoDisplayBlock` is converted into `AgentPlanUpdate`.
- Available commands:
- `AvailableCommandsUpdate` is sent right after session creation.
## Prompt/content conversion
- Incoming prompt blocks:
- Supported: `TextContentBlock`, `ImageContentBlock` (converted to data URL).
- Unsupported types are logged and ignored.
- Tool result display blocks:
- `DiffDisplayBlock` -> `FileEditToolCallContent`.
- `HideOutputDisplayBlock` suppresses tool output in ACP (used by terminal tool).
## Tool integration and permission flow
- ACP sessions use `ACPKaos` to route filesystem reads/writes through ACP clients.
- If the client advertises `terminal` capability, the `Shell` tool is replaced by an
ACP-backed `Terminal` tool.
- Uses ACP `terminal/create`, waits for exit, streams `TerminalToolCallContent`,
then releases the terminal handle.
- Approval requests in the core tool system are bridged to ACP
`session/request_permission` with allow-once/allow-always/reject options.
## Current gaps / not implemented
- `authenticate` method (not used by current Zed ACP client).
- `session/set_mode` and `session/set_model` (no multi-mode/model switching in kimi-cli).
- `ext_method` / `ext_notification` for custom ACP extensions are stubbed.
- Single-session server does not implement `session/load` or `session/list`.
## Filesystem (ACP client-backed)
- When the client advertises `fs.readTextFile` / `fs.writeTextFile`, `ACPKaos` routes
reads and writes through ACP `fs/*` methods.
- - `ReadFile` uses `KaosPath.read_lines`, which `ACPKaos` implements via ACP reads.
- - `ReadMediaFile` uses `KaosPath.read_bytes` to load image/video payloads through ACP reads.
- - `WriteFile` uses `KaosPath.read_text/write_text/append_text` and still generates diffs
+ - `read` uses `KaosPath.read_lines`, which `ACPKaos` implements via ACP reads.
+ - `read_image` uses `KaosPath.read_bytes` to load image/video payloads through ACP reads.
+ - `write` uses `KaosPath.read_text/write_text/append_text` and still generates diffs
and approvals in the tool layer.
## Zed-specific notes (as of current integration)
- Zed does not currently call `authenticate`.
- Zed’s external agent server session management is not yet available, so
`session/load` is not exercised in practice.