@possumtech/rummy 2.1.0 → 2.2.1

package/CLIENT_INTERFACE.md

@@ -1,396 +0,0 @@
-# CLIENT_INTERFACE
-
-Wire-protocol contract for any client that drives a rummy server (nvim,
-CLI, tbench harness, future GUIs). Pulse + query model: the server
-emits a content-free `run/changed` notification when entries land;
-clients reconcile against the entry store on demand.
-
-The entry store is the only source of truth for run progress. The
-server tells the client *that* something changed — never *what*.
-
----
-
-## TL;DR
-
-1. Connect a JSON-RPC websocket; `rummy/hello` to register the project.
-2. `set run://...` (or omit alias) to start a run; you receive `{ alias }`.
-3. Subscribe to **`run/changed`** pulses (notification from server).
-4. On each pulse, call **`getEntries(run, { since, pattern })`** to fetch
-   what's new. The reply is a flat list of insertion-ordered entries.
-   Pass `withBody: true` if you want the body inline (otherwise omit and
-   pull bodies via `getRun` or per-row).
-5. Track the highest `id` you've seen per run; pass it as `since` next pulse.
-6. Resolve any `state: "proposed"` entries by writing back via `set`
-   with `state: "resolved" | "cancelled" | "failed"`.
-7. Drive UI from the entry stream + `runs.status`; the run is complete
-   when its row reaches a terminal status (200/204/413/422/499/500).
-
-No typed payloads. No "render this widget" hints. The store is the
-narrative; the client decides what to show.
-
----
-
-## 1. Connection & handshake
-
-WebSocket JSON-RPC 2.0. Default port `3044`. Send:
-
-```json
-{ "jsonrpc": "2.0", "method": "rummy/hello", "params": {
-    "name": "my-client", "projectRoot": "/abs/path",
-    "clientVersion": "2.0.0"
-  }, "id": 1 }
-```
-
-Reply: `{ rummyVersion, projectId, projectRoot }`. The server enforces
-**MAJOR-version match** between client and server protocol versions and
-rejects on mismatch.
-
-After `rummy/hello`, every subsequent RPC carries the project context
-implicitly — the server knows which project this socket belongs to.
-
----
-
-## 2. Starting a run
-
-```json
-{ "method": "set", "params": {
-    "path": "run://",
-    "body": "Write a brief OC_RIVERS.md ...",
-    "attributes": { "model": "fast", "mode": "act", "yolo": false }
-  } }
-```
-
-The server returns `{ alias }` immediately and kicks off the run async.
-`mode` is `"ask"` or `"act"`. `yolo: true` opts out of client proposal
-resolution (server auto-accepts everything and materializes file edits
-to disk).
-
-Aliases are formatted `<modelAlias>_<unixMs>` (e.g.
-`gfast_1777422716094`). The format is **not a stable public contract**
-— treat the alias as an opaque string and don't parse it. To recover
-the model, read `runs.model` via `getRun`.
-
-To **cancel**:
-```json
-{ "method": "set", "params": {
-    "path": "run://gfast_1777422716094", "state": "cancelled"
-  } }
-```
-
-To **inject a continuation prompt** into an existing run, write to its
-`run://` path with a `body` and `attributes.mode`. To **fork** a run,
-include `attributes.fork: true`.
-
----
-
-## 3. The `run/changed` pulse
-
-The server emits this notification any time an entry write occurs in
-the project. Payload is intentionally minimal:
-
-```json
-{ "method": "run/changed", "params": {
-    "run": "gfast_1777422716094",
-    "runId": 42,
-    "path": "log://turn_3/set/notes.md",
-    "changeType": "insert"
-  } }
-```
-
-The pulse is **content-free** — it does not carry the entry body, the
-run status, telemetry, or render hints. It is only a hint that the
-store has moved. Treat it as a debounce signal.
-
-**Identifiers.** Both `run` (string alias, what you pass to other
-RPCs) and `runId` (integer, the SQLite primary key) are included.
-Clients should key UI state by `run`. `runId` is informational and may
-be useful when multi-tenancy / cross-project bookkeeping requires a
-globally unique key, but you never pass it back to the server.
-
-**Delivery.** Pulses are best-effort and may be coalesced server-side
-during burst writes. Use `since` (§4) for catch-up — a missed pulse is
-recovered on the next reliable pulse by `getEntries(run, { since })`
-returning every entry that landed in the gap. Do not assume one pulse
-per write.
-
----
-
-## 4. Reconciling via `getEntries`
-
-After receiving (or coalescing) one or more pulses for a given run,
-query for the diff:
-
-```json
-{ "method": "getEntries", "params": {
-    "run": "gfast_1777422716094",
-    "pattern": "**",
-    "since": 1234,
-    "limit": 200,
-    "withBody": false
-  } }
-```
-
-**Parameters:**
-
-- **`run`** — alias from `rummy/hello`-then-`set run://`.
-- **`pattern`** — glob over entry path. Default `"*"`. Use `"**"` to
-  mirror everything, `"log://**"` for the audit trail, etc.
-- **`since`** — the highest `id` you've already processed for this run
-  (or `0` / omit on first call). Server returns only entries with
-  `id > since`, ordered by `id` ASC (insertion order).
-- **`limit`** — cap result count; chunk catch-up by re-querying with
-  the new high-water mark.
-- **`scheme`**, **`state`**, **`visibility`** — exact-match filters.
-- **`bodyFilter`** — substring/glob match against entry body content;
-  filters which **rows** are returned by their body. *Not* a body-
-  inclusion knob — for that, see `withBody`.
-- **`withBody`** — when `true`, each returned row carries `body`
-  inline. Default `false` to keep pulse-reconcile traffic lean.
-
-**Returned row shape:**
-
-| Field        | Type                           | Notes                                           |
-|--------------|--------------------------------|-------------------------------------------------|
-| `id`         | integer                        | Monotonic insertion id; the `since` cursor key. |
-| `path`       | string                         | URI-encoded; e.g. `log://turn_1/update/done`.  |
-| `scheme`     | string \| null                 | URI scheme of `path`, or `null` for bare files.|
-| `state`      | string                         | `proposed` / `resolved` / `cancelled` / `failed` / `streaming`. |
-| `outcome`    | string \| null                 | Free-form outcome label (e.g. `not_found`).    |
-| `visibility` | string                         | `visible` / `summarized` / `archived`.         |
-| `turn`       | integer                        | Turn this entry was written in.                |
-| `tokens`     | integer                        | `countTokens(body)` — included even when body isn't. |
-| `attributes` | object                         | Always parsed JSON object (never a string).    |
-| `body`       | string (only with `withBody`)  | Full entry body. Omitted by default.           |
-
-**Important:** when `since` is set, results are ordered by `id` ASC
-(insertion order — what catch-up streams want). When `since` is
-omitted, results are ordered by `path` ASC (browse mode — what
-inventory walks want). Pick the mode that matches your use case.
-
----
-
-## 5. Resolving proposals
-
-Some entries land in `state: "proposed"` — the run is parked waiting
-for the client to decide. Examples: file edits (`log://turn_N/set/...`),
-shell commands (`log://turn_N/sh/...`), `ask_user` prompts.
-
-To accept, reject, or fail a proposal, write back through `set`:
-
-```json
-{ "method": "set", "params": {
-    "run": "gfast_1777422716094",
-    "path": "log://turn_3/set/notes.md",
-    "state": "resolved",
-    "body": ""
-  } }
-```
-
-| Resolution | `state`      | Meaning                              |
-|------------|--------------|--------------------------------------|
-| accept     | `resolved`   | Apply the proposal; server materializes side effects |
-| reject     | `cancelled`  | Drop the proposal; the run continues |
-| error      | `failed`     | The proposal couldn't be applied; the run aborts |
-
-For `ask_user` proposals, put the user's answer in `body`.
-
-The server's response carries `{ status }` reflecting the run's
-**current** status (102 mid-run, terminal at completion). Do **not**
-treat `status >= 200` from a resolve response as terminal — the run may
-still be active. Use the run row's status (via `getRun` or by tracking
-pulses) as authoritative.
-
-If a run was started with `attributes.yolo: true`, you do not need to
-register a resolver — the server auto-accepts every proposal
-server-side and materializes file edits to disk under `projectRoot`.
-For `ask_user` under yolo the server cannot supply a meaningful answer
-on the user's behalf; yolo runs that emit `ask_user` proposals park
-indefinitely (or until cancelled). Treat `ask_user` + yolo as a client
-configuration error.
-
----
-
-## 6. Reading bodies and run state
-
-`getEntries` returns metadata only by default. Two ways to get bodies:
-
-1. **`getEntries` with `withBody: true`** — bodies for matched rows
-   inline. Bandwidth scales with what you query for; bound it with
-   `pattern` / `limit`.
-2. **`getRun(run)`** — full structured snapshot of one run with
-   bodies, telemetry, history, latest prompt and summary. Use on
-   initial open of a run document or after long disconnects.
-
-```json
-{ "method": "getRun", "params": { "run": "gfast_1777422716094" } }
-```
-
-**`getRun` response shape (pinned):**
-
-```json
-{
-  "run": "gfast_1777422716094",
-  "turn": 4,
-  "status": 200,
-  "model": "gfast",
-  "temperature": null,
-  "persona": null,
-  "context_limit": null,
-  "context": {
-    "telemetry": {
-      "prompt_tokens": 1928,
-      "completion_tokens": 75,
-      "total_tokens": 2003,
-      "cost": 0
-    },
-    "reasoning": [ { "path": "reasoning://N", "body": "...", "turn": N } ],
-    "content":   [ { "path": "content://N",   "body": "...", "turn": N } ],
-    "history":   [ {
-      "tool": "set",
-      "path": "log://turn_N/set/notes.md",
-      "status": 200,
-      "body": "...",
-      "attributes": { "action": "set", "status": 200, "...": "..." },
-      "turn": N
-    } ]
-  },
-  "last_user_prompt": "...",
-  "last_summary": "..."
-}
-```
-
-- `attributes` on `history` rows is always a parsed object (never a
-  JSON string).
-- `context.reasoning` and `context.content` carry the model's per-turn
-  reasoning and assistant content respectively. Empty arrays for runs
-  whose model didn't surface those channels.
-- `last_summary` is the body of the most recent `log://turn_N/update/*`
-  entry. `last_user_prompt` is the body of the most recent `prompt://*`
-  entry (the active user prompt for this run).
-
-For incremental updates inside a session, prefer the pulse +
-`getEntries` flow over polling `getRun`.
-
----
-
-## 7. Terminal detection & telemetry
-
-A run's `status` field on its row is authoritative. Terminal statuses:
-`200, 204, 413, 422, 499, 500`. Any other value is in-flight (typically
-`102`).
-
-**Status updates land at `log://turn_N/update/<slug>` with:**
-- `attributes.action = "update"`
-- `attributes.status = <int>` — the integer status code (e.g. `145`,
-  `156`, `167`, `200`)
-- `body` — the human-readable summary text
-
-Latest `update` entry's body is the latest summary. Terminal status is
-detected when:
-1. The `runs.status` row reaches a terminal value (read via `getRun`),
-   **or**
-2. The latest `log://turn_N/update/*` entry's `attributes.status` is in
-   the terminal set.
-
-(1) is the authoritative read; (2) is a convenience for UIs that are
-already watching the entry stream.
-
-**Errors land at `log://turn_N/error/<slug>` with:**
-- `attributes.action = "error"`
-- Body carrying the error detail; `outcome` may carry a short label
-  (e.g. `not_found`, `validation`).
-
-There is no separate `update://` or `error://` URI scheme — these are
-log channels under the audit trail. Filter via `pattern: "log://**/update/**"`
-or `pattern: "log://**/error/**"` if you only want one channel.
-
-**Per-turn telemetry** (token counts, model alias, cached tokens, etc.)
-is in the `turns` table. Surface it by:
-- Calling `getRun(run)` and reading `context.telemetry` (aggregated
-  across all turns of the run), **or**
-- Querying the SQLite store directly if your client runs alongside the
-  server (private optimization, not a wire contract).
-
-Per-turn breakdowns (rather than aggregated) require a direct DB read
-for now; we may add a wire RPC if a need surfaces.
-
-A common UI pattern:
-
-- Maintain a `Map<runAlias, lastSeenId>`.
-- On `run/changed`: `getEntries(run, { since })`, update `lastSeenId`,
-  render new entries inline.
-- For runs in your foreground UI, periodically (every ~2s, or on
-  pulse) fetch bodies for newly-arrived rows via `getEntries` with
-  `withBody: true` filtered by the new `id` range.
-- Detect terminal by watching for `attributes.action === "update"`
-  with `attributes.status` in the terminal set, or by polling
-  `runs.status` via `getRun` on a low cadence.
-
----
-
-## 8. Other notifications
-
-Beyond `run/changed`, the server emits:
-
-| Notification        | Purpose                                                |
-|---------------------|--------------------------------------------------------|
-| `ui/render`         | **Advisory only.** Streaming model output for live thinking displays. Payload shape and cadence are not part of the wire contract; clients may ignore. The entry stream + bodies is the durable record. |
-| `ui/notify`         | Toast-level operator messages. `params: { message, level }`. |
-| `stream/cancelled`  | Server-initiated stream abort; client should kill its local process if it owned the stream. |
-
-A minimal client can ignore all three and still function — the entry
-store carries the durable record.
-
----
-
-## 9. Migrating from the typed-notification protocol
-
-The legacy protocol shipped three typed notifications:
-
-- `run/state` — fired after each turn with status, summary, history,
-  unknowns, telemetry.
-- `run/progress` — turn-status pings ("thinking", "processing").
-- `run/proposal` — pending proposal payload + metadata.
-
-All three are **gone**. Their information is fully derivable from the
-entry store:
-
-| Old surface             | New equivalent                                                   |
-|-------------------------|------------------------------------------------------------------|
-| `run/state.status`      | `runs.status` row field (via `getRun`), or latest `log://turn_N/update/*` with `attributes.status` in terminal set |
-| `run/state.summary`     | latest `log://turn_N/update/*` entry body, or `getRun.last_summary` |
-| `run/state.history`     | `getEntries(run, { pattern: "log://**" })`                       |
-| `run/state.unknowns`    | `getEntries(run, { pattern: "unknown://**" })`                   |
-| `run/state.telemetry`   | `getRun(run).context.telemetry` (aggregated)                     |
-| `run/progress`          | (drop — pulse cadence is sufficient)                             |
-| `run/proposal.proposed` | `getEntries(run, { state: "proposed", since })`                  |
-
-If your client previously closed a document the moment a `run/state`
-arrived with `status >= 200`: do **not** apply the same logic to a
-resolve-RPC response. Track `runs.status` instead.
-
----
-
-## 10. Multi-client semantics
-
-Multiple clients may connect to the same server simultaneously.
-Conflict resolution is **last-write-wins** at the entry-store level —
-two clients resolving the same `(run, path)` proposal will both
-succeed; the second resolution's `state` and `body` overwrite the
-first. The server does not lock or arbitrate.
-
-For UI safety: implement optimistic local state on resolve, but
-re-render from `getEntries` on pulse to absorb any concurrent client's
-write. The pulse will always reach you eventually; don't pessimistically
-lock.
-
----
-
-## 11. Reference
-
-- Server source of truth: `src/server/ClientConnection.js`,
-  `src/plugins/rpc/rpc.js`.
-- Entry store schema: `migrations/001_initial_schema.sql`.
-- Pulse emission point: `hooks.entry.changed` → `run/changed`.
-- Protocol version constant: `src/server/protocol.js`
-  (`RUMMY_PROTOCOL_VERSION`).