zcode-acp-server 0.11.8 → 0.14.1

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);
@@ -52,6 +52,7 @@ ACP editor ────── stdio ──────────┘
 | `GET /api/instances`                                  | required | Registered bridge instances. Add `?probe=1` to verify first.                                 |
 | `GET /api/instances/{id}/status`                      | required | Real-time per-session running status of one bridge.                                          |
 | `POST /api/instances/{id}/sessions/{sessionId}/close` | required | Retire a session from remote discovery — see [Closing a session](#closing-a-session).        |
+| `POST /api/instances/{id}/sessions/{sessionId}/rename` | required | Rename a session — see [Renaming a session](#renaming-a-session).                            |
 | `GET /api/quota`                                      | required | Account-level usage stats — same payload as `account/usage_stats`, no ACP connection needed. |
 | `POST /api/upgrade`                                   | required | Trigger the hub's own staleness check — see [Hub self-upgrade](#hub-self-upgrade).           |
 
@@ -91,9 +92,12 @@ HTTP auth: `Authorization: Bearer <token>` or `?token=<token>`.
   `session/load` puts the remote client on the same notification stream as
   the editor tab: turns driven from either side stream live to both. A
   conversation with no editor placeholder is advertised under its backend
-  id (`sess_…`), still loadable via pass-through resume. `title` comes from
-  the backend session store once the backend has titled it; sessions whose
-  first turn is still running carry the provisional prompt-derived title.
+  id (`sess_…`), still loadable via `session/load` pass-through resume. The
+  title is set exactly once by the bridge — from the first line of the first
+  prompt (capped at 80 chars), the moment that prompt is sent — and never
+  changes automatically afterwards; a manual rename is the only later
+  modifier. Sessions born in a previous bridge lifetime get their title from
+  the session store on load/resume.
 - `sessions[].status` is a coarse `"running" | "idle"` indicator riding the
   heartbeat (up to ~10s stale; absent on older bridges — treat as unknown).
   For the live value poll [`/api/instances/{id}/status`](#session-running-status).
@@ -110,9 +114,9 @@ HTTP auth: `Authorization: Bearer <token>` or `?token=<token>`.
   **accessible** (every listed id resolves and resumes through that bridge).
   Retired conversations of the project are NOT listed even though the
   backend store still has them — the store only enriches live entries with
-  the authoritative title and a cross-bridge `updatedAt`. Entries may carry
-  a provisional title (first line of the first prompt, capped at 60 chars)
-  until the backend's own auto-title lands.
+  the stored title and a cross-bridge `updatedAt`. The auto-title is set once
+  at the first prompt (first non-empty line, capped at 80 chars) and is never
+  revised by later turns.
 - Entries are **deduped across instances**: several bridges of the same
   project (e.g. a leaked old process plus the current one) can all hold the
   same live conversation under the same id; the hub keeps one copy per
@@ -178,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:
 
@@ -292,6 +296,31 @@ Cross-instance note: if the same conversation is also registered by another
 bridge of the project, the hub's dedupe re-attaches it under that instance —
 close it there too.
 
+## Renaming a session
+
+```text
+POST {hub}/api/instances/{id}/sessions/{sessionId}/rename
+     body: { "title": "new name" }                        → 200 { "ok": true, "title": "…" }
+```
+
+The session title is set **once**, automatically, from the first prompt of a
+freshly created session (first non-empty line, capped at 80 chars) — this
+endpoint is the only later modifier. ACP has no client→agent rename channel,
+and an editor-side rename lives in the editor's own storage forever, so the
+remote side is where a rename enters the system.
+
+The bridge applies the rename everywhere: its in-memory title pin (no later
+automatic write can touch it), the discovery summary (live within one
+heartbeat), the ZCode App's tasks-index (`title_overridden=1`, same marker the
+App's own rename sets), and a `session_info_update` broadcast to every
+attached client — the editor tab updates live. The title is normalized like
+the auto-title: flattened to one line, trimmed, capped at 80 chars; an
+all-whitespace title is rejected with `400`.
+
+Errors: `400` missing/empty title or oversized body (>4 KB), `401` bad token,
+`404` unknown session (or instance), `502` bridge unreachable. Renaming during
+a running turn is allowed — titles are no longer turn-coupled.
+
 ## Hub self-upgrade
 
 ```text

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.8",
+  "version": "0.14.1",
   "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",