@spunto/build 0.21.1 → 0.23.0

package/src/agent-contract/vocabulary.ts

@@ -0,0 +1,313 @@
+/**
+ * The Spunto agent contract (RFC 0048 § 4.2, § 9): what an agent app's runner prints, and the one
+ * reader the platform has for it.
+ *
+ * A runner speaks **our** vocabulary on stdout, one JSON object per line, whatever harness it
+ * drives — the normalisation from a harness's own dialect happens in the runner, in the machine,
+ * before the line ever leaves it. So the platform has a single reader, strict, and no adapter of
+ * anyone's: adding an agent is writing a runner, never changing the platform.
+ *
+ * Everything here is derived from one table (`FIELDS`): the validator the platform reads with, and
+ * the JSON Schema an app author writes against (`agentContractSchema`, published as
+ * `agent-contract.v1.schema.json`). They cannot drift, because there is only one of them.
+ *
+ * Two rules the platform depends on:
+ *
+ *  1. **Closed schemas.** A known type with a field we do not know, or a field of the wrong shape,
+ *     is not guessed at: the line is kept as `raw`, with the reason, and nothing silently lands in
+ *     the timeline half-read. An unknown type is `raw` too. Never an error, never dropped.
+ *  2. **`source` travels with the event.** A runner puts the harness's own message next to the
+ *     event it read it into (`"source": {…}`), so the projection stays replayable (RFC 0020) — the
+ *     platform stores *that* as the event's source, not our reading of it.
+ *
+ * Pure: no I/O, no clock.
+ */
+
+import { TURN_LIMIT_KINDS } from "../agent-stream/turn-limit"
+
+/** Bumped only for a change an existing runner would not survive. Additive changes keep it. */
+export const AGENT_CONTRACT_VERSION = 1
+
+/**
+ * The stored vocabulary. Deliberately short — it has to be translatable *from* several harnesses,
+ * so anything specific to one of them does not belong in it.
+ */
+export const TASK_EVENT_TYPES = [
+  "session.started",
+  "session.title",
+  "message",
+  "thinking",
+  "tool.call",
+  "tool.result",
+  "plan",
+  "usage",
+  "session.ended",
+  "session.background",
+  "raw",
+] as const
+export type TaskEventType = (typeof TASK_EVENT_TYPES)[number]
+
+/**
+ * Lines a runner may print that are **not events**: never stored, read on the way past. Only one —
+ * the text of a message still being written (`message.delta`), which folds into the transient draft
+ * the cockpit shows until the finished `message` lands (`../agent-stream/draft.ts`).
+ */
+export const TRANSIENT_TYPES = ["message.delta"] as const
+export type TransientType = (typeof TRANSIENT_TYPES)[number]
+
+export type NormalizedEvent = {
+  type: TaskEventType
+  payload: Record<string, unknown>
+}
+
+/** An event and the harness line it came from. One line can yield several. */
+export type SourcedEvent = NormalizedEvent & { source: string }
+
+/**
+ * One line of a runner's stdin. The whole input side of the contract — three verbs, the same for
+ * every harness, so the platform never writes a harness's own shape into a runner. Closing stdin
+ * ends the session once its turn is over.
+ */
+export type RunnerInput =
+  | { type: "user"; text: string }
+  | { type: "interrupt"; id: string }
+  | { type: "title"; id: string; description: string }
+
+// ── The table ─────────────────────────────────────────────────────────────────
+
+type Field = { check: (v: unknown) => boolean; schema: Record<string, unknown>; required?: boolean }
+
+const str = (): Field => ({ check: (v) => typeof v === "string", schema: { type: "string" } })
+const num = (): Field => ({ check: (v) => typeof v === "number" && Number.isFinite(v), schema: { type: "number" } })
+const bool = (): Field => ({ check: (v) => typeof v === "boolean", schema: { type: "boolean" } })
+const any = (): Field => ({ check: () => true, schema: {} })
+const oneOf = (values: readonly string[]): Field => ({
+  check: (v) => typeof v === "string" && values.includes(v),
+  schema: { type: "string", enum: [...values] },
+})
+const nullable = (f: Field): Field => ({
+  check: (v) => v === null || f.check(v),
+  schema: { anyOf: [f.schema, { type: "null" }] },
+})
+const array = (item: Field): Field => ({
+  check: (v) => Array.isArray(v) && v.every(item.check),
+  schema: { type: "array", items: item.schema },
+})
+const req = (f: Field): Field => ({ ...f, required: true })
+const object = (fields: Record<string, Field>): Field => ({
+  check: (v) => !!v && typeof v === "object" && !Array.isArray(v) && fieldsProblem(v as Record<string, unknown>, fields) === null,
+  schema: objectSchema(fields),
+})
+
+function objectSchema(fields: Record<string, Field>, extra: Record<string, unknown> = {}): Record<string, unknown> {
+  const required = Object.entries(fields).filter(([, f]) => f.required).map(([k]) => k)
+  return {
+    type: "object",
+    properties: { ...extra, ...Object.fromEntries(Object.entries(fields).map(([k, f]) => [k, f.schema])) },
+    ...(required.length || extra.type ? { required: [...(extra.type ? ["type"] : []), ...required] } : {}),
+    additionalProperties: false,
+  }
+}
+
+/** Why `obj` does not fit `fields`, or null. Closed: an unknown key is a problem too. */
+function fieldsProblem(obj: Record<string, unknown>, fields: Record<string, Field>): string | null {
+  for (const [key, field] of Object.entries(fields)) {
+    if (!(key in obj) || obj[key] === undefined) {
+      if (field.required) return `missing "${key}"`
+      continue
+    }
+    if (!field.check(obj[key])) return `"${key}" is not ${describe(field.schema)}`
+  }
+  for (const key of Object.keys(obj)) if (!(key in fields)) return `unknown field "${key}"`
+  return null
+}
+
+function describe(schema: Record<string, unknown>): string {
+  if (Array.isArray(schema.enum)) return `one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`
+  if (Array.isArray(schema.anyOf)) return schema.anyOf.map((s) => describe(s as Record<string, unknown>)).join(" or ")
+  if (schema.type === "array") return "an array of the expected shape"
+  if (schema.type === "object") return "an object of the expected shape"
+  return typeof schema.type === "string" ? `a ${schema.type}` : "valid"
+}
+
+/** `limit` — the turn ended because the account ran out, not the work (`../agent-stream/turn-limit.ts`). */
+const LIMIT = object({
+  kind: req(oneOf(TURN_LIMIT_KINDS)),
+  status: nullable(num()),
+  message: req(str()),
+  resetsAt: nullable(str()),
+})
+
+const COUNT = nullable(num())
+
+/**
+ * Every line type, and its fields. `type` and `source` are on every line and not repeated here.
+ * A field absent from a line is "unknown", which is not the same as `null` only for the reader of
+ * the stored payload — both are allowed wherever the field is optional.
+ */
+const FIELDS: Record<TaskEventType | TransientType, Record<string, Field>> = {
+  // The session opened (or was resumed). `sessionId` is what `--resume` takes back; `contextWindow`
+  // the size of the model's window, when the runner could tell — the platform no longer guesses it.
+  "session.started": {
+    harness: req(str()),
+    model: nullable(str()),
+    sessionId: nullable(str()),
+    cwd: nullable(str()),
+    tools: array(str()),
+    contextWindow: COUNT,
+  },
+  // The name the harness gave the conversation — in answer to the `title` verb, or on its own.
+  "session.title": { title: req(str()) },
+  message: { role: req(oneOf(["assistant", "user"])), text: req(str()), truncated: bool(), limit: nullable(LIMIT) },
+  thinking: { text: req(str()), truncated: bool() },
+  // `input` is text: the call's arguments as the harness wrote them, JSON or not.
+  "tool.call": { callId: nullable(str()), name: req(str()), input: req(str()), truncated: bool() },
+  "tool.result": { callId: nullable(str()), isError: req(bool()), output: req(str()), truncated: bool() },
+  plan: { steps: req(array(object({ text: req(str()), status: req(str()) }))) },
+  // `call`: one model call, summed over the task; its `contextTokens` is how full the window is
+  // now. `session`: the harness's own running total, restated — the latest one wins.
+  usage: {
+    scope: req(oneOf(["call", "session"])),
+    model: nullable(str()),
+    inputTokens: COUNT,
+    outputTokens: COUNT,
+    cacheReadTokens: COUNT,
+    cacheCreationTokens: COUNT,
+    contextTokens: COUNT,
+    contextWindow: COUNT,
+    costUsd: COUNT,
+    turns: COUNT,
+    durationMs: COUNT,
+  },
+  // The turn is over and the harness is listening again (or exiting). `limit` when the account,
+  // not the work, ended it — the platform then waits for `resetsAt` instead of calling it review.
+  "session.ended": {
+    status: req(oneOf(["succeeded", "failed"])),
+    stopReason: nullable(str()),
+    summary: str(),
+    limit: nullable(LIMIT),
+  },
+  // What the harness still runs in the background, restated whole — a turn that leaves something
+  // running has not handed back.
+  "session.background": {
+    tasks: req(array(object({ id: nullable(str()), kind: nullable(str()), description: nullable(str()) }))),
+  },
+  raw: { json: any(), text: str() },
+  // Not stored. `start` opens a fresh draft (one draft is one text block), else `text` is appended.
+  "message.delta": { text: req(str()), start: bool() },
+}
+
+/** The JSON Schema of one output line, every type. What an app author validates against. */
+export function agentContractSchema(): Record<string, unknown> {
+  const line = (type: string, fields: Record<string, Field>) =>
+    objectSchema(fields, {
+      type: { const: type },
+      source: { description: "The harness's own message this event was read from, verbatim — kept so the projection can be replayed." },
+    })
+  const input: Record<string, Field>[] = [
+    { type: req(oneOf(["user"])), text: req(str()) },
+    { type: req(oneOf(["interrupt"])), id: req(str()) },
+    { type: req(oneOf(["title"])), id: req(str()), description: req(str()) },
+  ]
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: `https://spunto.net/schemas/agent-contract.v${AGENT_CONTRACT_VERSION}.json`,
+    title: `Spunto agent contract, v${AGENT_CONTRACT_VERSION}`,
+    description:
+      "What an agent app's runner prints on stdout (one `output` object per line) and reads on stdin (one `input` object per line). See docs/agent-contract.md.",
+    $defs: {
+      output: { oneOf: Object.entries(FIELDS).map(([type, fields]) => line(type, fields)) },
+      input: { oneOf: input.map((fields) => objectSchema(fields)) },
+    },
+    $ref: "#/$defs/output",
+  }
+}
+
+// ── The reader ────────────────────────────────────────────────────────────────
+
+/**
+ * Per-field ceiling on stored text. A single `tool.result` can be a 2 MB file read; the timeline
+ * needs enough of it to be readable, not all of it. `truncated` is set so the UI can say so.
+ */
+export const MAX_TEXT = 8_000
+
+export function clip(value: unknown): { text: string; truncated: boolean } {
+  const text =
+    typeof value === "string" ? value : value === undefined || value === null ? "" : safeStringify(value)
+  return text.length > MAX_TEXT ? { text: text.slice(0, MAX_TEXT), truncated: true } : { text, truncated: false }
+}
+
+export function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? ""
+  } catch {
+    return String(value)
+  }
+}
+
+/** Fields a runner may write at any length; the reader clips them as the adapters always did. */
+const CLIPPED: Partial<Record<TaskEventType, string>> = {
+  message: "text",
+  thinking: "text",
+  "tool.call": "input",
+  "tool.result": "output",
+}
+
+/** Why this line is not a valid output line of the contract, or null. */
+export function contractLineProblem(obj: Record<string, unknown>): string | null {
+  const type = obj.type
+  if (typeof type !== "string") return `missing "type"`
+  const fields = (FIELDS as Record<string, Record<string, Field> | undefined>)[type]
+  if (!fields) return `unknown type "${type}"`
+  const { type: _t, source: _s, ...payload } = obj
+  return fieldsProblem(payload, fields)
+}
+
+/** Is this a line that is read on the way past and never stored (`message.delta`)? */
+export function isTransient(obj: Record<string, unknown>): boolean {
+  return (TRANSIENT_TYPES as readonly unknown[]).includes(obj.type)
+}
+
+/**
+ * Read one parsed line of the contract into the event it states, with its source.
+ *
+ * `line` is what was read, kept as the source when the runner gave none — a home-made agent that
+ * has no harness message of its own to point at is still auditable. Transient lines read as
+ * nothing here; see `foldDraft`.
+ */
+export function readContractObject(obj: Record<string, unknown>, line: string): SourcedEvent[] {
+  if (isTransient(obj)) return []
+  const source = obj.source === undefined ? line : typeof obj.source === "string" ? obj.source : safeStringify(obj.source)
+  const problem = contractLineProblem(obj)
+  if (problem) return [{ type: "raw", payload: { json: withoutSource(obj), invalid: problem }, source }]
+  const { type, source: _s, ...payload } = obj
+  const field = CLIPPED[type as TaskEventType]
+  if (field) {
+    const { text, truncated } = clip(payload[field])
+    payload[field] = text
+    if (truncated) payload.truncated = true
+  }
+  if (type === "session.ended" && typeof payload.summary === "string") payload.summary = clip(payload.summary).text
+  return [{ type: type as TaskEventType, payload, source }]
+}
+
+function withoutSource(obj: Record<string, unknown>): Record<string, unknown> {
+  const { source: _s, ...rest } = obj
+  return rest
+}
+
+/** Read one line of a runner's stdout. A line that is not a JSON object is kept as `raw` text. */
+export function readContractLine(line: string): SourcedEvent[] {
+  const trimmed = line.trim()
+  if (!trimmed) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(trimmed)
+  } catch {
+    return [{ type: "raw", payload: { text: clip(trimmed).text }, source: trimmed }]
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return [{ type: "raw", payload: { json: parsed }, source: trimmed }]
+  }
+  return readContractObject(parsed as Record<string, unknown>, trimmed)
+}

package/src/agent-runners/catalogs.ts

@@ -47,6 +47,13 @@ export type AgentCatalog = {
 /** The variable a task's chosen parameters reach the runner in, as one JSON object. */
 export const OPTIONS_ENV = "SPUNTO_AGENT_OPTIONS"
 
+/**
+ * `"1"` when the session should stream the tokens of a message as they are written (partial
+ * messages, folded into the draft by `foldDraft`). Set by the platform behind the org flag
+ * `token-streaming`; absent, a runner prints finished messages only — the system before it.
+ */
+export const STREAM_ENV = "SPUNTO_AGENT_STREAM"
+
 /**
  * The variable the org's MCP servers reach the runner in (RFC 0049): a JSON array of
  * `{ name, path }`, `path` being the platform's gateway for that server, resolved by the runner

package/src/agent-runners/claude/adapter.ts

@@ -0,0 +1,330 @@
+/**
+ * Claude's dialect, read into our vocabulary — the SDK's messages, which are exactly the CLI's
+ * `--output-format stream-json --verbose` shapes.
+ *
+ * Lives with the Claude runner (RFC 0048 § 9): the runner bundles it and prints the contract
+ * (`claudeContractLines`), so the platform reads no Claude line of a session started since. The
+ * platform's legacy reader (`../../agent-stream`) still imports `adaptClaudeJson` for the
+ * conversations that began on the CLI or on the runner's old dialect, until they end.
+ *
+ * Written against output measured in a real worker, not against a spec: the shapes below are what
+ * the CLI emitted, and the tests replay recorded samples so a change in that output shows up as a
+ * failing test rather than as an empty timeline.
+ */
+
+import { clip, type NormalizedEvent } from "../../agent-contract/vocabulary"
+import { contextWindowOf } from "../../agent-stream/model-window"
+import { claudeTurnLimit, resetFromText, type TurnLimit } from "../../agent-stream/turn-limit"
+
+/** Marks the `control_request`s that ask the CLI for a title, and so the `control_response`s that answer. */
+export const TITLE_REQUEST_PREFIX = "spunto-title-"
+
+/** One line, no runs of whitespace, bounded — a title goes in a list row and in a page header. */
+export function cleanTitle(value: unknown): string | null {
+  if (typeof value !== "string") return null
+  const title = value.replace(/\s+/g, " ").trim().slice(0, MAX_TITLE).trim()
+  return title || null
+}
+
+/** Longest name we keep. The column allows 200; a harness that writes an essay gets cut. */
+const MAX_TITLE = 200
+
+export function adaptClaudeJson(obj: Record<string, unknown>): NormalizedEvent[] {
+  const type = obj.type
+
+  if (type === "system" && obj.subtype === "init") {
+    const model = typeof obj.model === "string" ? obj.model : null
+    return [
+      {
+        type: "session.started",
+        payload: {
+          harness: "claude-code",
+          model,
+          // Read here and nowhere else: this is the only line that spells the model the way the
+          // *session* was opened (`claude-opus-5[1m]`), suffix included — the assistant messages
+          // that follow carry the plain API id. From the catalogue only, so this stays a pure
+          // function; the runner replaces it with the model's own answer when it has a key to ask
+          // with (`resolveContextWindow`).
+          contextWindow: contextWindowOf(model),
+          cwd: typeof obj.cwd === "string" ? obj.cwd : null,
+          sessionId: typeof obj.session_id === "string" ? obj.session_id : null,
+          tools: Array.isArray(obj.tools) ? obj.tools.filter((t) => typeof t === "string") : [],
+        },
+      },
+    ]
+  }
+
+  // The set of background tasks (a `run_in_background` shell, a backgrounded subagent) still
+  // alive, restated whole on every change. Why it has to be read: a `result` ends the *turn*, not
+  // the work — measured, a turn that leaves a background task running emits its `result`, and
+  // when that task finishes the harness wakes itself up for another turn and another `result`,
+  // nobody having said anything. So a `result` is a hand-back only if nothing was left running
+  // behind it, and this line is the only place that says so.
+  if (type === "system" && obj.subtype === "background_tasks_changed") {
+    const tasks = (Array.isArray(obj.tasks) ? obj.tasks : [])
+      .filter((t): t is Record<string, unknown> => !!t && typeof t === "object")
+      .map((t) => ({
+        id: typeof t.task_id === "string" ? t.task_id : null,
+        kind: typeof t.task_type === "string" ? t.task_type : null,
+        description: typeof t.description === "string" ? t.description : null,
+      }))
+    return [{ type: "session.background", payload: { tasks } }]
+  }
+
+  if (type === "assistant" || type === "user") {
+    const message = obj.message as Record<string, unknown> | undefined
+    const content = Array.isArray(message?.content) ? message!.content : []
+    const role = type === "assistant" ? "assistant" : "user"
+    const events: NormalizedEvent[] = []
+    for (const rawBlock of content) {
+      if (!rawBlock || typeof rawBlock !== "object") continue
+      const block = rawBlock as Record<string, unknown>
+      switch (block.type) {
+        case "text": {
+          const { text, truncated } = clip(block.text)
+          if (text) events.push({ type: "message", payload: { role, text, truncated } })
+          break
+        }
+        case "thinking": {
+          const { text, truncated } = clip(block.thinking)
+          if (text) events.push({ type: "thinking", payload: { text, truncated } })
+          break
+        }
+        case "tool_use": {
+          const name = typeof block.name === "string" ? block.name : "tool"
+          const { text: input, truncated } = clip(block.input)
+          events.push({
+            type: "tool.call",
+            payload: { callId: typeof block.id === "string" ? block.id : null, name, input, truncated },
+          })
+          // A todo list is a plan, and a plan is the single most useful thing to show while a
+          // session runs. Emitted *alongside* the tool call rather than instead of it: the call
+          // is what happened, the plan is what it means.
+          const plan = todoPlan(block.input)
+          if (plan) events.push(plan)
+          break
+        }
+        case "tool_result": {
+          const { text: output, truncated } = clip(
+            typeof block.content === "string" ? block.content : block.content ?? "",
+          )
+          events.push({
+            type: "tool.result",
+            payload: {
+              callId: typeof block.tool_use_id === "string" ? block.tool_use_id : null,
+              isError: block.is_error === true,
+              output,
+              truncated,
+            },
+          })
+          break
+        }
+      }
+    }
+    // The synthetic message Claude Code writes when the API refused the call carries the one
+    // structured reset time of a usage limit; the `result` that follows does not. Kept on the
+    // message so ingestion can carry it over to the turn's end (`stampLimitReset`).
+    if (type === "assistant") {
+      const limit = claudeTurnLimit(obj)
+      if (limit) for (const e of events) if (e.type === "message") e.payload.limit = limit
+    }
+    // What the call that produced this message cost, and how full the context was when it ran.
+    // Only assistant messages carry it — a `user` line is tool results being handed back.
+    if (type === "assistant") {
+      const measured = callUsage(message)
+      if (measured) events.push(measured)
+    }
+    return events
+  }
+
+  if (type === "result") {
+    const usage = (obj.usage ?? {}) as Record<string, unknown>
+    const limit = claudeTurnLimit(obj)
+    return [
+      {
+        type: "usage",
+        payload: {
+          // The harness's own running total, **cumulative over the whole process** — with an
+          // interactive session a `result` lands at the end of every turn and each one restates
+          // the session so far. Summing them would bill the first turn once per turn that
+          // followed; the latest one is the answer. (Claude Code's own SDK reader does the same:
+          // it overwrites `total_cost_usd`/`num_turns` on each result rather than adding.)
+          scope: "session",
+          inputTokens: num(usage.input_tokens),
+          outputTokens: num(usage.output_tokens),
+          cacheReadTokens: num(usage.cache_read_input_tokens),
+          cacheCreationTokens: num(usage.cache_creation_input_tokens),
+          costUsd: num(obj.total_cost_usd),
+          turns: num(obj.num_turns),
+          durationMs: num(obj.duration_ms),
+        },
+      },
+      {
+        type: "session.ended",
+        payload: {
+          // `is_error` too: a turn the API refused (a usage limit, measured) still says
+          // `subtype: "success"` — it is the *harness* that ended cleanly, not the turn.
+          status: obj.subtype === "success" && obj.is_error !== true ? "succeeded" : "failed",
+          stopReason: typeof obj.stop_reason === "string" ? obj.stop_reason : null,
+          summary: clip(obj.result).text,
+          ...(limit ? { limit } : {}),
+        },
+      },
+    ]
+  }
+
+  // The CLI's answer to a `generate_session_title` request. Only ours, recognised by request id:
+  // a `control_response` is also how an interrupt is acknowledged, and that one is no name.
+  if (type === "control_response") {
+    const response = (obj.response ?? {}) as Record<string, unknown>
+    const inner = (response.response ?? {}) as Record<string, unknown>
+    const requestId = typeof response.request_id === "string" ? response.request_id : ""
+    const title = response.subtype === "success" && requestId.startsWith(TITLE_REQUEST_PREFIX) ? cleanTitle(inner.title) : null
+    if (title) return [{ type: "session.title", payload: { title } }]
+  }
+
+  // Tokens of a message still being written (`includePartialMessages`). Not events: the finished
+  // `assistant` line repeats them whole, and one row per token would bury the session. They fold
+  // into the transient draft instead (`claudeDelta` below, `draft.ts` for the old dialects).
+  if (type === "stream_event") return []
+
+  // Known-but-uninteresting (`rate_limit_event`, `system/thinking_tokens`) and anything the CLI
+  // grows next land here rather than being dropped: an unknown event is information about the
+  // harness, and the UI keeps it behind a toggle.
+  return [{ type: "raw", payload: { json: obj } }]
+}
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+/**
+ * What **one model call** consumed, read off an assistant message.
+ *
+ * Two different questions are answered by these numbers, and only the first is obvious:
+ *
+ *  - added up over the session, they are what it has spent in tokens — and unlike the `result`
+ *    line, they exist *during* a turn, which is when someone is watching;
+ *  - the latest one alone is the **context**: `input + cache_read + cache_creation` is the prompt
+ *    the harness just sent, so it is how full the window is right now. Same formula Claude Code
+ *    uses for its own context meter.
+ *
+ * Skipped when every counter is zero: an API error makes the CLI emit a synthetic assistant
+ * message with an all-zero usage, and drawing a context that just fell to zero would be a lie
+ * about the session rather than a fact about the error.
+ */
+function callUsage(message: Record<string, unknown> | undefined): NormalizedEvent | null {
+  const usage = message?.usage
+  if (!usage || typeof usage !== "object") return null
+  const u = usage as Record<string, unknown>
+  const inputTokens = num(u.input_tokens) ?? 0
+  const outputTokens = num(u.output_tokens) ?? 0
+  const cacheReadTokens = num(u.cache_read_input_tokens) ?? 0
+  const cacheCreationTokens = num(u.cache_creation_input_tokens) ?? 0
+  if (inputTokens + outputTokens + cacheReadTokens + cacheCreationTokens === 0) return null
+  // `<synthetic>` is what the CLI puts there when no model ran at all.
+  const model = typeof message?.model === "string" && !message.model.startsWith("<") ? message.model : null
+  return {
+    type: "usage",
+    payload: {
+      scope: "call",
+      model,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheCreationTokens,
+      contextTokens: inputTokens + cacheReadTokens + cacheCreationTokens,
+    },
+  }
+}
+
+/** Claude Code's TodoWrite input, as a `plan` — `{ todos: [{ content, status }] }`. */
+function todoPlan(input: unknown): NormalizedEvent | null {
+  if (!input || typeof input !== "object") return null
+  const todos = (input as Record<string, unknown>).todos
+  if (!Array.isArray(todos) || todos.length === 0) return null
+  const steps = todos
+    .filter((t): t is Record<string, unknown> => !!t && typeof t === "object")
+    .map((t) => ({
+      text: clip(t.content ?? t.activeForm ?? "").text,
+      status: typeof t.status === "string" ? t.status : "pending",
+    }))
+    .filter((s) => s.text)
+  return steps.length > 0 ? { type: "plan", payload: { steps } } : null
+}
+
+// ── The contract, as the runner prints it ────────────────────────────────────
+
+/**
+ * A partial message (`stream_event`, `includePartialMessages`) as the contract's transient
+ * `message.delta`: a text block starting opens a fresh draft, a `text_delta` grows it. A subagent's
+ * partials (`parent_tool_use_id` set) are skipped — what it writes is not what the session says to
+ * the reader, and interleaving it would garble the draft of the main thread.
+ */
+export function claudeDelta(obj: Record<string, unknown>): Record<string, unknown>[] {
+  if (obj.type !== "stream_event" || obj.parent_tool_use_id) return []
+  const event = (obj.event ?? {}) as Record<string, unknown>
+  if (event.type === "content_block_start") {
+    const block = (event.content_block ?? {}) as Record<string, unknown>
+    if (block.type === "text") return [{ type: "message.delta", start: true, text: typeof block.text === "string" ? block.text : "" }]
+  } else if (event.type === "content_block_delta") {
+    const delta = (event.delta ?? {}) as Record<string, unknown>
+    if (delta.type === "text_delta" && typeof delta.text === "string" && delta.text) return [{ type: "message.delta", text: delta.text }]
+  }
+  return []
+}
+
+/** How deep `withoutFileBytes` looks. A content block sits two or three levels down; this is a loop guard. */
+const MAX_DEPTH = 8
+
+/**
+ * The message with every base64 file block reduced to what it is (`{type, media_type}`).
+ *
+ * What the *events* are read from, not what is printed as `source`: a screenshot a tool hands back
+ * is megabytes of base64 on one line, and read as text it would fill a `tool.result` with 8 KB of
+ * noise. The bytes stay whole in `source`, where the platform takes them out and stores them as a
+ * file of the task (RFC 0022) — so the event only needs to say that a file was there.
+ */
+export function withoutFileBytes(value: unknown, depth = 0): unknown {
+  if (depth > MAX_DEPTH || !value || typeof value !== "object") return value
+  if (Array.isArray(value)) return value.map((v) => withoutFileBytes(v, depth + 1))
+  const obj = value as Record<string, unknown>
+  const src = obj.source as Record<string, unknown> | undefined
+  if ((obj.type === "image" || obj.type === "document") && src && typeof src === "object" && src.type === "base64") {
+    const { source: _s, ...rest } = obj
+    return { ...rest, media_type: src.media_type }
+  }
+  return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, withoutFileBytes(v, depth + 1)]))
+}
+
+/**
+ * The Claude runner's reading of a session: SDK messages in, lines of the contract out — each event
+ * a message reads into, with the message itself as `source`. Every line of one message carries the
+ * same `source`, so the platform can tell they belong together (and stores a file they carry once).
+ *
+ * Stateful for one reason: **when a limit lifts**. Claude Code puts `resetsAt` on the synthetic
+ * assistant message it writes in place of the refused answer, one line *before* the `result` that
+ * ends the turn — which only says it in prose (« resets 9pm (UTC) »), measured on 2026-10-17. The
+ * contract says it where the platform waits for it, on `session.ended`: carried over from that
+ * message, else read from the prose against the clock (`now`, a parameter for the tests).
+ */
+export function claudeTranslator(now: () => Date = () => new Date()): (message: Record<string, unknown>) => Record<string, unknown>[] {
+  let carried: string | null = null
+  return (message) => {
+    if (message.type === "stream_event") return claudeDelta(message)
+    // The runner answers the `title` verb itself; a control response is never a title here.
+    if (message.type === "control_response") return []
+    const events = adaptClaudeJson(withoutFileBytes(message) as Record<string, unknown>)
+    for (const e of events) {
+      const limit = e.payload.limit as TurnLimit | undefined
+      if (e.type === "message" && limit?.resetsAt) carried = limit.resetsAt
+      if (e.type !== "session.ended") continue
+      if (limit && !limit.resetsAt) {
+        const resetsAt = carried ?? resetFromText(limit.message, now())
+        if (resetsAt) e.payload.limit = { ...limit, resetsAt }
+      }
+      carried = null
+    }
+    return events.map((e) => ({ type: e.type, ...e.payload, source: message }))
+  }
+}