zcode-acp-server 0.11.9 → 0.14.2

package/docs/BACKLOG.md

@@ -3,9 +3,15 @@
 Backend RPC methods and event types exposed by the ZCode CLI (`zcode app-server`)
 that are **not yet wired into the bridge**, tracked for potential future support.
 
-Last audited against **app-server 0.16.3** (bundled in ZCode desktop 3.8.1,
-2026-08-09). Method names were extracted from the bundled `zcode.cjs` dispatch
-switch and verified with live RPC calls.
+Last audited against **app-server 0.16.5** (bundled in ZCode desktop 3.9.2,
+2026-08-27; the previous audit ran against desktop 3.9.1 / same app-server
+0.16.5, so this refresh is a re-verification rather than a version bump).
+Method names were extracted from the bundled `zcode.cjs` dispatch switch and
+verified with live RPC calls. Live checks after the 3.9.2 update: `session/
+list`, `session/create`, `session/steer` (still `-32601`), and a full REPL
+smoke (`session/new` + `/sessions`) all behave unchanged. New in the
+enumeration: the reference-catalog family below (either shipped quietly in
+0.16.x or added by 3.9.2 — the previous audit never listed them).
 
 ## Removed upstream in 0.16 (verified live: `-32601`)
 
@@ -25,15 +31,23 @@ elsewhere.
 Available in the backend but with no ACP-side counterpart yet. Pick them up
 when a concrete ACP/editor need appears.
 
-| Method                                                                          | Purpose                                                     | Current bridge behavior                                                                                                |
-| ------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `session/subagents`                                                             | Query the list of sub-agents for a session                  | Sub-agent info is parsed from the `Agent` tool result (`_meta.subagent`); sufficient for now                           |
-| `session/events`                                                                | Pull-mode event history (complement to `session/subscribe`) | Not used; could support event replay/gap-fill                                                                          |
-| `session/usage`                                                                 | Per-session token usage                                     | Context bar uses `session.updated` usage payload instead                                                               |
-| `workspace/hooks/trustGrant`                                                    | Server→client request: approve hook trust                   | Auto-errored by the unknown-request fallback (`server-requests.ts` `handleOne`) during turns; `session/send` carries a 15s timeout so nothing hangs. If hook trust ever needs real UX, map it onto ACP `session/request_permission` |
-| `interaction/browserList` / `interaction/browserExecute`                        | Server→client requests: browser automation via the client   | Auto-errored by the fallback above; only meaningful once an ACP client has a browser surface                                                 |
-| `interaction/requestProviderRuntimeHeaders`                                     | Server→client request: provider runtime headers             | Auto-errored by the fallback above                                                                                     |
-| `workspace/updateInteractionPreferences` / `workspace/updateModelIoPreferences` | Client preference updates                                   | Not used                                                                                                               |
+| Method                                                                                                                                                      | Purpose                                                                | Current bridge behavior                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session/subagents`                                                                                                                                         | Query the list of sub-agents for a session                             | Sub-agent info is parsed from the `Agent` tool result (`_meta.subagent`); sufficient for now                                                                                                                                        |
+| `session/events`                                                                                                                                            | Pull-mode event history (complement to `session/subscribe`)            | Not used; could support event replay/gap-fill                                                                                                                                                                                       |
+| `session/usage`                                                                                                                                             | Per-session token usage                                                | Context bar uses `session.updated` usage payload instead                                                                                                                                                                            |
+| `workspace/hooks/trustGrant`                                                                                                                                | Server→client request: approve hook trust                              | Auto-errored by the unknown-request fallback (`server-requests.ts` `handleOne`) during turns; `session/send` carries a 15s timeout so nothing hangs. If hook trust ever needs real UX, map it onto ACP `session/request_permission` |
+| `interaction/browserList` / `interaction/browserExecute`                                                                                                    | Server→client requests: browser automation via the client              | Auto-errored by the fallback above; only meaningful once an ACP client has a browser surface                                                                                                                                        |
+| `interaction/requestProviderRuntimeHeaders`                                                                                                                 | Server→client request: provider runtime headers                        | Auto-errored by the fallback above                                                                                                                                                                                                  |
+| `interaction/requestOfficialMcpAuthHeaders` (0.16.5)                                                                                                        | Server→client request: official MCP auth headers                       | Auto-errored by the fallback above                                                                                                                                                                                                  |
+| `session/requestRuntimePreferences` (0.16.5)                                                                                                                | Runtime preference negotiation                                         | Auto-errored by the fallback above (same class as trustGrant)                                                                                                                                                                       |
+| `session/close` (0.16.5)                                                                                                                                    | Actually close a backend session/runtime                               | Not used — remote close intentionally retires discovery only (ADR-0006, self-healing); backend runtimes idle-evict anyway                                                                                                           |
+| `workspace/generateText` / `workspace/cancelGenerateText` (0.16.5)                                                                                          | Workspace-scoped one-shot text generation                              | Not used; no ACP counterpart                                                                                                                                                                                                        |
+| `workspace/readState` (0.16.5)                                                                                                                              | Read workspace state                                                   | Not used                                                                                                                                                                                                                            |
+| `workspace/setDefaultMode` / `setDefaultModel` / `setDefaultThoughtLevel` (0.16.5)                                                                          | Workspace-level defaults (bridge uses per-session setters)             | Not used                                                                                                                                                                                                                            |
+| `workspace/upsertModelProvider` / `removeModelProvider` (0.16.5)                                                                                            | Provider registry management                                           | Not used; bridge forwards the client's registry via `updateProviderRegistry`                                                                                                                                                        |
+| `workspace/updateInteractionPreferences` / `workspace/updateModelIoPreferences`                                                                             | Client preference updates                                              | Not used                                                                                                                                                                                                                            |
+| `skills/referenceCatalog`, `plugins/referenceCatalog`, `plugins/resolveSuggestedReference` (verified live 2026-08-27, params need `workspace.workspaceKey`) | Skill/plugin reference catalog lookup + suggested-reference resolution | Not used — the bridge reads skills and plugin commands from disk (`config/skill-discovery.ts`, `config/plugin-commands.ts`); revisit only if a client needs the backend's catalog view                                              |
 
 ### New `session/send` params (0.16+)
 
@@ -52,15 +66,20 @@ forwarded:
 
 ### New event types (undocumented in PROTOCOL.md)
 
-| Event                                    | Notes                                                                      |
-| ---------------------------------------- | -------------------------------------------------------------------------- |
-| `checkpoint.created`                     | Checkpoint lifecycle; pairs with `rewind.triggered`                        |
-| `rewind.triggered`                       | A rewind happened (e.g. initiated elsewhere)                               |
-| `streamRecovery.updated`                 | Stream recovery progress — potentially useful for the replay/gap-fill path |
-| `turn.attachments.resolved`              | Attachment resolution telemetry                                            |
-| `usage.delta`                            | Streaming usage updates                                                    |
-| `turn.steerQueued` / `turn.steerDrained` | Steer lifecycle (queue/drain of steered inputs)                            |
-| `turn.terminal`                          | Terminal turn lifecycle; bridge relies on `turn.completed`/`turn.failed`   |
+| Event                                                            | Notes                                                                      |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `checkpoint.created`                                             | Checkpoint lifecycle; pairs with `rewind.triggered`                        |
+| `rewind.triggered`                                               | A rewind happened (e.g. initiated elsewhere)                               |
+| `rewind.started` / `rewind.failed` / `rewind.completed` (0.16.5) | Full rewind lifecycle; richer than the bare `triggered`                    |
+| `streamRecovery.updated`                                         | Stream recovery progress — potentially useful for the replay/gap-fill path |
+| `turn.attachments.resolved`                                      | Attachment resolution telemetry                                            |
+| `usage.delta`                                                    | Streaming usage updates                                                    |
+| `turn.steerQueued` / `turn.steerDrained`                         | Steer lifecycle (queue/drain of steered inputs)                            |
+| `turn.terminal`                                                  | Terminal turn lifecycle; bridge relies on `turn.completed`/`turn.failed`   |
+
+Unknown event types fall through the translator's else-chain untranslated and
+silently — new backend events never produce noise or errors, so additions
+here are informational, not blocking.
 
 ## v4 protocol family (strategic)
 

package/docs/REMOTE-CLIENTS.md

@@ -2,7 +2,7 @@
 
 How to attach any out-of-editor client — browser SPA, mobile app, CLI, desktop
 tool — to bridge sessions over the network. This document IS the contract:
-everything here is implemented by `zcode-acp-hub` and the bridge's remote
+everything here is implemented by the hub daemon (`zcode-acp hub`) and the bridge's remote
 endpoint; anything not written here is not part of the contract.
 
 ACP method semantics are defined by the [ACP spec](https://agentclientprotocol.com);
@@ -182,7 +182,7 @@ pull-only request — callable any time after `initialize`, no session required.
 Fetch once after attach and on demand; quota changes are slow, there is no
 push.
 
-Both channels return the same payload, mirroring the `zcode-quota` CLI card's
+Both channels return the same payload, mirroring the `zcode-acp quota` CLI card's
 data model — one GLM section plus one Opencode Go section — so clients can
 reproduce the CLI layout exactly:
 

package/docs/TROUBLESHOOTING.md

@@ -341,7 +341,7 @@ http://127.0.0.1:<hub-port>/api/health` fails, or `/api/*` returns 401.
 1. 401 means a token mismatch — `ZCODE_ACP_REMOTE_TOKEN` must be identical in
    the bridge env, the hub env (if run manually), and the client request.
 2. A dead hub self-heals: the next bridge heartbeat (≤10s; worst ~1min under
-   the spawn throttle) re-spawns `zcode-acp-hub`. Retry with backoff rather
+   the spawn throttle) re-spawns the hub daemon. Retry with backoff rather
    than restarting anything by hand.
 3. Confirm the ports match: the client must reach `ZCODE_ACP_HUB_PORT`
    (default 8377) through the tunnel, and the tunnel maps exactly that one

package/docs/adr/0007-unified-cli-entry-and-bin-pruning.md

@@ -0,0 +1,40 @@
+# Unified CLI entry and bin pruning
+
+The package grew three separate bins (`zcode-acp-server`, `zcode-acp-hub`,
+`zcode-quota`) plus a planned terminal chat surface. Installing four sibling
+commands for one tool is noisy, and each new surface would add another. We
+decided to ship one human-facing entry point — the Unified CLI, `zcode-acp` —
+with every surface as a subcommand: `quota`, `hub`, and `server`. Bare
+`zcode-acp` opens the interactive REPL: an Ink-rendered chat UI (the renderer
+Claude Code and Gemini CLI use) speaking ACP to a spawned bridge over stdio,
+with the update pump, permission picker, and turn state machine owned by this
+package. The REPL is written in-house rather than borrowed — no embeddable
+interactive ACP client library exists (acpx is headless-only; the interactive
+clients Toad/Hydra/Nori are external tools or heavyweight daemons), and we
+control both protocol ends already.
+
+Bin declarations are pruned to `zcode-acp` and `zcode-acp-server`. The server
+bin stays because it is the command name hardcoded in existing editor configs
+(Zed, JetBrains) across ~2.5k monthly downloads — removing it would break every
+current user at once; it is an editor contract, not a human alias. The
+`zcode-acp-hub` and `zcode-quota` bins are removed in 0.12.0 with a README
+migration note (`zcode-acp hub` / `zcode-acp quota`); the hub's own binary file
+stays in `dist/bin/hub.js` because bridges spawn it by absolute path, not by
+command name, so the remote feature is unaffected.
+
+Bin-name detection is `basename(argv[1])`, which works through Unix symlinks
+but not through Windows `.cmd` shims (they spawn `node ...\dist\cli.js`, so
+the bin name never reaches argv). Bare invocation without a TTY therefore
+falls back to the stdio server — the only sensible reading of a piped, no-TTY
+launch, and exactly what a Windows editor spawn needs. The explicit
+`zcode-acp repl` subcommand keeps a hard TTY check and errors instead.
+
+We rejected keeping all old bins as silent aliases (five installed commands;
+the redundancy was the original complaint), removing every old bin including
+`zcode-acp-server` (breaks all existing editor configs at once; revisit at
+1.0), and bundling [acpx](https://github.com/openclaw/acpx) as a `chat`
+passthrough subcommand (evaluated first: its engine is headless-only, so it
+cannot host the interactive REPL that is the actual requirement, and keeping
+it beside the in-house REPL would mean two terminal surfaces, a pre-1.0
+dependency, and an extra Node engine bump for no remaining use — dropped
+before release).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.11.9",
+  "version": "0.14.2",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,9 +23,8 @@
     "zcode"
   ],
   "bin": {
-    "zcode-acp-server": "dist/index.js",
-    "zcode-acp-hub": "dist/bin/hub.js",
-    "zcode-quota": "dist/bin/quota.js"
+    "zcode-acp": "dist/cli.js",
+    "zcode-acp-server": "dist/cli.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,6 +36,11 @@
   ],
   "dependencies": {
     "@agentclientprotocol/sdk": "^1.3.0",
+    "chalk": "^6.0.0",
+    "ink": "^7.1.1",
+    "ink-spinner": "^5.0.0",
+    "react": "^19.2.8",
+    "string-width": "^8.2.2",
     "ws": "^8.21.3"
   },
   "peerDependencies": {
@@ -45,6 +49,7 @@
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.2.18",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",