@zvada/agent-server 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,317 @@
+# Changelog
+
+## 0.3.0
+
+**Breaking.** `WIRE_PROTOCOL_VERSION` 1 → 2. The protocol batch that folds the
+nine-harness survey into one canonical layer: one spelling per concept, ACP's
+vocabulary wherever the concepts overlap, `_meta` everywhere, unknowns
+preserved instead of dropped, and a casing test that fails the build on drift.
+There is no compatibility shim — decode the rename table below.
+
+Also in this batch:
+
+- `verifyStreamContract` (exported from the package root): machine-checkable
+  stream-contract verification — ordering rules plus projection agreement
+  (the reducer's final state must match the authoritative snapshots). The
+  CLI grows `run --verify` (exit 1 on violation); every live harness/wire
+  test is contract-checked.
+- Honest cancels in the pre-first-yield window: a `turn/cancel` that lands
+  between the `turn/start` quick-ack and the harness registering its
+  abortable turn now answers `{outcome: "unconfirmed"}` (the abort landed on
+  nothing and the turn may run to completion) instead of a clean `cancelled`.
+- `session/close` broadcasts `session.ended {reason: "released"}` on the
+  stream (consuming one seq) — subscribers learn the terminal fact from the
+  stream itself, not from the closer's RPC result.
+- Reasoning parts carry text again on Fable-class models: the claude harness
+  opts into thinking summaries (`--thinking-display summarized` via
+  `extraArgs`; operator `extraArgs` still wins per-key), and the adapter keeps
+  the `estimated_tokens` placeholder as
+  `providerMetadata.estimatedThinkingTokens` when text is withheld. The
+  claude pin holds at 0.3.220 — CLI 2.1.233 ignores the display flag and
+  streams token-estimate placeholders instead; bump only after re-verifying
+  summaries flow.
+
+### The rename table (old → new)
+
+- `parentToolUseId` → `parentToolCallId` (on parts and `message.started`;
+  REMOVED entirely from `message.part` / `message.part.delta` events — the
+  part carries it)
+- Delta types: `"text-delta"` → `"text"`, `"reasoning-delta"` → `"reasoning"`,
+  `"tool-input-delta"` → `"tool_input"`
+- Event `"session.compacted"` → `"session.compaction"` (now an upsert entity:
+  REQUIRED new fields `compactionId: string`,
+  `status: "in_progress"|"completed"|"failed"|"cancelled"`; optional `summary`,
+  `abstractsIds`)
+- `error` event: `{error: string, code?: string}` →
+  `{category: ErrorCategory, message: string}` (`recoverable`/`stack`
+  unchanged)
+- `turn.ended.error`: `{name, message}` → `{category, message}`
+- `PermissionMode` values: `"acceptEdits"` → `"accept_edits"`, `"dontAsk"` →
+  `"dont_ask"`, `"bypassPermissions"` → `"bypass_permissions"` (engine-side
+  values; SDK-facing values in adapters stay camelCase — the adapters map)
+- `PartInput`/parts: `mediaType` → `mimeType`
+- `TurnCancelResult`: `{cancelled: boolean, confirmed?, activeTurnId?}` →
+  discriminated union `{outcome:"cancelled",turnId}` |
+  `{outcome:"unconfirmed",turnId}` | `{outcome:"no_active_turn",activeTurnId?}`
+- `ToolState`: new fifth status `"cancelled"` `{status,input,time{start,end}}`;
+  `completed.title` now OPTIONAL (no more default-to-`toolName`); `completed`
+  gains optional `content?: ToolResultContent[]` and `metadata?`
+- `TOOL_STATUSES` → **`RUNTIME_TOOL_STATUSES`**, `ToolStatus` →
+  **`RuntimeToolStatus`** (`ToolStatusSchema` → `RuntimeToolStatusSchema`).
+  The rename marks a deliberate deviation from §2, which lists `ToolStatus`
+  among the OPEN vocabularies: this union is **closed**. The status is a
+  STRUCTURAL discriminator here — each status carries its own payload
+  (`pending.partialInput`, `in_progress.time{start}`, `completed.output`,
+  `failed.error`, `cancelled.time{start,end}`) — so an unknown status has no
+  decodable body and would only ever be a shape nothing can render. New
+  statuses are protocol additions (a new arm), not producer extensions; the
+  `Runtime` prefix says which set you are importing. Raised against the spec
+  rather than silently diverging — if §2 wins, the fix is an
+  `UnknownToolState {status, input?, _meta?}` arm, not a re-opened union.
+- `classifyError` fallback category renamed `"unknown"` → `"internal"`
+- ALL `message.*` events now carry `sessionId`; `message.started` gained
+  `model?`, lost its `metadata` bag
+- Every event / part / tool state has optional `_meta`
+- Reducer: `ConversationState.messages`/`compactions` replaced by a unified
+  `timeline: Array<ConversationMessage|ConversationCompaction>`
+  (kind-discriminated: `kind:"message"`/`"compaction"`); helper
+  `conversationMessages(state)`; new state fields `ended?`, `unknownEvents`;
+  `reduceConversation` also accepts an `UnknownEvent` and preserves it
+
+### New
+
+- **The user echo (§7.2).** Every turn now opens with the submitted input
+  echoed back as a complete user message —
+  `message.started{role:"user", outputIndex:0}` → one `message.part` per input
+  part → `message.ended` — before any harness output. Assistant messages now
+  start at `outputIndex: 1`. The stream is a complete transcript: multi-client
+  attach, replay, and persistence no longer need the client's own copy of the
+  prompt. The echo's ids are DERIVED from the turn id (`echo-${turnId}` — see
+  Consumer machinery below), so a consumer that minted the turnId predicts
+  the whole echo instead of reconciling against it.
+- **`session.ended {reason}`** — `idle` | `replaced` | `released` |
+  `shutdown` (OPEN). `ConversationState.ended` records it.
+- **`session.compaction` as a positional, ID-addressed entity.** First
+  appearance anchors its place in the timeline; later upserts advance
+  `status`/`summary` in place without moving or restamping it. A failed
+  compaction is representable instead of a stream that goes quiet.
+- **Structured tool output (three audiences).** `output` (string) stays the
+  model-facing record and rendering fallback; `content?: ToolResultContent[]`
+  (`text` | `image` | `diff` | `terminal`) is the display-grade view;
+  `metadata?` is the machine channel. The claude-code adapter now populates
+  `content` for text and image result blocks instead of only flattening.
+- **Subagent metadata.** `Task`-style spawns populate
+  `subagent {type, description, model, agentId?}` from the tool's input, and
+  `kind: "task"` is derived from its PRESENCE — no more tool-name allowlists.
+- **`reasoning.time` and `providerMetadata` are real.** The claude-code adapter
+  stamps `time.start`/`time.end` across a thinking block and marks
+  `redacted_thinking` with `providerMetadata: {redacted: true}` instead of
+  collapsing it into plain reasoning.
+- **Unknown preservation (Law 6).** `decodeLifecycleEvent` keeps an unknown
+  event type in order as `{type, raw}` rather than dropping it; the reducer
+  collects them in `state.unknownEvents`. Known types with malformed bodies
+  still fail loudly.
+- **Cancellation closure.** At `turn.ended{stopReason:"cancelled"}` the reducer
+  transitions the turn's non-terminal tool parts to `status:"cancelled"` — a
+  cancelled turn can no longer strand tools as `in_progress` forever.
+- **One casing test (Law 9).** `test/protocol/casing.test.ts` walks every enum,
+  discriminator and field name in the vocabulary and fails on a Law-2
+  violation. The two documented kebab exceptions (`AGENT_HARNESSES`,
+  `ModelSwitchMode`) are excluded explicitly.
+- **Permissions actually offer what the schema advertises (§6.4).** The broker
+  now offers all four option kinds (`allow_once`, `allow_always`,
+  `reject_once`, `reject_always`), and an `*_always` answer becomes a standing
+  per-session rule: later calls to that tool are answered without a round-trip
+  and without synthesizing a prompt event that never happened. Rules are
+  cleared by `session/close`.
+- **`permission.resolved.outcome.updatedInput` is honoured.** An edited input
+  travels `PermissionDecision {decision:"allow", updatedInput?}` into the
+  claude-code harness's `canUseTool` return, so what was approved is what runs.
+  Codex and ACP have no slot for it in their approval replies — documented at
+  both call sites rather than silently dropped.
+- **Law 6 on the paths that carry traffic.** `decodeLifecycleEvent` is now what
+  the wire client uses: an unknown event type is DELIVERED (advancing `seq`,
+  so it can never be mistaken for a gap) as `UnknownEvent`, and `events/replay`
+  decodes envelope-by-envelope so one unknown event cannot poison the buffer
+  that heals a gap. New `decodePart` gives `message.part` a lenient part
+  decoder — an unknown part type is preserved as
+  `UnknownPart {type, id, sessionId, messageId, parentToolCallId?, raw}` in its
+  message instead of failing the event. **Breaking for consumers**:
+  `TurnHandle.events`, `onEvent` and `client.replay()` are typed
+  `DecodedLifecycleEvent | UnknownEvent` — narrow with `isUnknownEvent` /
+  `isUnknownPart` (`reduceConversation` already accepts the union).
+- **Law 5 is enforced, not just documented.** One `EpochMsSchema`
+  (integer, non-negative, rejects `-0`) types every event `timestamp` and every
+  nested `time.start`/`time.end` on tool states and reasoning parts. A
+  seconds-based or fractional stamp is now a parse error instead of a value
+  that sorts wrong in production.
+- Open vocabularies reject blank values (`""`, `"   "`) while still accepting
+  unknown ones — one `openVocabulary()` helper instead of six casts. New
+  `COMPACTION_TRIGGERS` (`auto` | `manual`, OPEN) types
+  `session.compaction.trigger`, and `ConversationState.harness` is the closed
+  `AgentHarness` again instead of a widened `string`.
+- Image and file parts now ENFORCE §4's "exactly one of `data` | `url`" on the
+  output side, as the input side already did.
+- Cancellation closure preserves a pending tool's streamed JSON under
+  `_meta["agent-server/partialInput"]` (`PARTIAL_INPUT_META_KEY`) instead of
+  dropping what the call was about; `emptyConversation().totals` now uses the
+  same zero shape as `DEFAULT_TOKEN_USAGE`.
+- `verifyStreamContract` fixes two false positives that failed LEGAL streams:
+  a cancelled turn's trailing deltas (a snapshot is a prefix of the fold, not
+  a ceiling) and multi-turn sessions (`session.created` is per turn, since the
+  engine re-announces it on every turn's first yield). Its vacuous
+  "refold the same stream" determinism check is replaced by a real re-delivery
+  probe: every upsert-shaped event delivered twice must leave the timeline,
+  per-message part counts, resolved permissions and billing totals unchanged.
+- The CLI renderer now folds the stream with `reduceConversation` instead of
+  hand-rolling two switch statements over the event union — the reference
+  implementation is dogfooded, as `docs/consuming.md` tells consumers to do.
+- Deliberately absent under Law 7 (advertise nothing you don't deliver): §8's
+  `InitializeResult.experimental` (no experimental capability to gate yet) and
+  §12's `docs/rfds/` (no RFD process while the protocol has one implementation).
+
+### Consumer machinery
+
+- **Restart detection is a handshake fact, not an inference.** `initialize`
+  returns a per-process `instanceId`; `AgentServerClient` re-initializes on
+  every reconnect (also failing loudly on a version mismatch instead of
+  silently talking to a different build) and adopts the fresh session logs
+  when the id changed. This replaced four separate seq-pattern heuristics
+  (live seq-1 reset with drain choreography, a content compare at the
+  watermark, replay-side `latestSeq` adoption) with one stated fact; a
+  minimal seq-layer `reset` arm remains as defense-in-depth for
+  handshake-less consumers.
+
+The machinery every consumer of this stream wrote for itself. Each item below
+replaces a **counted** duplication in a shipping product — three drifting
+copies of one predicate, two hand-rolled seq cursors, a transport attached
+purely to sniff its own wire — not a hypothetical need (Law 7). Together they
+retire ~570 lines of product code plus their tests.
+
+- **`isCleanStop` / `isFailureStopReason` / `CLEAN_STOP_REASONS`.** Did the
+  turn finish the way it was supposed to? `cancelled` is CLEAN (the user asked
+  for the stop); `error` is not; and because `StopReason` is OPEN, anything
+  this build does not recognize — a newer engine's value, an adapter's
+  `_`-prefixed extension, `undefined` — classifies as a FAILURE. That
+  direction is deliberate: a failure affordance on an outcome we cannot
+  interpret is recoverable, an unknown outcome rendered as success is not.
+  The three copies in the wild disagreed on `max_turn_requests`, on `refusal`,
+  and — in opposite directions — on what to do with an unknown value.
+- **`createSeqCursor()`** (`/protocol`): per-session `seq` bookkeeping as a
+  pure, dependency-free object — `advance(sessionId, seq)` →
+  `"deliver" | "duplicate" | "gap" | "reset"`, plus `reset`, `seek`, `last`,
+  `sessions`. `AgentServerClient` is now implemented ON it (one
+  implementation, not two), so a consumer that folds envelopes forwarded over
+  its own transport gets the client's exact semantics, including the
+  restart-at-1 `reset` verdict that keeps a post-restart stream from being
+  dropped as duplicates.
+- **`parseAgentInput(value)`** (`/protocol`): decode an untrusted value into
+  an `AgentInput`, or throw `invalid agent input: <path>: <why>`. The schema
+  was always the contract; the hand-rolled decoders in front of it were where
+  tolerance for shapes the engine never accepted crept in.
+- **`AgentServer.onEvent(cb)`**: observe every broadcast envelope in-process,
+  already sequenced and appended to the session log, returning an
+  unsubscribe. Synchronous, and an observer that throws is isolated exactly
+  like a faulty transport. Replaces attaching a fake transport to the server
+  in order to parse one's own NDJSON back into objects.
+- **zod-free subpaths**: `@zvada/agent-server/protocol/factories`,
+  `@zvada/agent-server/protocol/guards`, `…/protocol/stop-reasons`,
+  `…/protocol/seq-cursor` and `…/protocol/selectors`. `PART_TYPES`,
+  `LIFECYCLE_EVENT_TYPES`, `isKnownPartType`, `isUnknownPart`,
+  `isKnownLifecycleEventType` and `isUnknownEvent` moved into
+  `src/protocol/guards.ts` — **still exported from the root and `/protocol`**,
+  nothing moved for existing importers. The subpaths let a browser bundle
+  import a part constructor or a membership test without pulling zod and the
+  whole contract in behind it; a test walks their transitive runtime import
+  graph and fails if a package ever appears in it.
+- **Selectors** (`/protocol`), pure functions over `ConversationState`:
+  `groupIntoTurns` (consecutive same-role, same-turn runs of the timeline,
+  with `isLatest` true for the final group ONLY — the guard that stops a
+  finished turn from re-entering streaming UI when the next prompt lands),
+  `subagentGroups` (parented messages keyed by their spawning `toolCallId`),
+  `agentActivity` (`thinking` | `generating` | `tool_running` |
+  `tool_failed` | `idle`, from the last part of the last top-level assistant
+  message of the last active turn), and `toolResultText` (completed →
+  `output`, failed → `error`, otherwise `""`).
+- **Deterministic echo ids — BREAKING for anyone reading structure into them.**
+  The user echo's message id is now `echo-${turnId}` (`echoMessageId`) and its
+  part ids `echo-${turnId}-${index}` (`echoPartId`), instead of freshly minted
+  UUIDv7s. `createUserEchoParts(input, turnId)` takes the turn id and stamps
+  them. A documented exception to Law 8: the echo is not new information, it
+  is the caller's own input played back, exactly once per turn — so a consumer
+  that minted the `turnId` can predict the echo byte-for-byte and render its
+  optimistic bubble AS the echo (same ids, same parts) instead of reconciling
+  a look-alike and swapping it. Ids remain opaque to peers; this is a producer
+  rule with a matching consumer helper, not a licence to parse ids elsewhere.
+- **`reduceConversationWithChanges(state, event)`** →
+  `{state, changes: ConversationChange[]}` (`/protocol`): the same fold, plus
+  the list of what it touched, for sinks that must WRITE rather than
+  re-render — which rows to upsert, which queries to invalidate.
+  `ConversationChange` (zod-typed, exported) is a discriminated union of
+  `message-upserted` · `part-upserted` · `message-ended` · `delta-buffered` ·
+  `turn-updated` · `compaction-upserted` · `permission-updated` ·
+  `usage-updated` · `session-meta-updated` · `session-ended` ·
+  `unknown-event-recorded`. The changes are RECORDED by the fold, not diffed
+  from its output: `reduceConversation` is this function with the recorder
+  thrown away, so the two cannot drift. A fold that changes nothing (a
+  replayed duplicate) reports nothing; the cancellation closure reports one
+  `part-upserted` per tool it closed.
+
+## 0.2.3
+
+- **`reduceConversation`** (root / `./protocol`): the canonical
+  LifecycleEvent → conversation-state reducer. Pure, copy-on-write fold that
+  encodes the stream's consumption rules — part upsert by `part.id`
+  (including late tool completions landing in their original message),
+  authoritative snapshots over streamed deltas, exactly-once permission
+  resolution, the gauge/billing-totals distinction. Ships with
+  `emptyConversation()` and `pendingPermissions()`. Replaces the fold every
+  consumer had been writing by hand.
+- **`onSessionEnd`** (`ClaudeCodeAgentOptions`): fires exactly once when a
+  live session's subprocess ends, with why — `idle` | `replaced` |
+  `released` | `shutdown`. The seam for host-managed per-session resources
+  (BYOK proxy keys, recorders).
+- **`onDiagnostic`** (`CreateRegistryOptions`, `AgentRuntime` options,
+  `createAnthropicProxy` options): operational signals the engine previously
+  swallowed — `interruptTimeout`, `resumeFallback`, `sinkError`,
+  `proxyUpstreamAuth`. Handler errors can never break a turn.
+
+## 0.2.2
+
+- **Idempotent turn admission.** `AgentRuntime.run` converges a duplicate
+  `{sessionId, turnId}` with identical input onto the in-flight promise or
+  the memoized summary (bounded per-session window, released by
+  `session/close`) — a retried RPC can never double-execute a turn. Same ids
+  with different input throw `TurnConflictError`. `runtime.admission()` is
+  the pure probe; `turn/start` delegates (`deduplicated: true` acks, wire
+  error `turnConflict`). Registration precedes execution start, so even a
+  synchronous reentrant sink converges.
+- **Confirmed, turn-stamped cancels.** `Agent.cancel` returns
+  `{confirmed, hadTurn}`; `interruptTurn()` reports the SDK round-trip
+  outcome instead of swallowing it; `turn/cancel` accepts a `turnId` stamp
+  and refuses a stale one with `activeTurnId` instead of killing the
+  successor turn. Claude aborts before interrupting, fixing a race where a
+  clean cancel could surface as `error`.
+- **Bun-proof BYOK proxy.** SSE bodies pipe through a fresh stream
+  (downstream disconnects propagate upstream — no leaked sockets); non-SSE
+  responses drop stale `content-encoding`/`content-length`/
+  `transfer-encoding`; structured 502 on unreachable upstreams; injectable
+  `fetch`. Media-type detection parses instead of substring-matching.
+- Turn-end ordering hardened: `turn.ended` never starts before any
+  `permission.resolved` emission completed, regardless of who settled it.
+- Empty-string session/turn ids are rejected at the wire schema.
+- `toolPolicy` receives the SDK's full `canUseTool` context (signal,
+  suggestions, blockedPath, decisionReason).
+
+## 0.2.1
+
+- codex-app-server: an `item/completed` carrying `text: ""` no longer
+  clobbers reasoning text accumulated from `summaryTextDelta`s — thoughts
+  persist in the terminal snapshot consumers store.
+
+## 0.2.0
+
+- The four packages (`@zvada/agent-server-{protocol,core,server,client}`)
+  consolidated into **one package** with subpath seats: root = the wire
+  contract, `./core` (+ `./core/proxy`), `./server` (ships the
+  `agent-server` bin), `./client`. The old four are deprecated on npm.

package/README.md

@@ -18,9 +18,9 @@ One package, four seats — pick the subpath for how you consume it:
 ## Embed the engine
 
 ```ts
-import { AgentRuntime, callbackSink, createAgentRegistry } from "@zvada/agent-server/core";
+import { callbackSink, createAgentRuntime } from "@zvada/agent-server/core";
 
-const runtime = new AgentRuntime(createAgentRegistry({ provision: { mode: "pinned" } }));
+const runtime = createAgentRuntime({ provision: { mode: "pinned" } });
 await runtime.run(
   {
     sessionId: "s1",
@@ -69,6 +69,19 @@ npx --yes agentic-feedback@latest --to agent-server --category <api|cli|docs|oth
 Continue a thread with `--resume <threadId>` (printed after each submission).
 `DO_NOT_TRACK=1` strips auto-detected context. Only specific, actionable reports.
 
+## Consume the stream
+
+Fold events with the shipped canonical reducer instead of hand-rolling a
+`switch` — it encodes the upsert/delta/permission rules consumers get wrong
+first (see [docs/consuming.md](docs/consuming.md) for the full recipe):
+
+```ts
+import { emptyConversation, reduceConversation } from "@zvada/agent-server";
+
+let conversation = emptyConversation();
+for await (const event of turn.events) conversation = reduceConversation(conversation, event);
+```
+
 ## Notes
 
 - Ships as TypeScript source (Bun-first; the client and stdio/dial server
@@ -77,8 +90,11 @@ Continue a thread with `--resume <threadId>` (printed after each submission).
 - The wire vocabulary tracks the
   [Agent Client Protocol](https://agentclientprotocol.com) where concepts
   overlap.
-- Full docs, architecture, and the live test harness live in the
-  [repository](https://github.com/zvadaadam/agent-server).
+- Shipped guides: [docs/consuming.md](docs/consuming.md) (integration recipe),
+  [docs/harnesses.md](docs/harnesses.md) (per-harness support matrix),
+  [docs/deploy.md](docs/deploy.md) (provisioning, single binary, sandboxes),
+  [CHANGELOG.md](CHANGELOG.md). Architecture and the live test harness live in
+  the [repository](https://github.com/zvadaadam/agent-server).
 - Supersedes the four split packages `@zvada/agent-server-{protocol,core,server,client}`
   (now deprecated); the subpaths above are their one-to-one replacements.
 

package/docs/consuming.md

@@ -0,0 +1,269 @@
+# Consuming the agent-server stream
+
+The integration recipe, written down once — every rule here was re-derived
+independently by at least one real consumer before it landed in this file.
+
+## Fold events with the shipped reducer
+
+Do not hand-roll a `switch (event.type)` state fold. The package ships the
+canonical one:
+
+```ts
+import { emptyConversation, reduceConversation, pendingPermissions } from "@zvada/agent-server";
+
+let conversation = emptyConversation();
+for await (const event of turn.events) {
+  conversation = reduceConversation(conversation, event); // pure, copy-on-write
+  render(conversation);                                    // React-friendly identities
+  for (const request of pendingPermissions(conversation)) prompt(request);
+}
+```
+
+The reducer encodes the rules consumers get wrong first:
+
+- **Every turn starts with your own prompt echoed back.** See below — this is
+  the rule that surprises consumers upgrading to 0.3.0.
+
+- **Upsert parts by `part.id`.** A tool part can complete AFTER its message —
+  or its turn — ended; the event's `messageId` names the original message and
+  the upsert lands there. If you persist per-event, your writes must be
+  upserts, never inserts.
+- **Snapshots are authoritative; deltas are streaming sugar.** `message.part`
+  replaces whatever `message.part.delta`s built. Never append a snapshot's
+  text onto delta-accumulated text.
+- **`turn.ended.tokens` ≠ `session.usage`.** The first is the turn's billing
+  total (sum for spend); the second is the live context-window gauge (render
+  for "how full"). Different numbers, both kept by the reducer.
+- **Permissions resolve exactly once.** Turn end or cancel resolves pending
+  requests as `cancelled`; you will always observe a `permission.resolved`
+  before that turn's `turn.ended`.
+
+Branch on the outcome with `isCleanStop` / `isFailureStopReason` rather than
+your own list: `cancelled` is clean (the user asked for the stop), `error` is
+not, and because `StopReason` is OPEN, anything neither this build nor yours
+recognizes counts as a failure — the safe direction.
+
+## Fold with changes when you WRITE
+
+Rendering needs the state; persisting needs to know what moved. Use
+`reduceConversationWithChanges` and let the fold tell you:
+
+```ts
+const { state, changes } = reduceConversationWithChanges(previous, event);
+for (const change of changes) {
+  switch (change.kind) {
+    case "message-upserted": upsertMessageRow(state, change.messageId); break;
+    case "part-upserted":    upsertPartRow(state, change.messageId, change.partId); break;
+    case "turn-updated":     upsertTurnRow(state, change.turnId); break;
+    // …message-ended · delta-buffered · compaction-upserted · permission-updated
+    // usage-updated · session-meta-updated · session-ended · unknown-event-recorded
+  }
+}
+```
+
+The changes are recorded BY the fold, not diffed from its output —
+`reduceConversation` is the same function with the recorder discarded, so
+there is no second implementation to drift. A fold that changed nothing (a
+replayed duplicate) yields `[]`, which is your cue to skip the write
+entirely. SQL semantics stay yours: `ON CONFLICT` vs `REPLACE`, `COALESCE`
+guards, and which columns are yours to own are schema knowledge, not fold
+knowledge.
+
+## Project the state with the shipped selectors
+
+Four pure functions over `ConversationState`, so a UI does not re-derive them:
+
+- `groupIntoTurns(state)` — turn cards: consecutive entries of the same turn
+  and the same speaker. `isLatest` is true for the FINAL group only; render
+  streaming affordances on it and nothing else, or the moment the next
+  prompt's echo lands the previous — completed — answer flips back into
+  "working".
+- `subagentGroups(state)` — parented messages keyed by the `toolCallId` that
+  spawned them, to nest under that tool card (and to filter out of the main
+  flow, or the subagent's work prints twice).
+- `agentActivity(state)` — `thinking` | `generating` | `tool_running` |
+  `tool_failed` | `idle`, from the last part of the last top-level assistant
+  message of the last ACTIVE turn. `idle` during an active turn means
+  "between observable activities", not "finished" — combine it with your own
+  busy flag.
+- `toolResultText(toolPart.state)` — the display fallback: completed →
+  `output`, failed → `error`, everything else → `""` (deliberately empty, not
+  invented placeholder prose).
+
+## Track `seq` with the shared cursor
+
+If you fold envelopes yourself — forwarded over your own WebSocket, replayed
+from a log — use `createSeqCursor()` instead of comparing numbers by hand:
+
+```ts
+const cursor = createSeqCursor();
+switch (cursor.advance(envelope.sessionId, envelope.seq)) {
+  case "deliver":   return fold(envelope.event);
+  case "duplicate": return;                       // already folded
+  case "gap":       return holdAndReplay(envelope); // request events/replay
+  case "reset":     return dropLocalStateAndFold(envelope); // the log restarted at 1
+}
+```
+
+`reset` is the one that is easy to get wrong: a restarted server begins the
+session log at 1 again, and treating that as a duplicate silently discards the
+entire post-restart stream. `duplicate` and `gap` leave the cursor untouched,
+so healed events still land in order. `AgentServerClient` uses this exact
+object — there is no second implementation.
+
+Restarts themselves are not guessed from seq patterns on the wire: `initialize`
+returns a per-process `instanceId`, the client re-handshakes on every
+reconnect, and a changed id adopts the fresh logs outright (cursors reset,
+sessions resynced from seq 1). The `reset` verdict remains for consumers that
+fold envelopes without a handshake of their own.
+
+## Render by role — the turn opens with the user echo
+
+Every turn now begins with the submitted input echoed back as a complete user
+message, before any harness output:
+
+```text
+turn.started
+  message.started {role: "user", outputIndex: 0}   ← the echo
+    message.part*                                  ← one per input part, state "done"
+  message.ended
+  message.started {role: "assistant", outputIndex: 1}   ← the model's reply
+  ...
+turn.ended
+```
+
+Consequences, in the order they bite:
+
+- **A consumer that renders every `message.part` as model output now prints the
+  user's own prompt.** Filter by the role of the part's message — never by
+  position. `conversationMessages(state)` gives the timeline's messages in
+  order, each with its `role`, so `messages.filter(m => m.role === "assistant")`
+  is the whole fix.
+- **`outputIndex: 0` is the echo; assistant messages start at 1.** Anything
+  keyed on "the first message of the turn is the model's" needs re-keying.
+- **The echo is predictable — don't reconcile, PREDICT.** Its ids are derived
+  from the turn id you minted:
+
+  ```ts
+  const turnId = generateUUIDv7();
+  renderOptimistically({
+    messageId: echoMessageId(turnId),        // `echo-${turnId}`
+    parts: createUserEchoParts(input, turnId), // ids `echo-${turnId}-${index}`
+  });
+  await client.runTurn({ turnId, input, config });
+  ```
+
+  The echo that arrives upserts onto your optimistic bubble by id: same
+  message, same parts, byte for byte. No placeholder to swap, no window where
+  the prompt renders twice, and multimodal parts survive (the swap-a-look-alike
+  approach is where file and image parts got dropped). These two are the
+  documented exception to engine-minted UUIDv7 ids — everything else on the
+  wire stays opaque, and nothing may parse structure out of an id.
+- The stream is now a complete transcript. Multi-client attach, replay and
+  persistence no longer need the client's private copy of the prompt — which
+  is the point: a second UI attaching mid-turn sees what was asked.
+
+`session.created` is unrelated to this ordering and lands **mid-turn** (it
+carries the harness-native id, which does not exist until the harness's first
+yield). Persist it whenever it arrives.
+
+## Tolerate the unknown
+
+The client delivers events it does not recognize instead of dropping them: a
+newer server's event type arrives as `UnknownEvent {type, sessionId?, raw}`,
+and an unknown part type inside a known `message.part` as
+`UnknownPart {type, id, sessionId, messageId, raw}`. Both keep their place in
+the order, and the unknown event still advances the per-session `seq` — a
+dropped event would read as an unfillable gap and kill the turn handle.
+
+`reduceConversation` accepts the union as-is (unknown events land in
+`state.unknownEvents`, unknown parts in their message's `parts`). In your own
+code, narrow with `isUnknownEvent` / `isUnknownPart` before switching on a
+known `type`, and **store and forward what you don't understand** — a
+round trip through your persistence layer must not be where a newer server's
+data disappears. A known type with a malformed body still fails loudly.
+
+## Persist for resume
+
+Store `state.nativeSessionId` (from `session.created`) keyed by your logical
+`sessionId`, and pass it back as `config.resumeSessionId` to continue a
+conversation later — across processes and machines. Check
+`session.created.resumed` on resume turns: `false` means the harness fell
+back to a fresh session (context lost) — surface that, never swallow it.
+Compare with the flag, not ids: a successful Claude resume mints a NEW native
+id.
+
+## Retry safely
+
+Turn admission is idempotent on `{sessionId, turnId}`: mint the `turnId`
+client-side, and a retried `turn/start` (or embedded `runtime.run`) with the
+identical request converges on the original execution — the wire acks it with
+`deduplicated: true` and `events/replay` fills anything you missed. The same
+`turnId` with different input fails loudly (`turnConflict` /
+`TurnConflictError`). This is what makes at-least-once RPC layers (Durable
+Object retries, queue redelivery) safe over the engine.
+
+## Cancel honestly
+
+`turn/cancel` (and `runtime.cancel`) accept a `turnId` stamp — always pass
+the id of the turn you mean, so a late cancel can never kill its successor
+(a stale stamp returns `{outcome: "no_active_turn", activeTurnId}`). The
+result is a single-outcome union: `cancelled` means the harness confirmed the
+interrupt; `unconfirmed` means it did not land — including the window between
+the `turn/start` quick-ack and the harness registering its abortable turn —
+and the agent may still be running. On `unconfirmed`, report "stopping…" and
+treat `turn.ended` as the source of truth, not the cancel response.
+
+## Verify the stream
+
+`verifyStreamContract(events, {seqs?})` machine-checks a recorded stream
+against the ordering/delivery contract — echo-first, bracket pairing,
+upsert-address stability, delta-follows-snapshot, permissions resolve-once,
+seq monotonicity — then folds it twice: once to assert the reducer's final
+state agrees with the authoritative snapshots, and once with every upsert
+delivered TWICE to assert re-delivery changes nothing (the property a replay
+overlap or a reconnect resync depends on). Run it in CI over recorded fixtures
+and in staging over live turns (`agent-server run "…" --verify` exits 1 on any
+violation); a product pipeline (a Durable Object, a persistence shim) can run
+it on replay to fail loudly instead of storing a corrupt projection.
+
+It takes **one session's** stream, of any length: `session.created` is expected
+once per turn (not once per stream), deltas that trail the last snapshot of a
+cancelled turn are legal (a snapshot is a prefix of the fold, not a ceiling),
+and unknown event/part types are forward-compat rather than violations. Pass
+`{expectEcho: false}` for a partial capture that begins mid-turn.
+
+## Own your session resources
+
+Register `onSessionEnd` (claude options) to release per-session resources —
+BYOK proxy keys, recorders — instead of re-deriving termination from side
+effects. Reasons: `idle` (idle-timeout eviction), `replaced` (config change
+restarted the subprocess — usually respawns immediately with context kept),
+`released` (explicit close), `shutdown`. On the wire, call `session/close`
+when a logical session will not be resumed: it frees the replay buffer and
+the harness-native state (until then, memory cost ≈ `bufferSize` events per
+session).
+
+`session/close` also broadcasts `session.ended {reason: "released"}` — but
+only to subscribers **connected at that moment**, because the replay log is
+retired in the same operation. A subscriber that was detached does not get the
+event later: its `events/replay` answers `unknownSession`, and that answer *is*
+the terminal signal (the session is gone; nothing more will be appended to it).
+Treat `unknownSession` on replay as "session over", not as an error to retry.
+
+## Listen to the engine's diagnostics
+
+Pass `onDiagnostic` (registry/runtime/proxy options) and log what arrives:
+`interruptTimeout`, `resumeFallback`, `sinkError`, `proxyUpstreamAuth`.
+These are the signals the engine deliberately does not fail turns over — a
+product that doesn't surface them debugs blind.
+
+## Wire transports
+
+`spawn` (stdio subprocess), `connect` (dial a `--listen` server; reconnects
+and replays by default), `attach` (an accepted socket, e.g. the server dialed
+OUT to you via `--dial`). The client dedupes by per-session `seq` and heals
+gaps via `events/replay`; an unfillable gap raises `EventGapError` instead of
+silently losing events. The WebSocket wire itself carries no auth — keep it
+on a trusted channel (localhost, sandbox-internal, or behind your own
+authenticated boundary).