zcode-acp-server 0.2.0 → 0.3.0

package/dist/utils.js

@@ -3,15 +3,31 @@
  *
  * Logging goes to stderr so it never corrupts the stdout ACP protocol stream.
  */
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 /** ACP protocol version this server speaks. */
 export const PROTOCOL_VERSION = 1;
+/**
+ * Package version, read once from package.json. Kept in sync with releases by
+ * construction (the hardcoded constant used to drift from package.json); the
+ * hub-vs-bridge version handshake in remote/ relies on it changing per
+ * release.
+ */
+const PACKAGE_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 /** Agent identity advertised in the initialize response. */
 export const AGENT_INFO = {
     name: "zcode-acp-server",
     title: "ZCode",
-    version: "0.1.0",
+    version: PACKAGE_VERSION,
 };
 /** Path to the ZCode v2 config (credentials + provider/model metadata). */
 export const ZCODE_CREDS_PATH = path.join(process.env.HOME || process.env.USERPROFILE || "~", ".zcode", "v2", "config.json");

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -14,7 +14,7 @@ application-client (Zed / JetBrains)
        |
        v
 zcode-acp-server (stdio JSON-RPC ACP)
-  |-- handlers/     session, extensions, dispatch, server-requests, io, slash
+  |-- handlers/     session, extensions, dispatch, server-requests, io, slash, account
   |-- translators/    event-translator, projection-differ, tool-helpers
   |-- interaction/    adapter
   |-- config/         options, runtime-model, model-cache
@@ -142,12 +142,12 @@ local relay: prompts, code, and tool outputs pass through process memory on
 their way between the editor and the ZCode subprocess, but reach the GLM cloud
 API only because the ZCode backend itself sends them for inference.
 
-| Concern | Detail |
-| ------- | ------ |
-| Network | One outbound request in the whole codebase — `src/quota/client.ts` GET to the quota API, Bearer token only, no body |
-| Credentials | API key from `~/.zcode/v2/config.json` (authenticates the subprocess + quota request), never logged. OAuth handled by the ZCode subprocess, not this server |
-| Disk | No new files. Writes only to the existing `~/.zcode/v2/tasks-index.sqlite` — syncs sessions into the ZCode app's history & search (session title + first prompt) |
-| Logging | `log()`/`warn()` → stderr only for troubleshooting; even with `ZCODE_ACP_DEBUG=1`, no prompts/code/keys are logged |
+| Concern     | Detail                                                                                                                                                           |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Network     | One outbound request in the whole codebase — `src/quota/client.ts` GET to the quota API, Bearer token only, no body                                              |
+| Credentials | API key from `~/.zcode/v2/config.json` (authenticates the subprocess + quota request), never logged. OAuth handled by the ZCode subprocess, not this server      |
+| Disk        | No new files. Writes only to the existing `~/.zcode/v2/tasks-index.sqlite` — syncs sessions into the ZCode app's history & search (session title + first prompt) |
+| Logging     | `log()`/`warn()` → stderr only for troubleshooting; even with `ZCODE_ACP_DEBUG=1`, no prompts/code/keys are logged                                               |
 
 ## Module Responsibilities
 
@@ -170,15 +170,16 @@ API only because the ZCode backend itself sends them for inference.
 
 ### `handlers/` — ACP method handling
 
-| File                 | Responsibility                                                                                               |
-| -------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `session.ts`         | session/new/list/resume/load/prompt/set_config_option/cancel                                                 |
-| `extensions.ts`      | fork/rewind/rewindCascade/goal/compact/steer/cancelBackgroundTask/setModel/setMode/setThoughtLevel           |
-| `dispatch.ts`        | dispatchEvent single exit point: InternalEvent → ACP session/update                                          |
+| File                  | Responsibility                                                                                                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session.ts`          | session/new/list/resume/load/prompt/set_config_option/cancel                                                                                                                                            |
+| `extensions.ts`       | fork/rewind/rewindCascade/goal/compact/steer/cancelBackgroundTask/setModel/setMode/setThoughtLevel                                                                                                      |
+| `dispatch.ts`         | dispatchEvent single exit point: InternalEvent → ACP session/update                                                                                                                                     |
 | `background-tasks.ts` | Session-scoped `BackgroundTaskListener` — forwards background sub-agent status (`session.updated` taskId) + completion-notification turns to the client OUTSIDE request handlers (lives across prompts) |
-| `server-requests.ts` | Handle zcode interaction/* requests (tool auth, ExitPlanMode, AskUserQuestion), protocol negotiation routing |
-| `io.ts`              | ACP notification helpers (including `sendAvailableCommandsDeferred` deferred notification)                   |
-| `slash.ts`           | Interception of `/`-prefixed commands (/compact /goal /fork /rewind /steer /model /mode /thought)            |
+| `server-requests.ts`  | Handle zcode interaction/* requests (tool auth, ExitPlanMode, AskUserQuestion), protocol negotiation routing                                                                                            |
+| `io.ts`               | ACP notification helpers (including `sendAvailableCommandsDeferred` deferred notification)                                                                                                              |
+| `slash.ts`            | Interception of `/`-prefixed commands (/compact /goal /fork /rewind /steer /model /mode /thought); non-advertised `/x` prompts are neutralized into plain text (`neutralizeSlashText`)                  |
+| `account.ts`          | `account/usage_stats` — account-level plan quota for remote clients (Proposal 0002; quota pipeline + graceful error)                                                                                    |
 
 ### `interaction/` — Interaction bridging
 
@@ -194,6 +195,37 @@ API only because the ZCode backend itself sends them for inference.
 | `runtime-model.ts` | runtimeModel overlay construction and application              |
 | `model-cache.ts`   | Model ID cache and usage initialization                        |
 
+### `remote/` — Remote access (opt-in via `ZCODE_ACP_REMOTE=1`)
+
+| File            | Responsibility                                                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `broadcast.ts`  | ClientRegistry + broadcast proxy: notify fans out to all clients; request is first-response-wins with loser `$/cancel_request`                               |
+| `config.ts`     | ENV parsing (gate, mandatory token, hub/bridge ports)                                                                                                        |
+| `endpoint.ts`   | Loopback ACP endpoint (SDK AcpServer transport, port auto-increment) + hub registration/heartbeat                                                            |
+| `hub-server.ts` | The hub singleton: token auth, instance discovery, byte-level WS proxying, heartbeat pruning, on-demand `?probe=1` liveness, idle exit, version self-upgrade |
+
+When enabled, the same `AgentApp` serves the stdio editor and a loopback
+WebSocket endpoint. Every connection (editor or remote) joins the broadcast
+registry via `trackConnections`, so one turn's notifications reach all clients
+regardless of who prompted. The bridge registers itself with the machine-level
+`zcode-acp-hub` (`bin/hub.ts`), which is the only public entry point and holds
+no session state (see `docs/adr/0002`). The bridge's lifetime still follows the
+stdio client (ADR-0001); the listener is `unref()`'d so remote clients alone
+never keep the process alive.
+
+Hub upgrades are self-managing: each heartbeat carries the bridge's package
+version, and a hub that sees a NEWER bridge replies `{ok, restarting}`, exits,
+and is re-spawned by that bridge from its own (upgraded) `dist/` within a few
+seconds. Equal, older, or absent versions never trigger a restart — downgrades
+and mixed-version fleets are fine. Without this handshake a long-lived hub
+would keep running pre-upgrade code until its 10-minute idle exit.
+
+Discovery liveness has two layers: the heartbeat TTL (30s, pruned every 5s)
+drops bridges that stopped registering — the fallback for hard kills — and
+`GET /api/instances?probe=1` actively TCP-probes each registered loopback port
+on demand, so a client refresh gets an immediately-honest list with no
+background probing cost.
+
 ## Key State Machines
 
 ### Turn state

package/docs/BACKLOG.md

@@ -33,7 +33,9 @@ have no ACP equivalent. Listed for completeness only — the bridge does not
 intend to surface them.
 
 `automation/create`, `automation/list`, `automation/delete` (scheduled tasks),
-`usage/stats`, `workspace/readState`, `workspace/upsertModelProvider`,
+`usage/stats` (token analytics; the account-level plan quota it does NOT cover
+is exposed via the bridge's own `account/usage_stats` — see Proposal 0002),
+`workspace/readState`, `workspace/upsertModelProvider`,
 `workspace/removeModelProvider`, `workspace/updateProviderRegistry`,
 `workspace/setDefaultModel`, `workspace/setDefaultThoughtLevel`,
 `workspace/setDefaultMode`, `workspace/generateText`, `mcp/list`,

package/docs/DEVELOPMENT.md

@@ -90,6 +90,32 @@ describe("backend", () => {
 });
 ```
 
+### Method 4: Remote access (hub + endpoint)
+
+Run the bridge with the remote env vars on scratch ports (keep stdin open —
+the bridge exits when its stdio client disconnects):
+
+```bash
+ZCODE_ACP_REMOTE=1 \
+ZCODE_ACP_REMOTE_TOKEN=dev-token \
+ZCODE_ACP_HUB_PORT=18377 \
+ZCODE_ACP_REMOTE_PORT=18378 \
+ZCODE_ACP_DEBUG=1 \
+tail -f /dev/null | node dist/index.js
+```
+
+The first bridge spawns `dist/bin/hub.js` on its own. Verify discovery:
+
+```bash
+curl -H "Authorization: Bearer dev-token" http://127.0.0.1:18377/api/instances
+curl -H "Authorization: Bearer dev-token" "http://127.0.0.1:18377/api/instances?probe=1"
+```
+
+Integration tests live in `tests/hub.test.ts` (hub API, probe, proxy, idle
+exit) and `tests/remote-endpoint.test.ts` (registration + end-to-end proxied
+initialize). The remote features are opt-in and self-contained — remote
+failures warn and disable remote only, so stdio testing works without them.
+
 ## Debugging Tips
 
 ### Enable verbose logging

package/docs/PROTOCOL.md

@@ -12,11 +12,11 @@ resembles JSON-RPC, but **does not include the `jsonrpc` field**.
 
 Messages are classified by the presence of `id` and `method`:
 
-| Combination | Type | Direction |
-|------|------|------|
-| `id` + no `method` | Response | zcode -> bridge |
-| `id` + `method` | Request | bridge -> zcode or zcode -> bridge |
-| `method` + no `id` | Notification | bidirectional |
+| Combination        | Type         | Direction                          |
+| ------------------ | ------------ | ---------------------------------- |
+| `id` + no `method` | Response     | zcode -> bridge                    |
+| `id` + `method`    | Request      | bridge -> zcode or zcode -> bridge |
+| `method` + no `id` | Notification | bidirectional                      |
 
 ### Request format
 
@@ -84,6 +84,7 @@ the backend session (this RPC) on the first prompt / config change / extension
 method, so an editor startup that never sends a message leaves no session.
 
 **Request:**
+
 ```json
 {
   "id": 1,
@@ -99,6 +100,7 @@ method, so an editor startup that never sends a message leaves no session.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 1,
@@ -117,6 +119,7 @@ method, so an editor startup that never sends a message leaves no session.
 List all sessions.
 
 **Request:**
+
 ```json
 {
   "id": 2,
@@ -142,6 +145,7 @@ empty one if the placeholder was never used. Real ids from `session/list` pass
 through unchanged.
 
 **Request:**
+
 ```json
 {
   "id": 3,
@@ -161,6 +165,7 @@ through unchanged.
 Send a prompt.
 
 **Request:**
+
 ```json
 {
   "id": 4,
@@ -173,6 +178,7 @@ Send a prompt.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 4,
@@ -200,6 +206,7 @@ Stop the current turn (fire-and-forget).
 Read the session state and projection.
 
 **Request:**
+
 ```json
 {
   "id": 5,
@@ -211,6 +218,7 @@ Read the session state and projection.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 5,
@@ -226,9 +234,7 @@ Read the session state and projection.
       "model": { "current": { "modelId": "GLM-5.2" } },
       "thoughtLevel": { "current": "high" }
     },
-    "todos": [
-      { "content": "Implement login", "status": "pending", "priority": "high" }
-    ]
+    "todos": [{ "content": "Implement login", "status": "pending", "priority": "high" }]
   }
 }
 ```
@@ -238,6 +244,7 @@ Read the session state and projection.
 Fetch the session's historical messages.
 
 **Request:**
+
 ```json
 {
   "id": 6,
@@ -255,6 +262,7 @@ Fetch the session's historical messages.
 Subscribe to a session's event push.
 
 **Request:**
+
 ```json
 {
   "id": 7,
@@ -269,6 +277,7 @@ Subscribe to a session's event push.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 7,
@@ -322,6 +331,7 @@ Model streaming output.
 ```
 
 `kind` can be:
+
 - `text_delta`: text delta
 - `reasoning_delta`: reasoning text delta
 - `tool_call`: tool call declaration (caches toolName and input)
@@ -348,6 +358,7 @@ Tool status update.
 ```
 
 `kind` can be:
+
 - `scheduled`: tool scheduled
 - `started`: tool started executing
 - `progress`: progress update (stdoutTail / stderrTail)
@@ -497,6 +508,7 @@ Tool permission request.
 User input request (ExitPlanMode / AskUserQuestion).
 
 **ExitPlanMode:**
+
 ```json
 {
   "id": 101,
@@ -512,6 +524,7 @@ User input request (ExitPlanMode / AskUserQuestion).
 ```
 
 **AskUserQuestion:**
+
 ```json
 {
   "id": 102,
@@ -539,17 +552,18 @@ User input request (ExitPlanMode / AskUserQuestion).
 ZCode `interaction/*` requests are routed to different ACP interaction
 mechanisms based on client capabilities:
 
-| Request type | Client supports elicitation.form | Client does not |
-|---------|:------------------------:|:----------:|
-| Tool auth (`interaction/requestPermission`) | `session/request_permission` | `session/request_permission` |
-| ExitPlanMode (`interaction/requestUserInput` + plan_approval) | `elicitation/create` (approve/reject form) | `session/request_permission` |
-| AskUserQuestion (`interaction/requestUserInput`) | `elicitation/create` (single form) | per-question `session/request_permission` |
+| Request type                                                  |      Client supports elicitation.form      |              Client does not              |
+| ------------------------------------------------------------- | :----------------------------------------: | :---------------------------------------: |
+| Tool auth (`interaction/requestPermission`)                   |        `session/request_permission`        |       `session/request_permission`        |
+| ExitPlanMode (`interaction/requestUserInput` + plan_approval) | `elicitation/create` (approve/reject form) |       `session/request_permission`        |
+| AskUserQuestion (`interaction/requestUserInput`)              |     `elicitation/create` (single form)     | per-question `session/request_permission` |
 
 **Capability detection**: at `initialize` time the client declares support via
 `clientCapabilities.elicitation.form`. The server detects it with
 `server.supportsElicitationForm()`.
 
 **elicitation form example** (AskUserQuestion):
+
 ```json
 {
   "method": "elicitation/create",
@@ -591,6 +605,7 @@ overrides the dropdown (single-select) or is appended to the picked values
 that question without cancelling the form.
 
 **elicitation response** (accept/decline/cancel):
+
 ```json
 {
   "action": "accept",
@@ -604,6 +619,7 @@ typing into the field is the reject action. Submitting with the field empty
 approves the plan; submitting with text rejects it and returns the text to
 zcode as the decline `reason` (so the agent sees the redirection when it
 re-plans). The cancel/decline button is a plain reject with no reason.
+
 ```json
 {
   "method": "elicitation/create",
@@ -633,6 +649,7 @@ re-plans). The cancel/decline button is a plain reject with no reason.
 Fork a new session from a checkpoint.
 
 **Request:**
+
 ```json
 {
   "id": 8,
@@ -649,6 +666,7 @@ Fork a new session from a checkpoint.
 Rewind to a checkpoint.
 
 **Request:**
+
 ```json
 {
   "id": 9,
@@ -666,6 +684,7 @@ Rewind to a checkpoint.
 Read / set / replace / clear the goal.
 
 **Request:**
+
 ```json
 {
   "id": 10,
@@ -685,6 +704,7 @@ Read / set / replace / clear the goal.
 Compact the conversation history.
 
 **Request:**
+
 ```json
 {
   "id": 11,
@@ -700,6 +720,7 @@ Compact the conversation history.
 Append instructions to a running turn.
 
 **Request:**
+
 ```json
 {
   "id": 12,
@@ -716,6 +737,7 @@ Append instructions to a running turn.
 Switch the session mode.
 
 **Request:**
+
 ```json
 {
   "id": 13,
@@ -732,6 +754,7 @@ Switch the session mode.
 Set the thought level.
 
 **Request:**
+
 ```json
 {
   "id": 14,
@@ -807,10 +830,10 @@ lifecycle on the same stream:
 The bridge's session-scoped `BackgroundTaskListener` turns these into a
 dedicated ACP tool card (`[background] <description>`) plus status updates:
 
-| Backend event | ACP notification |
-|---|---|
+| Backend event                              | ACP notification                                               |
+| ------------------------------------------ | -------------------------------------------------------------- |
 | first `session.updated` (status `running`) | `tool_call` (new card, `kind:"other"`, `status:"in_progress"`) |
-| `session.updated` (status `completed`) | `tool_call_update` (`status:"completed"`) |
+| `session.updated` (status `completed`)     | `tool_call_update` (`status:"completed"`)                      |
 
 `session.updated` events WITHOUT a `taskId` (e.g. usage updates) are ignored by
 the background listener — they remain owned by the turn loop.
@@ -883,11 +906,11 @@ The mechanism:
    `toolCallId` is unknown to `terminalSentData` (sub-agent case), the listener
    falls back to minting a fresh `bg_*` card — the Agent sub-agent path above.
 
-| Backend event | ACP notification (background Bash) |
-|---|---|
-| first `session.updated` (status `running`) | `tool_call_update` on the launch card (`status:"in_progress"`) |
+| Backend event                                             | ACP notification (background Bash)                                                                                         |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| first `session.updated` (status `running`)                | `tool_call_update` on the launch card (`status:"in_progress"`)                                                             |
 | `session.updated` (status `completed`, with `outputTail`) | `terminal_output` (final output, if not already streamed) + `tool_call_update` with `terminal_exit` (`status:"completed"`) |
-| `session.updated` (status `failed`) | `tool_call_update` with `terminal_exit` (`status:"failed"`, exit_code 1) |
+| `session.updated` (status `failed`)                       | `tool_call_update` with `terminal_exit` (`status:"failed"`, exit_code 1)                                                   |
 
 `session/cancelBackgroundTask` for a background Bash task additionally emits
 `terminal_exit` with `_meta.backgroundTask.cancelled = true` so the terminal
@@ -898,13 +921,11 @@ UI closes on cancellation.
 Cancels a background task. The bridge additionally marks the corresponding ACP
 tool card as `failed` with `_meta.backgroundTask.cancelled = true`.
 
-
-
-| ZCode CLI version | session/subscribe | Extension methods | Notes |
-|---------------|-------------------|----------|------|
-| >= 0.15.0 | Supported | All supported | Full functionality |
-| >= 0.14.8 | Supported | Partially supported | workspace/* unavailable |
-| 0.14.5 ~ 0.14.7 | Not supported | Not supported | Incompatible with this project |
+| ZCode CLI version | session/subscribe | Extension methods   | Notes                          |
+| ----------------- | ----------------- | ------------------- | ------------------------------ |
+| >= 0.15.0         | Supported         | All supported       | Full functionality             |
+| >= 0.14.8         | Supported         | Partially supported | workspace/* unavailable        |
+| 0.14.5 ~ 0.14.7   | Not supported     | Not supported       | Incompatible with this project |
 
 ## Additional backend methods (not wired into the bridge)
 
@@ -912,3 +933,22 @@ The backend exposes more RPC methods than the bridge uses (sub-agent listing,
 event pull, session usage/close, automation, workspace config, MCP/plugins).
 These have no ACP-side counterpart yet. See [`BACKLOG.md`](./BACKLOG.md) for
 the full list and which are candidates for future support.
+
+## Multi-client semantics (remote access)
+
+When `ZCODE_ACP_REMOTE=1` is enabled, the bridge accepts additional ACP clients
+over WebSocket (via the machine-level hub) alongside the stdio editor. All
+clients share the same backend sessions; the rules below define how one agent
+serves many clients.
+
+| Aspect                                             | Behaviour                                                                                                                                                                                |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session/update` notifications                     | Broadcast to every connected client. A client that never saw a session (e.g. an editor receiving a phone-created session) simply ignores the update.                                     |
+| `session/request_permission`, `elicitation/create` | Sent to every client; the **first response wins**. Losing requests are aborted, which emits `$/cancel_request` so the losing client dismisses its dialog and replies `RequestCancelled`. |
+| Capabilities                                       | OR-merged across clients at each `initialize` (booleans union, `_meta` shallow-merged). A capability any client declares is enabled for interaction routing.                             |
+| Concurrent `session/prompt` on one session         | Serialized by the per-session preempt lock — identical to the single-client case; a second client's prompt preempts or queues the same way.                                              |
+| `session/cancel`                                   | Affects the shared turn regardless of which client sent it.                                                                                                                              |
+| Process lifetime                                   | Follows the stdio client: when the editor disconnects, the bridge (and every remote attachment) exits. Remote clients never extend the lifetime.                                         |
+
+Transport details (hub discovery API, token auth, tunnel notes) live in the
+[Remote Access](../README.md#remote-access) section of the README.