zcode-acp-server 0.2.0 → 0.3.0

package/docs/proposals/0001-tail-session-replay.md

@@ -0,0 +1,136 @@
+# Proposal 0001 — Tail session replay with incremental history fetch
+
+Status: implemented (2026-08-17; decisions in ADR-0003, contract documented in
+REMOTE-CLIENTS.md "Tail replay and history pagination") · Date: 2026-08-17 ·
+Affects: ACP endpoint (`session/load`), remote clients
+
+## Problem
+
+`session/load` replays the **entire** conversation as `session/update`
+notifications. This is the attach path AND the reconnect catch-up path
+(REMOTE-CLIENTS.md: "history replay is the recovery mechanism"), so its cost is
+paid on every attach and every reconnect. For long-lived sessions the cost is
+unbounded:
+
+- A real working session measured today replays **2,000+ update chunks**
+  (user/agent/thought/tool) per attach. The mobile client (zcode-acp-app)
+  saturated its main thread for tens of seconds even after shipping windowed
+  rendering — every chunk used to trigger a full React commit. The client now
+  batches replay into single store writes, which fixes rendering, but the
+  **wire transfer, JSON parse, and state application remain O(full history)**
+  on every attach. That part is irreducible client-side.
+- Mobile clients reconnect often (background suspension kills the socket), so
+  the most latency-sensitive clients pay the largest cost, repeatedly.
+- Recovery after a network flap should be fast; instead it grows with session
+  age. The catch-up path degrades exactly when the session is most valuable.
+
+Clients render only the tail (the app renders the last ~30 messages and loads
+older on scroll-up), yet the protocol forces them to receive and process all
+of it up front.
+
+## Transport constraint (verified against SDK 1.3.0)
+
+The SDK registers spec methods with zod `z.object` params schemas; zod's
+default `.parse()` **strips unknown top-level keys**. A top-level `limit` on
+`session/load` would never reach the handler. `_meta` is the preserved
+extension channel, so all bridge extension parameters on spec methods ride in
+`_meta.zcode`. Response fields are unaffected (the SDK's response mapping is a
+passthrough), so `replayMeta` rides top-level in the result. Our own method
+`session/load_earlier` takes a bridge-provided parser, so its params stay
+top-level.
+
+## Proposed API
+
+Additive and backward compatible — omitting the new fields keeps today's
+full-replay behavior byte-identical (Zed sends neither, and is unaffected).
+
+### 1. `session/load` gains an optional tail limit (in `_meta.zcode`)
+
+```json
+{ "sessionId": "…", "cwd": "…", "mcpServers": [], "_meta": { "zcode": { "limit": 30 } } }
+```
+
+- Replays at most the **last `limit` messages, aligned back to the start of
+  the turn containing the oldest one** — never a mid-turn cut, never an
+  orphaned tool_call. A turn spans from a user message to the next; leading
+  non-user messages belong to the first turn.
+- `limit: 0` attaches with **metadata only** (no replay) — for clients that
+  build the connection first and page history on demand.
+- Clamped to `[0, 500]`; invalid values clamp, never error.
+- Result gains replay metadata:
+
+```json
+{
+  "replayMeta": {
+    "cursor": "…",
+    "hasMore": true,
+    "replayedMessages": 47,
+    "replayedTurns": 12,
+    "totalMessages": 1893,
+    "totalTurns": 412
+  }
+}
+```
+
+`cursor` is an opaque bridge-chosen handle identifying the oldest replayed
+turn (clients never interpret it). Both `session/load` and
+`session/load_earlier` results use this same shape.
+
+### 2. New request `session/load_earlier` (params top-level)
+
+```json
+{ "sessionId": "…", "before": "…", "limit": 50 }
+```
+
+- Delivers updates strictly older than `before` as `session/update`
+  notifications — the same delivery mechanism as replay, so clients reuse
+  their existing apply path. Within a batch, updates arrive oldest → newest;
+  the client prepends at the head of its history.
+- Requires the session to already be registered in this bridge (attached via
+  `session/load`); unknown sessions error — pagination never triggers an
+  implicit backend resume.
+- `hasMore: false` ends pagination. A cursor only expires when the history
+  shrank (session compacted/truncated, no longer matching the cursor's
+  anchor); appended turns keep it valid. An expired or unknown cursor returns
+  a fixed `"cursor expired"` error the client maps to a full re-
+  `session/load`.
+
+## Semantics & edge cases
+
+- **Cursor representation** (bridge-internal): opaque base64 of
+  `{ id?, index, totalTurns }`. Valid only while `index` is in range AND the
+  history it points into is unchanged; stable backend message ids are used
+  when present, with index/total as the consistency check otherwise.
+- **Concurrent live turn.** A turn may stream while replay or pagination runs.
+  A per-session replay lock (patterned on `preemptLocks`) is held for the
+  duration of each replay batch, and live-turn dispatch for the same session
+  acquires the same lock — batches are atomic and never interleave with live
+  forwards. Concurrent `load_earlier` calls serialize naturally.
+- **Bridge-side slicing.** The backend `session/messages` RPC has no
+  pagination; the bridge fetches full history (local stdio IPC, cheap) and
+  slices in memory — the wire to the client carries only the tail. A future
+  backend limit parameter can slot in without contract change.
+- **Editor/stdio clients are unaffected** — no `_meta.zcode` ⇒ today's
+  behavior.
+
+## Alternatives considered
+
+- **Top-level `limit` on `session/load`**: rejected — the SDK's zod params
+  parsing strips unknown top-level keys; it cannot work.
+- **Turn-count limit**: rejected — tool-heavy turns make turn budgets
+  unpredictable for UI; message count with turn alignment serves both.
+- **`limit` only, no `load_earlier`**: simpler, but "scroll up for older" then
+  forces a full re-load — the exact cost this proposal removes.
+- **Client-side windowing alone** (shipped in zcode-acp-app today): bounds
+  rendering but not wire/parse/apply; reconnect cost still grows unboundedly.
+- **Push-only history with gap-fill by update id**: requires the bridge to
+  retain an update log keyed by id and clients to track continuity — heavier
+  than cursor pagination for the same result.
+
+## Rollout
+
+1. `_meta.zcode.limit` on `session/load` + `replayMeta` + replay lock
+   (unblocks fast mobile attach).
+2. `session/load_earlier` (unblocks infinite-scroll into history).
+
+REMOTE-CLIENTS.md gains the two parameters once implemented.

package/docs/proposals/0002-plan-quota-usage.md

@@ -0,0 +1,81 @@
+# Proposal 0002 — Expose plan quota usage to remote clients
+
+Status: implemented (bridge `account/usage_stats`, 2026-08-17) · Date: 2026-08-17 · Affects: bridge (new ACP method), remote clients
+
+## Problem
+
+The mobile client now shows the session **context bar** (`usage_update
+{used, size}`) — that part is done. The other "usage" users care about is the
+**plan quota**: how much of the current billing window (e.g. a coding plan's
+prompt allowance) is consumed and when it resets. The editor shows this; a
+remote client has no way to see it.
+
+Today the bridge surfaces nothing for quotas:
+
+- app-server has the RPC (`usageStats: "usage/stats"` in the method enum, plus
+  the `zcode quotas` CLI and `v4/usage/stats` backend endpoint), but the
+  bridge's BACKLOG lists `usage/stats` under **Not planned** ("desktop client
+  / config layer").
+- `session/usage` (per-session tokens) is also unwired (BACKLOG candidate
+  table) — lower value, the context bar already covers session-level usage.
+
+## Proposed API (minimal, pull-only)
+
+Quota is **account-level**, not session-level, so it does not fit a
+`session/update` kind. One request method on the bridge, callable any time
+after `initialize` (no session required):
+
+```json
+{ "id": 7, "method": "account/usage_stats", "params": {} }
+```
+
+Response — shape to mirror whatever app-server's `usage/stats` actually
+returns (fields below are the client's expectation, not a hard contract):
+
+```json
+{
+  "plans": [
+    {
+      "id": "bigmodel-coding-plan",
+      "name": "GLM Coding Plan",
+      "used": 42,
+      "limit": 120,
+      "unit": "prompts",
+      "windowHours": 5,
+      "resetsAt": 1723812000000
+    }
+  ]
+}
+```
+
+Semantics:
+
+- Pull-only v1: the client fetches once after attach and on demand (or every
+  few minutes). No push notification needed yet — quota changes are slow.
+- Non-standard, additive method name (`account/…`); nothing existing changes.
+- Failure should degrade gracefully: error → the client hides the quota UI.
+
+Implementation notes (2026-08-17):
+
+- Data source is the bridge's own `quota/` pipeline (GLM usage API + 10s
+  cache, same as `/quota`), NOT the app-server `usage/stats` RPC — inspected
+  live, that RPC returns token analytics over a time range (per-day token
+  counts, model/tool breakdowns), not billing-window quotas. The wire shape
+  above is adapted accordingly: `usedPercent` is always present; `used`/
+  `limit` only when the API reports absolute counts; `windowHours` is derived
+  from the window id (5h → 5, week → 168).
+- Failures map to JSON-RPC `-32003` with the kind in `data.kind`
+  (`auth_error` | `rate_limited` | `unavailable`).
+
+## Client UI (once available)
+
+Drawer section under Session config: one row per plan showing
+`used/limit` with a small progress bar and a "resets in Xh" hint. Reuse of
+the existing context-bar styling.
+
+## Alternatives considered
+
+- **`usage_update` extension**: wrong scope — that kind is per-session and
+  replayed on attach; quota is account-wide and would replay stale values.
+- **Hub-level `/api/usage`**: violates ADR-0002 (the hub is a stateless byte
+  proxy with no backend connection; only bridges talk to app-server).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",
@@ -24,6 +24,7 @@
   ],
   "bin": {
     "zcode-acp-server": "dist/index.js",
+    "zcode-acp-hub": "dist/bin/hub.js",
     "zcode-quota": "dist/bin/quota.js"
   },
   "main": "dist/index.js",
@@ -35,7 +36,8 @@
     "docs"
   ],
   "dependencies": {
-    "@agentclientprotocol/sdk": "^1.1.0"
+    "@agentclientprotocol/sdk": "^1.3.0",
+    "ws": "^8.21.3"
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
@@ -43,6 +45,7 @@
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^9.0.0",