zcode-acp-server 0.1.0 → 0.3.0

package/docs/adr/0002-stateless-hub-over-per-bridge-acp-endpoints.md

@@ -0,0 +1,23 @@
+# Remote access: stateless hub over per-bridge ACP endpoints
+
+Remote clients must reach any active bridge through a single tunneled port
+(Cloudflare Tunnel / frp); exposing one port per bridge does not survive that
+constraint. We decided each bridge serves its own ACP endpoint on loopback
+only (auto-incrementing ports from 8378), and a machine-singleton hub
+(`zcode-acp-hub`, fixed port 8377, auto-spawned detached by bridges, idle-exits
+after ~10 minutes without registrations) does exactly three things: token
+authentication, instance discovery, and byte-level WebSocket proxying
+(`WS /acp?instance=<id>` → the chosen bridge).
+
+The hub has no ACP semantics and no business state; session authority stays
+in the bridges. A remote connection binds to one instance for its whole
+lifetime; switching instances means opening a new connection. We rejected a
+globally-routing gateway that aggregates sessions across bridges and speaks
+ACP itself — it would re-create session management outside the bridges, which
+is the "fat hub" design this project deliberately avoids.
+
+The hub is the only public entry point, so it is the only place that enforces
+the token; the tunnel maps exactly this one port. WebSocket ping/pong
+heartbeat (~30s) is mandatory on both hub and proxy connections because ACP
+streams are silent when idle and proxy layers (notably Cloudflare) drop idle
+connections.

package/docs/adr/0003-tail-replay-meta-and-cursor-pagination.md

@@ -0,0 +1,40 @@
+# Tail replay: extension params ride in _meta, history pages by cursor
+
+`session/load` replays full history to attaching clients, so attach and
+reconnect cost grow with session age (Proposal 0001). Extending the protocol
+for tail replay required three decisions that are now wire contract and hard
+to reverse.
+
+**Extension parameters on spec methods ride in `_meta.zcode`, not top-level.**
+The ACP SDK registers spec methods like `session/load` with a zod
+`z.object` params schema (`zLoadSessionRequest`), and zod's default behavior
+strips unknown keys during `.parse()` — a top-level `limit` would be silently
+removed before our handler ever sees it. `_meta` is the one channel the schema
+preserves (`record(string, unknown)`), and it is also where the ACP spec
+points extension payloads. Responses need no escape hatch: the SDK's response
+mapping for `session/load` is a passthrough, so `replayMeta` rides top-level
+in the result. Our own non-standard method `session/load_earlier` takes a
+bridge-provided parser, so its params stay top-level — the asymmetry is
+intentional and documented in REMOTE-CLIENTS.md.
+
+**`limit` counts messages, aligned back to turn boundaries.** Clients render
+messages (the app shows the last ~30), but turns are the atomic semantic unit
+(a cut must not orphan a tool_call from its updates). The bridge replays at
+most the last `limit` messages, extended backwards to the start of the turn
+containing the oldest one; `limit: 0` attaches with metadata only. A turn
+spans from a user message to the next; leading non-user messages belong to the
+first turn. We rejected turn-count limits — tool-heavy turns make them
+unpredictable for UI budgets.
+
+**Cursor pagination over a full fetch, with expiry.** The backend's
+`session/messages` has no pagination, but the fetch is local stdio IPC — the
+expensive part is the wire to the client, so the bridge fetches all, slices in
+memory, and ships only the tail. The cursor is an opaque base64 of
+`{ id?, index, totalTurns }`: it validates only while the history it points
+into is unchanged (compaction/truncation expires it). An expired or unknown
+cursor returns a fixed `"cursor expired"` error the client maps to a full
+re-`session/load` — we rejected a push-only update log with id-gap fill as
+heavier machinery for the same result. During any replay batch the bridge
+holds a per-session replay lock (patterned on `preemptLocks`) that live-turn
+dispatch for the same session also acquires, so a batch is never interleaved
+with live updates.

package/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root (if it exists) — it points to one `CONTEXT.md` per context. Read each file relevant to the current topic.
+- **`docs/adr/`** — read ADRs related to the area you are about to work on. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If these files don't exist, **continue silently**. Don't flag the absence; don't proactively suggest creating them. The producer skill (`/grill-with-docs`) will lazily create them when terms or decisions are actually resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (root has `CONTEXT-MAP.md`):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (issue title, refactor proposal, hypothesis, test name), use the term defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider), or there's a genuine gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, call it out explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+This repo's issues and PRDs live in GitHub issues. All operations use the `gh` CLI.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filter comments with `jq`, and fetch labels at the same time.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`, add `--label` and `--state` filters as needed.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+The repo is inferred from `git remote -v`; when running inside a clone, `gh` handles this automatically.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+Skills use five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill refers to a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right column to match the vocabulary you actually use.

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,17 +1,17 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.1.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",
   "author": "ZCode ACP Server Contributors",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zcode-org/zcode-acp-server.git"
+    "url": "https://github.com/william0wang/zcode-acp.git"
   },
-  "homepage": "https://github.com/zcode-org/zcode-acp-server#readme",
+  "homepage": "https://github.com/william0wang/zcode-acp#readme",
   "bugs": {
-    "url": "https://github.com/zcode-org/zcode-acp-server/issues"
+    "url": "https://github.com/william0wang/zcode-acp/issues"
   },
   "keywords": [
     "acp",
@@ -23,7 +23,9 @@
     "zcode"
   ],
   "bin": {
-    "zcode-acp-server": "dist/index.js"
+    "zcode-acp-server": "dist/index.js",
+    "zcode-acp-hub": "dist/bin/hub.js",
+    "zcode-quota": "dist/bin/quota.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,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"
@@ -42,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",