| 1 | # ACP Registry Submission Prep |
| 2 | |
| 3 | Prepared for #3192. The external registry submission is now open as |
| 4 | `agentclientprotocol/registry#411`. |
| 5 | |
| 6 | ## Upstream Registry Requirements |
| 7 | |
| 8 | Checked against `agentclientprotocol/registry` on 2026-06-27: |
| 9 | |
| 10 | - New entries live in a directory whose name matches the `id` field. |
| 11 | - Each entry needs `agent.json` plus a required `icon.svg`. |
| 12 | - `agent.json` requires `id`, `name`, `version`, `description`, and at least one |
| 13 | `distribution` method. |
| 14 | - Supported distribution methods are `binary`, `npx`, and `uvx`. |
| 15 | - Package and binary versions must match the entry version, and `latest` is not |
| 16 | allowed. |
| 17 | - Binary platform ids are `darwin-aarch64`, `darwin-x86_64`, `linux-aarch64`, |
| 18 | `linux-x86_64`, `windows-aarch64`, and `windows-x86_64`. |
| 19 | - Icons must be 16x16 SVG, square, monochrome, and use `currentColor`. |
| 20 | - Registry CI runs an auth check: `initialize` must return at least one |
| 21 | `authMethods` entry with `type: "agent"` or `type: "terminal"`. |
| 22 | |
| 23 | Sources for the external PR author: |
| 24 | |
| 25 | - https://github.com/agentclientprotocol/registry |
| 26 | - https://github.com/agentclientprotocol/registry/blob/main/FORMAT.md |
| 27 | - https://github.com/agentclientprotocol/registry/blob/main/CONTRIBUTING.md |
| 28 | - https://github.com/agentclientprotocol/registry/blob/main/AUTHENTICATION.md |
| 29 | - https://github.com/agentclientprotocol/registry/blob/main/agent.schema.json |
| 30 | |
| 31 | ## Local ACP Readiness Audit |
| 32 | |
| 33 | CodeWhale already exposes ACP through `codewhale serve --acp`. |
| 34 | |
| 35 | Implemented locally: |
| 36 | |
| 37 | - `crates/tui/src/main.rs` accepts `serve --acp` and dispatches to the ACP |
| 38 | server. |
| 39 | - `crates/tui/src/acp_server.rs` implements JSON-RPC 2.0 over newline-delimited |
| 40 | stdio. |
| 41 | - `initialize` advertises: |
| 42 | - `agentInfo.name = "codewhale"` |
| 43 | - `agentInfo.title = "codewhale"` |
| 44 | - `agentInfo.version = env!("CARGO_PKG_VERSION")` |
| 45 | - `promptCapabilities.embeddedContext = true` |
| 46 | - `loadSession = false` |
| 47 | - `mcpCapabilities.http = false` |
| 48 | - `mcpCapabilities.sse = false` |
| 49 | - `authMethods` with terminal auth: `auth set --provider <provider>` |
| 50 | - `session/new` creates an in-memory session with a cwd. |
| 51 | - `session/prompt` accepts string prompts plus text/resource/resource_link |
| 52 | blocks and routes through the configured CodeWhale client. |
| 53 | - `session/prompt` **streams**: each provider text delta is emitted as a |
| 54 | `session/update` agent_message_chunk as it arrives, then the prompt returns |
| 55 | `stopReason: "end_turn"` (instead of buffering the whole turn and sending one |
| 56 | chunk at the end). |
| 57 | - The stream is consumed concurrently with the input reader, so a |
| 58 | `session/cancel` for the same session interrupts the turn mid-stream and the |
| 59 | prompt returns `stopReason: "cancelled"`; dropping the stream aborts the |
| 60 | underlying provider connection. A no-prompt `session/cancel` stays an |
| 61 | idempotent `null` no-op. The turn is single-flight: another request arriving |
| 62 | mid-turn gets a clear "prompt in progress" error instead of being silently |
| 63 | dropped. |
| 64 | |
| 65 | Known limitations to state clearly: |
| 66 | |
| 67 | - The adapter is baseline ACP, not the full interactive TUI/runtime surface. |
| 68 | - Streaming covers text deltas only; thinking/tool/server-tool deltas are not |
| 69 | surfaced over ACP (ACP baseline here is text-only, `tools: None`). |
| 70 | - ACP does not expose shell tools, file-write tools, checkpoint replay, session |
| 71 | loading, or the HTTP/SSE runtime API. |
| 72 | - Registry submission should be gated on a local run of the upstream registry |
| 73 | auth-check before opening the external PR. That check passed locally before |
| 74 | `agentclientprotocol/registry#411` was opened. |
| 75 | |
| 76 | The submitted registry PR uses the `npx` distribution because |
| 77 | `codewhale@0.8.65` is already published and the npm wrapper handles platform |
| 78 | selection, checksums, mirrors, and glibc preflight. |
| 79 | |
| 80 | ## External Registry Files |
| 81 | |
| 82 | Create this directory in `agentclientprotocol/registry`: |
| 83 | |
| 84 | ```text |
| 85 | codewhale/ |
| 86 | agent.json |
| 87 | icon.svg |
| 88 | ``` |
| 89 | |
| 90 | Use a concrete published version. Do not use `@latest`. |
| 91 | |
| 92 | ### `codewhale/agent.json` |
| 93 | |
| 94 | ```json |
| 95 | { |
| 96 | "id": "codewhale", |
| 97 | "name": "CodeWhale", |
| 98 | "version": "0.8.65", |
| 99 | "description": "Provider-agnostic terminal coding agent with first-class DeepSeek support.", |
| 100 | "repository": "https://github.com/Hmbown/CodeWhale", |
| 101 | "website": "https://github.com/Hmbown/CodeWhale/blob/main/docs/RUNTIME_API.md#acp-stdio-adapter-codewhale-serve---acp", |
| 102 | "authors": ["Hunter Bown"], |
| 103 | "license": "MIT", |
| 104 | "distribution": { |
| 105 | "npx": { |
| 106 | "package": "codewhale@0.8.65", |
| 107 | "args": ["serve", "--acp"] |
| 108 | } |
| 109 | } |
| 110 | } |
| 111 | ``` |
| 112 | |
| 113 | ### `codewhale/icon.svg` |
| 114 | |
| 115 | ```svg |
| 116 | <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="none"> |
| 117 | <path d="M2 9.5c0-3.3 2.7-6 6-6h4.5v2H8a4 4 0 0 0-4 4v.5h7.5a2.5 2.5 0 0 0 2.4-1.8l.6-2.2H16l-.7 2.7A4 4 0 0 1 11.5 12H4.2A3 3 0 0 1 2 9.5Z" fill="currentColor"/> |
| 118 | <path d="M5 7h1.5v1.5H5V7Zm3 0h1.5v1.5H8V7Z" fill="currentColor"/> |
| 119 | </svg> |
| 120 | ``` |
| 121 | |
| 122 | ## External PR Draft |
| 123 | |
| 124 | Title: |
| 125 | |
| 126 | ```text |
| 127 | Add CodeWhale ACP agent |
| 128 | ``` |
| 129 | |
| 130 | Body: |
| 131 | |
| 132 | ```text |
| 133 | Adds CodeWhale to the ACP registry. |
| 134 | |
| 135 | CodeWhale is a provider-agnostic terminal coding agent with first-class |
| 136 | DeepSeek support. The submitted distribution uses the published npm package and |
| 137 | runs `codewhale serve --acp`. |
| 138 | |
| 139 | Local readiness checked in Hmbown/CodeWhale: |
| 140 | - ACP stdio adapter exists at `codewhale serve --acp`. |
| 141 | - `initialize` returns terminal auth via `auth set --provider <provider>`. |
| 142 | - `session/new`, `session/prompt`, and `session/cancel` are implemented. |
| 143 | - `session/prompt` streams provider text deltas as `session/update` chunks. |
| 144 | - The adapter is intentionally baseline: no ACP shell/file tools, no session |
| 145 | load, and no full runtime API through ACP. |
| 146 | |
| 147 | Version: 0.8.65 |
| 148 | ``` |
| 149 | |
| 150 | ## Pre-Submission Checklist |
| 151 | |
| 152 | - Confirm `codewhale@0.8.65` is published to npm: done on 2026-06-27. |
| 153 | - Run the upstream registry validator: done on 2026-06-27 with |
| 154 | `python3 .github/workflows/verify_agents.py --auth-check --agent codewhale --verbose`; |
| 155 | result was `Auth OK: codewhale-terminal-auth(terminal)`. |
| 156 | - Verify `npx -y codewhale@0.8.65 serve --acp` returns `authMethods` from |
| 157 | `initialize`: done on 2026-06-27. |
| 158 | - Keep the external PR body explicit that ACP support is baseline and does not |
| 159 | imply the full TUI/runtime API is available inside ACP: done in |
| 160 | `agentclientprotocol/registry#411`. |
| 161 |