@spunto/build 0.22.0 → 0.24.0

package/src/agent-stream/agent-stream.ts

@@ -1,10 +1,12 @@
 /**
  * Reading an agent session as it happens (RFC 0020, phase 1).
  *
- * A task's harness is launched with the prompt on stdin and nothing else agreed — that poverty is
- * what makes `taskAgentCommand` able to hold Claude Code, Codex or a shell script. Streaming needs
- * strictly more than that, so it is **opt-in per project** (`projects.taskAgentProtocol`) and the
- * extra knowledge lives here, in one adapter per dialect, and nowhere else.
+ * Since RFC 0048 § 9 a session started under an agent app speaks **our** contract (`agent-v1`, read
+ * by `../agent-contract`): the runner normalised its harness's output before it left the machine,
+ * and nothing here knows which harness it was. What remains in this file is everything around that
+ * reader — how to write to a session, how to sum what it consumed — and the **legacy dialects**:
+ * the harnesses' own shapes, normalised here, for the sessions that started on them (the CLI of a
+ * task delegated before agent apps, a runner's previous dialect) and for spunto-lite.
  *
  * Two rules the rest of the code depends on:
  *
@@ -19,10 +21,35 @@
  * ingestion loop lives in task-events.service.ts.
  */
 
+import {
+  clip,
+  readContractLine,
+  TASK_EVENT_TYPES,
+  type NormalizedEvent,
+  type TaskEventType,
+  type RunnerInput,
+  type SourcedEvent,
+} from "../agent-contract/vocabulary"
+import { adaptClaudeJson, cleanTitle, TITLE_REQUEST_PREFIX } from "../agent-runners/claude/adapter"
+import { adaptCodex } from "../agent-runners/codex/adapter"
 import { contextWindowOf } from "./model-window"
-import { claudeTurnLimit } from "./turn-limit"
 
-export const AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream", "jsonl", "claude-runner", "codex-runner"] as const
+export { cleanTitle }
+export { TASK_EVENT_TYPES } from "../agent-contract/vocabulary"
+export type { NormalizedEvent, RunnerInput, SourcedEvent, TaskEventType } from "../agent-contract/vocabulary"
+
+/**
+ * How a session is read.
+ *
+ *  - `agent-v1` — **the Spunto agent contract** (`../agent-contract`): what every agent app's runner
+ *    prints since the normalisation moved into the runner (RFC 0048 § 9). The one dialect a new
+ *    session speaks; read by one strict reader, with no adapter of anyone's.
+ *  - `claude-runner`, `codex-runner` — what those runners printed before: their harness's own
+ *    dialect, normalised here. Kept for the sessions that started on it, until they end.
+ *  - `claude-stream`, `claude-json`, `jsonl`, `none` — the CLI dialects of a task delegated before
+ *    agent apps (`LEGACY_CLI`), and what spunto-lite's `spunto.json` still names.
+ */
+export const AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream", "jsonl", "claude-runner", "codex-runner", "agent-v1"] as const
 export type AgentProtocol = (typeof AGENT_PROTOCOLS)[number]
 
 /**
@@ -35,21 +62,12 @@ export const PROJECT_AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream",
 /**
  * A runner of an agent app (RFC 0048, `../agent-runners`): our own process in the machine, driving a
  * harness through its official SDK. Its stdin speaks **our** contract (`RunnerInput`), whatever the
- * harness; its stdout is the harness's own dialect, normalised here like any other.
+ * harness — and so does its stdout, since `agent-v1`.
  */
 export function isRunner(protocol: AgentProtocol): boolean {
-  return protocol === "claude-runner" || protocol === "codex-runner"
+  return protocol === "agent-v1" || protocol === "claude-runner" || protocol === "codex-runner"
 }
 
-/**
- * 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.
- */
-export type RunnerInput =
-  | { type: "user"; text: string }
-  | { type: "interrupt"; id: string }
-  | { type: "title"; id: string; description: string }
-
 function runnerLine(input: RunnerInput): string {
   return `${JSON.stringify(input)}\n`
 }
@@ -59,57 +77,6 @@ function speaksClaude(protocol: AgentProtocol): boolean {
   return protocol === "claude-json" || protocol === "claude-stream" || protocol === "claude-runner"
 }
 
-/**
- * The normalized 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", // { harness, model?, cwd?, tools? }
-  "session.title",   // { title } — the name the harness gave the conversation
-  "message",         // { role, text }
-  "thinking",        // { text }
-  "tool.call",       // { callId, name, input }
-  "tool.result",     // { callId, isError, output }
-  "plan",            // { steps: [{ text, status }] }
-  // { scope: "call" | "session", model?, inputTokens?, outputTokens?, cacheReadTokens?,
-  //   cacheCreationTokens?, contextTokens?, costUsd?, turns?, durationMs? } — see `summarizeUsage`
-  "usage",
-  // { status, stopReason?, summary?, limit? } — `limit` ({ kind, status, message, resetsAt }) when
-  // the turn ended because the account hit a usage/rate limit or the API was overloaded, see
-  // `turn-limit.ts`
-  "session.ended",
-  // { tasks: [{ id, kind, description }] } — what the harness still runs in the background, whole
-  "session.background",
-  "raw",             // anything an adapter could not place
-] as const
-export type TaskEventType = (typeof TASK_EVENT_TYPES)[number]
-
-export type NormalizedEvent = {
-  type: TaskEventType
-  payload: Record<string, unknown>
-}
-
-/**
- * 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
- * instead of quietly lying about what the agent saw.
- */
-const MAX_TEXT = 8_000
-
-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 }
-}
-
-function safeStringify(value: unknown): string {
-  try {
-    return JSON.stringify(value) ?? ""
-  } catch {
-    return String(value)
-  }
-}
-
 /**
  * The command actually run, given the project's harness and its protocol.
  *
@@ -180,12 +147,13 @@ export function interruptLine(protocol: AgentProtocol, requestId: string): strin
  * `control_response` (an interrupt's, say) without keeping state between write and read.
  */
 export function sessionTitleRequestLine(protocol: AgentProtocol, requestId: string, description: string): string | null {
-  if (protocol !== "claude-stream" && protocol !== "claude-runner") return null
+  if (protocol !== "claude-stream" && protocol !== "claude-runner" && protocol !== "agent-v1") return null
   const text = description.trim()
   if (!text) return null
-  // The Claude runner asks the SDK (`generateSessionTitle`), and answers with the very
-  // `control_response` the CLI would have printed — so the reading side below is one path.
-  if (protocol === "claude-runner") return runnerLine({ type: "title", id: `${TITLE_REQUEST_PREFIX}${requestId}`, description: text })
+  // A runner is asked with the contract's own verb, and answers — if its harness can name a
+  // conversation at all — with a `session.title` line (`agent-v1`), or, on the old Claude runner,
+  // with the very `control_response` the CLI would have printed.
+  if (isRunner(protocol)) return runnerLine({ type: "title", id: `${TITLE_REQUEST_PREFIX}${requestId}`, description: text })
   return `${JSON.stringify({
     type: "control_request",
     request_id: `${TITLE_REQUEST_PREFIX}${requestId}`,
@@ -193,9 +161,6 @@ export function sessionTitleRequestLine(protocol: AgentProtocol, requestId: stri
   })}\n`
 }
 
-/** Marks the `control_request`s that ask for a title, and so the `control_response`s that answer. */
-const TITLE_REQUEST_PREFIX = "spunto-title-"
-
 /**
  * A shell that prints the line where the harness wrote **the name it gave the conversation**, or
  * null for a dialect that has no such thing.
@@ -249,9 +214,6 @@ export function readsTitleOutOfBand(protocol: AgentProtocol): boolean {
   return speaksClaude(protocol)
 }
 
-/** Longest name we keep. The column allows 200; a harness that writes an essay gets cut. */
-const MAX_TITLE = 200
-
 /**
  * The name, out of what the probe printed. Newest first, and the first line that is really a
  * title record wins — see the `tail -5` above.
@@ -275,13 +237,6 @@ export function parseSessionTitle(protocol: AgentProtocol, output: string): { ti
   return null
 }
 
-/** 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
-}
-
 /**
  * Parse one line of a harness's stream into zero or more normalized events.
  *
@@ -289,6 +244,7 @@ export function cleanTitle(value: unknown): string | null {
  * or an event type we deliberately have no use for.
  */
 export function parseStreamLine(protocol: AgentProtocol, line: string): NormalizedEvent[] {
+  if (protocol === "agent-v1") return readContractLine(line).map(({ source: _s, ...event }) => event)
   const trimmed = line.trim()
   if (!trimmed) return []
   let parsed: unknown
@@ -321,338 +277,10 @@ function adaptPassthrough(obj: Record<string, unknown>): NormalizedEvent[] {
   return [{ type: type as TaskEventType, payload }]
 }
 
-/**
- * `codex-runner` — the events of `@openai/codex-sdk`'s `runStreamed()` (`ThreadEvent`), printed one
- * per line by the Codex runner (RFC 0048). Written against the SDK's own types (0.164.0); the
- * runner adds nothing of its own beyond a `thread.started` for a resumed thread (the SDK only
- * announces new ones) and a `turn.failed` when a turn is interrupted. Not yet run against a real
- * OpenAI account: the shapes below were measured on a failing turn (401) only.
- *
- * Codex works per **turn**, not per session: `turn.completed` is a hand-back the way Claude's
- * `result` is, so it ends the turn here too. Its usage is the turn's sum, which is why it is filed
- * as a `call` (summed over the task) without a `contextTokens`: no single number of it is the
- * size of the prompt last sent.
- */
-function adaptCodex(obj: Record<string, unknown>): NormalizedEvent[] {
-  const type = obj.type
-  if (type === "thread.started") {
-    return [{ type: "session.started", payload: { harness: "codex", model: null, sessionId: typeof obj.thread_id === "string" ? obj.thread_id : null } }]
-  }
-  if (type === "turn.started") return []
-  if (type === "turn.completed") {
-    const u = (obj.usage ?? {}) as Record<string, unknown>
-    return [
-      {
-        type: "usage",
-        payload: {
-          scope: "call",
-          model: null,
-          inputTokens: num(u.input_tokens) ?? 0,
-          outputTokens: (num(u.output_tokens) ?? 0) + (num(u.reasoning_output_tokens) ?? 0),
-          cacheReadTokens: num(u.cached_input_tokens) ?? 0,
-          cacheCreationTokens: num(u.cache_write_input_tokens) ?? 0,
-        },
-      },
-      { type: "session.ended", payload: { status: "succeeded", stopReason: null, summary: "" } },
-    ]
-  }
-  if (type === "turn.failed") {
-    const error = (obj.error ?? {}) as Record<string, unknown>
-    return [{ type: "session.ended", payload: { status: "failed", stopReason: null, summary: clip(error.message).text } }]
-  }
-  // Not an end: measured, Codex emits `error` for every retry ("Reconnecting... 2/5 (401 …)") and
-  // only the `turn.failed` that follows the last one ends the turn. Kept visible, not fatal.
-  if (type === "error") return [{ type: "raw", payload: { json: obj } }]
-  if (type !== "item.started" && type !== "item.updated" && type !== "item.completed") {
-    return [{ type: "raw", payload: { json: obj } }]
-  }
-  const item = (obj.item ?? {}) as Record<string, unknown>
-  const callId = typeof item.id === "string" ? item.id : null
-  const started = type === "item.started"
-  const completed = type === "item.completed"
-  switch (item.type) {
-    case "agent_message": {
-      if (!completed) return []
-      const { text, truncated } = clip(item.text)
-      return text ? [{ type: "message", payload: { role: "assistant", text, truncated } }] : []
-    }
-    case "reasoning": {
-      if (!completed) return []
-      const { text, truncated } = clip(item.text)
-      return text ? [{ type: "thinking", payload: { text, truncated } }] : []
-    }
-    case "command_execution": {
-      if (started) {
-        const { text: input, truncated } = clip({ command: item.command })
-        return [{ type: "tool.call", payload: { callId, name: "Bash", input, truncated } }]
-      }
-      if (!completed) return []
-      const { text: output, truncated } = clip(item.aggregated_output)
-      const failed = item.status === "failed" || (typeof item.exit_code === "number" && item.exit_code !== 0)
-      return [{ type: "tool.result", payload: { callId, isError: failed, output, truncated } }]
-    }
-    case "file_change": {
-      // Reported once, applied: the call and its outcome arrive together.
-      if (!completed) return []
-      const changes = Array.isArray(item.changes) ? item.changes : []
-      const { text: input, truncated } = clip({ changes })
-      const output = changes
-        .filter((c): c is Record<string, unknown> => !!c && typeof c === "object")
-        .map((c) => `${c.kind} ${c.path}`)
-        .join("\n")
-      return [
-        { type: "tool.call", payload: { callId, name: "Edit", input, truncated } },
-        { type: "tool.result", payload: { callId, isError: item.status === "failed", output, truncated: false } },
-      ]
-    }
-    case "mcp_tool_call": {
-      const name = `${typeof item.server === "string" ? item.server : "mcp"}.${typeof item.tool === "string" ? item.tool : "tool"}`
-      if (started) {
-        const { text: input, truncated } = clip(item.arguments)
-        return [{ type: "tool.call", payload: { callId, name, input, truncated } }]
-      }
-      if (!completed) return []
-      const error = (item.error ?? null) as Record<string, unknown> | null
-      const { text: output, truncated } = clip(error ? error.message : (item.result as Record<string, unknown> | undefined)?.content ?? "")
-      return [{ type: "tool.result", payload: { callId, isError: !!error || item.status === "failed", output, truncated } }]
-    }
-    case "web_search": {
-      if (!started) return []
-      const { text: input, truncated } = clip({ query: item.query })
-      return [{ type: "tool.call", payload: { callId, name: "WebSearch", input, truncated } }]
-    }
-    case "todo_list": {
-      const steps = (Array.isArray(item.items) ? item.items : [])
-        .filter((t): t is Record<string, unknown> => !!t && typeof t === "object")
-        .map((t) => ({ text: clip(t.text).text, status: t.completed === true ? "completed" : "pending" }))
-        .filter((s) => s.text)
-      return steps.length > 0 ? [{ type: "plan", payload: { steps } }] : []
-    }
-  }
-  return [{ type: "raw", payload: { json: obj } }]
-}
-
-/**
- * `claude-json` — Claude Code's `--output-format stream-json --verbose`.
- *
- * Written against output measured in a real worker, not against a spec: the shapes below are
- * what the CLI emitted, and `task-events.service.test.ts` replays recorded samples so a change in
- * that output shows up as a failing test rather than as an empty timeline.
- */
-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 ingestion loop replaces it with the model's own answer when the task
-          // 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 events: NormalizedEvent[] = [
-      {
-        type: "usage",
-        payload: {
-          // The harness's own running total, **cumulative over the whole process** — with an
-          // interactive protocol 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,
-          ...limitField(obj),
-        },
-      },
-    ]
-    return events
-  }
-
-  // The answer to `sessionTitleRequestLine`. 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 (`draft.ts`).
-  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 limitField(obj: Record<string, unknown>): { limit?: ReturnType<typeof claudeTurnLimit> } {
-  const limit = claudeTurnLimit(obj)
-  return limit ? { limit } : {}
-}
-
 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,
-    },
-  }
-}
-
 /** What a session has consumed so far — the recap the cockpit puts beside the timeline. */
 export type SessionUsage = {
   /** The model that ran, as the harness named it. */
@@ -728,24 +356,6 @@ export function summarizeUsage(input: UsageInput): SessionUsage | null {
   }
 }
 
-/** 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
-}
-
-/** An event and the harness line it came from. One line can yield several. */
-export type SourcedEvent = NormalizedEvent & { source: string }
-
 /**
  * Parse whole lines, keeping each event attached to the line it was derived from.
  *
@@ -760,17 +370,17 @@ export function parseLines(protocol: AgentProtocol, lines: string[], budget: num
   const out: SourcedEvent[] = []
   for (const line of lines) {
     if (out.length >= budget) break
-    let events: NormalizedEvent[]
+    let events: SourcedEvent[]
     try {
-      events = parseStreamLine(protocol, line)
+      // The contract carries each event's source itself; every other dialect's source is its line.
+      events = protocol === "agent-v1" ? readContractLine(line) : parseStreamLine(protocol, line).map((e) => ({ ...e, source: line.trim() }))
     } catch (err) {
       console.warn(`[tasks] agent stream adapter threw: ${err}`)
       continue
     }
-    const source = line.trim()
     for (const event of events) {
       if (out.length >= budget) break
-      out.push({ ...event, source })
+      out.push(event)
     }
   }
   return out

package/src/agent-stream/draft.ts

@@ -29,9 +29,47 @@ function append(draft: AgentDraft | null, text: string): AgentDraft {
   return next.length > MAX_DRAFT ? { text: next.slice(0, MAX_DRAFT), truncated: true } : { text: next, truncated: false }
 }
 
-/** Claude's dialects print token deltas; Codex's prints the message so far on `item.updated`. */
+/** Claude's dialects print token deltas; Codex's prints the message so far on `item.updated`; the contract, `message.delta`. */
 function streamsPartials(protocol: AgentProtocol): boolean {
-  return protocol === "claude-runner" || protocol === "claude-stream" || protocol === "claude-json" || protocol === "codex-runner"
+  return (
+    protocol === "agent-v1" ||
+    protocol === "claude-runner" ||
+    protocol === "claude-stream" ||
+    protocol === "claude-json" ||
+    protocol === "codex-runner"
+  )
+}
+
+/** What closes a draft in the contract: the finished text, or anything that comes after it in the turn. */
+const CLOSES_DRAFT = new Set(["message", "thinking", "tool.call", "tool.result", "session.ended"])
+
+/**
+ * The contract (`agent-v1`): `message.delta` with `start` opens a fresh draft, without it grows the
+ * one in flight. The runner already chose what is a draft (a subagent's words are not), so this
+ * only folds — whichever harness it was.
+ */
+function foldContract(lines: string[], draft: AgentDraft | null): AgentDraft | null {
+  let current = draft
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith("{")) continue
+    // Cheap pre-filter, before parsing a line that may carry megabytes.
+    if (!trimmed.includes('"message') && !trimmed.includes('"thinking"') && !trimmed.includes('"tool.') && !trimmed.includes('"session.ended"')) continue
+    let obj: Record<string, unknown>
+    try {
+      const parsed = JSON.parse(trimmed)
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue
+      obj = parsed as Record<string, unknown>
+    } catch {
+      continue
+    }
+    if (obj.type === "message.delta" && typeof obj.text === "string") {
+      current = append(obj.start === true ? null : current, obj.text)
+    } else if (typeof obj.type === "string" && CLOSES_DRAFT.has(obj.type)) {
+      current = null
+    }
+  }
+  return current
 }
 
 /**
@@ -82,6 +120,7 @@ function foldCodex(lines: string[], draft: AgentDraft | null): AgentDraft | null
  */
 export function foldDraft(protocol: AgentProtocol, lines: string[], draft: AgentDraft | null): AgentDraft | null {
   if (!streamsPartials(protocol)) return null
+  if (protocol === "agent-v1") return foldContract(lines, draft)
   if (protocol === "codex-runner") return foldCodex(lines, draft)
   let current = draft
   for (const line of lines) {