@spunto/build 0.3.1 → 0.4.1

package/README.md

@@ -102,6 +102,52 @@ fields it has no feature for** — shared volumes are a Lite concept, the task s
 both optional. Dropping a field the target cannot honour is the correct outcome; refusing the file
 is not.
 
+### `@spunto/build/script` — turning a project spec into the shell a worker runs
+
+Four generators, one recipe: `buildImageScript` bakes the project image, `buildSetupScript` is the
+first boot, `buildStartScript` is every boot, `buildWorkerScript` assembles the container CMD.
+
+```ts
+import { buildImageScript, IMAGE_RECIPE_VERSION } from "@spunto/build/script"
+
+const { script, steps, hasDinD } = buildImageScript({ features, vscodeExtensions })
+```
+
+No filesystem, no clock: the one install script the platform ships itself is embedded as a string
+(`local-features.ts`), and every path a generated script writes to comes from `./naming` rather
+than a literal.
+
+`buildContainerScript` and `buildSetupPlan` are shaped by one product's model — an agent that
+orchestrates setup phase by phase instead of a container running one long CMD. They live here
+because they share every helper in the file; splitting them out would fork the helpers, which is
+the duplication this package exists to remove.
+
+### `@spunto/build/catalogs` — what a project picker offers
+
+`AVAILABLE_IMAGES`, `AVAILABLE_FEATURES`, `SUGGESTED_EXTENSIONS`. Data, but shared data: the two
+hand-maintained copies had already drifted, one of them advertising Oh My Zsh in a feature the
+image recipe explicitly disables.
+
+Project *templates* are deliberately absent — one product's clone a starter repository and carry
+onboarding-gallery presentation, the other's only configure an environment. They answer different
+questions.
+
+### `@spunto/build/types` — the shapes both schemas point at
+
+`ProjectFeature`, `Repository`, `SetupStatus`. Declared here so each product's ORM can point its
+JSON columns at them with `$type<…>()`, instead of a generator having to import a database schema.
+`SetupStatus` is what a shell script writes into a container and a control plane reads back minutes
+later: changing it is a migration, not an edit.
+
+### `@spunto/build/agent-stream` — reading an agent session as it happens
+
+One adapter per harness dialect, one vocabulary out. A CLI's JSON output is an output format, not
+an API; adapters normalise into a small set of event types so stored history doesn't date the first
+time a vendor reshuffles a field.
+
+Here for the reason that inverts the rest of the package: **nothing has forked this yet.** Putting
+it in the shared package now costs nothing and means the second product never writes its own.
+
 ## The rule
 
 A module belongs in this package only if it imports **no** ORM schema, **no** HTTP framework, **no**
@@ -117,10 +163,11 @@ installed on its behalf. Import `./spec` without zod and resolution fails loudly
 right trade for not taxing every other entry point.
 
 Concretely: **no platform I/O**. No database, no Docker socket, no WebSocket. This package produces
-strings and parses strings; its only network call is outbound HTTP to a public extension registry,
-with no platform credential attached. Configuration arrives as function parameters — never read from
-the environment — so that one control plane can scope a setting per organization and another per
-process without either shape leaking in here.
+strings and parses strings. Its only network calls are outbound HTTP on the caller's behalf — a
+public extension registry, and a model vendor's catalogue endpoint when you hand
+`resolveContextWindow` a credential — and it holds no credential of its own. Configuration arrives
+as function parameters, never read from the environment, so that one control plane can scope a
+setting per organization and another per process without either shape leaking in here.
 
 That rule is what makes the package testable, safe to import from a node agent as well as from an
 API, and the reason it can't simply be folded into the design system: a script generator needs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Spunto's shared Build engine \u2014 the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",
@@ -31,22 +31,39 @@
       "types": "./src/steps/index.ts",
       "import": "./src/steps/index.ts"
     },
-    "./extensions": {
-      "types": "./src/extensions/index.ts",
-      "import": "./src/extensions/index.ts"
-    },
     "./naming": {
       "types": "./src/naming/index.ts",
       "import": "./src/naming/index.ts"
     },
+    "./types": {
+      "types": "./src/types/index.ts",
+      "import": "./src/types/index.ts"
+    },
+    "./catalogs": {
+      "types": "./src/catalogs/index.ts",
+      "import": "./src/catalogs/index.ts"
+    },
+    "./extensions": {
+      "types": "./src/extensions/index.ts",
+      "import": "./src/extensions/index.ts"
+    },
     "./spec": {
       "types": "./src/spec/index.ts",
       "import": "./src/spec/index.ts"
+    },
+    "./script": {
+      "types": "./src/script/index.ts",
+      "import": "./src/script/index.ts"
+    },
+    "./agent-stream": {
+      "types": "./src/agent-stream/index.ts",
+      "import": "./src/agent-stream/index.ts"
     }
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
     "README.md"
   ],
   "scripts": {

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

@@ -0,0 +1,561 @@
+/**
+ * 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.
+ *
+ * Two rules the rest of the code depends on:
+ *
+ *  1. **Our vocabulary is the stored one.** A harness's JSON shape is an output format, not an
+ *     API; storing it would date the history. Adapters translate into the small set below, and
+ *     anything unmapped becomes `raw` rather than being dropped — same escape hatch as
+ *     `tasks.meta`, which has already earned its keep twice.
+ *  2. **A malformed line is never fatal.** This parses the output of a third-party CLI on a read
+ *     path. Garbage in a line costs that line, not the task.
+ *
+ * Pure functions only: no database, no worker, no clock beyond what a caller passes in. The
+ * ingestion loop lives in task-events.service.ts.
+ */
+
+import { contextWindowOf } from "./model-window"
+
+export const AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream", "jsonl"] as const
+export type AgentProtocol = (typeof AGENT_PROTOCOLS)[number]
+
+/**
+ * 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",
+  "session.ended",   // { status, stopReason?, summary? }
+  "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.
+ *
+ * The platform appends the flags rather than asking the project to, because getting them wrong is
+ * silent: a missing `--verbose` makes Claude Code refuse `stream-json` outright, and a missing
+ * `--output-format` produces prose that parses into nothing at all.
+ *
+ * Left alone when the command already names an output format — a project whose harness is a
+ * pipeline, or who wants different flags, keeps full control by saying so.
+ */
+export function applyProtocol(command: string, protocol: AgentProtocol): string {
+  if (protocol !== "claude-json" && protocol !== "claude-stream") return command
+  if (/--output-format/.test(command)) return command
+  const flags = ["--output-format stream-json --verbose"]
+  // Interactive mode. `--input-format stream-json` is what keeps the harness alive between
+  // turns — it reads instructions as a stream instead of exiting after one prompt — which is the
+  // precondition for both answering it mid-flight and interrupting it. Measured in a worker
+  // before it was built: two turns, one session id, and an interrupt the process survives.
+  if (protocol === "claude-stream") flags.push("--input-format stream-json")
+  return `${command} ${flags.join(" ")}`
+}
+
+/** Does this protocol keep the harness alive, listening on stdin, between turns? */
+export function isInteractive(protocol: AgentProtocol): boolean {
+  return protocol === "claude-stream"
+}
+
+/**
+ * One turn of the conversation, as the harness expects it on stdin.
+ *
+ * Newline-terminated and emitted as a single write: under PIPE_BUF that is atomic, which is what
+ * stops two messages from interleaving into one unparseable line.
+ */
+export function userTurnLine(protocol: AgentProtocol, text: string): string {
+  if (protocol !== "claude-stream") return `${text}\n`
+  return `${JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } })}\n`
+}
+
+/**
+ * Stop what the harness is doing, without killing it.
+ *
+ * Measured: Claude Code answers a `control_request`/`interrupt` with a `control_response`
+ * success, ends the turn with `result/error_during_execution`, and **stays alive** — so the next
+ * message is a normal turn rather than a resume.
+ */
+export function interruptLine(protocol: AgentProtocol, requestId: string): string | null {
+  if (protocol !== "claude-stream") return null
+  return `${JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt" } })}\n`
+}
+
+/**
+ * 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.
+ *
+ * This exists because Claude Code names its own conversations — the title you see in the terminal
+ * and in `/resume` — but does **not** put that name on stdout: measured in a worker, a
+ * `--output-format stream-json` session emits `system/init`, `assistant`, `user` and `result`,
+ * and nothing else. The name is written to the session transcript, as one
+ * `{"type":"ai-title","aiTitle":…}` line per revision. So the only way to have it is to go and
+ * read it, once, out of band — which is why this returns a *shell* rather than a parser: it runs
+ * in the worker, where the transcript is.
+ *
+ * Deliberately not a `--name` handed to the harness (the flag exists): a task created without a
+ * title has no name to impose, and imposing the prompt's first line would just be our own
+ * placeholder read back to us.
+ *
+ * Found by file name rather than by rebuilding the per-directory path Claude Code derives from
+ * the cwd: that encoding is an internal detail, `find` by session id is not. A harness run with
+ * `--no-session-persistence` writes no transcript, and then this finds nothing — which is a
+ * normal answer, not an error.
+ *
+ * `jsonl` gets no probe on purpose: a harness speaking our vocabulary says the name in band,
+ * `{"type":"session.title","title":"…"}`, and pays nothing for it.
+ */
+export function sessionTitleProbe(protocol: AgentProtocol, sessionId: string): string | null {
+  if (!readsTitleOutOfBand(protocol)) return null
+  // The id comes from the harness's own output, and it is about to be interpolated into a shell
+  // run inside the worker. Nothing outside this alphabet has any business in a session id, and
+  // refusing is cheaper than trusting a CLI's field to be what it was yesterday. It also means
+  // the single quotes below are enough: the set excludes the quote itself.
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(sessionId)) return null
+  return [
+    `root="\${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"`,
+    `f=$(find "$root" -name '${sessionId}.jsonl' -type f 2>/dev/null | head -1)`,
+    `[ -n "$f" ] || exit 0`,
+    // The last few candidates, not just the last one: the pattern is a substring match on a file
+    // the agent itself can write into (a tool result quoting these very lines would match), so
+    // the reader below takes the last line that is actually a title record.
+    `grep -a '"type":"ai-title"' "$f" | tail -5`,
+  ].join("\n")
+}
+
+/**
+ * Does this dialect's name have to be fetched, rather than read off the stream? Asked *before* a
+ * session id is looked up, so a harness that says its name in band pays nothing for the question.
+ */
+export function readsTitleOutOfBand(protocol: AgentProtocol): boolean {
+  return protocol === "claude-json" || protocol === "claude-stream"
+}
+
+/** 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.
+ */
+export function parseSessionTitle(protocol: AgentProtocol, output: string): { title: string; source: string } | null {
+  if (!readsTitleOutOfBand(protocol)) return null
+  const lines = output.split("\n").map((l) => l.trim()).filter(Boolean)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(lines[i])
+    } catch {
+      continue
+    }
+    if (!parsed || typeof parsed !== "object") continue
+    const obj = parsed as Record<string, unknown>
+    if (obj.type !== "ai-title") continue
+    const title = cleanTitle(obj.aiTitle)
+    if (title) return { title, source: lines[i] }
+  }
+  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.
+ *
+ * Zero is a normal answer: a blank line, a line of prose from a harness that also logs to stdout,
+ * or an event type we deliberately have no use for.
+ */
+export function parseStreamLine(protocol: AgentProtocol, line: string): NormalizedEvent[] {
+  const trimmed = line.trim()
+  if (!trimmed) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(trimmed)
+  } catch {
+    // Not JSON. A harness that also writes human lines to stdout is common enough (a banner, a
+    // warning) that this must not be an error — but it must not be invisible either.
+    return [{ type: "raw", payload: { text: clip(trimmed).text } }]
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return []
+  const obj = parsed as Record<string, unknown>
+  return protocol === "claude-json" || protocol === "claude-stream" ? adaptClaudeJson(obj) : adaptPassthrough(obj)
+}
+
+/**
+ * `jsonl` — the project's harness already speaks our vocabulary. The escape hatch that means a
+ * home-made agent has nothing to learn beyond one page of documentation, and the thing that keeps
+ * the vocabulary honest: it is a format someone can write to, not just one we read from.
+ */
+function adaptPassthrough(obj: Record<string, unknown>): NormalizedEvent[] {
+  const type = typeof obj.type === "string" ? obj.type : null
+  if (!type) return [{ type: "raw", payload: { json: obj } }]
+  if (!(TASK_EVENT_TYPES as readonly string[]).includes(type)) {
+    return [{ type: "raw", payload: { json: obj } }]
+  }
+  const { type: _t, ...payload } = obj
+  return [{ type: type as TaskEventType, payload }]
+}
+
+/**
+ * `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") : [],
+        },
+      },
+    ]
+  }
+
+  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
+        }
+      }
+    }
+    // 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: {
+          status: obj.subtype === "success" ? "succeeded" : "failed",
+          stopReason: typeof obj.stop_reason === "string" ? obj.stop_reason : null,
+          summary: clip(obj.result).text,
+        },
+      },
+    ]
+    return events
+  }
+
+  // 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,
+    },
+  }
+}
+
+/** 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. */
+  model: string | null
+  /** Tokens in the prompt of the **latest** call: how full the window is right now. */
+  contextTokens: number | null
+  /** What that window holds, when it can be told from the model. */
+  contextWindow: number | null
+  inputTokens: number | null
+  outputTokens: number | null
+  cacheReadTokens: number | null
+  cacheCreationTokens: number | null
+  /** Only the harness can price a call, so this is always its own number, never ours. */
+  costUsd: number | null
+  turns: number | null
+  durationMs: number | null
+}
+
+/** The measurements `summarizeUsage` reduces, however the caller got hold of them. */
+export type UsageInput = {
+  /** Summed over every `scope: "call"` event of the task. */
+  calls: {
+    count: number
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens: number
+    cacheCreationTokens: number
+  }
+  /** The most recent `scope: "call"` payload — the one that carries the live context. */
+  latestCall: Record<string, unknown> | null
+  /** The most recent `scope: "session"` payload — the harness's running total. */
+  latestSession: Record<string, unknown> | null
+  /** The most recent `session.started` payload, for the model and the window it implies. */
+  started: Record<string, unknown> | null
+}
+
+/**
+ * Fold a task's usage events into the one recap a reader wants.
+ *
+ * Which number comes from where is the whole content of this function:
+ *
+ *  - **tokens** are summed from the per-call events rather than taken from the harness's total,
+ *    because a turn in flight has not produced a total yet — and "0 tokens" under a session that
+ *    has been working for ten minutes is the one answer that is never true. The harness's total
+ *    is the fallback for a dialect that only reports at the end.
+ *  - **money, turns and duration** can only come from the harness: pricing a call needs a rate
+ *    card, and a platform that made one up would be quoting a number it cannot stand behind.
+ *  - **context** is the latest call's prompt, against the window the *session* was opened with.
+ *
+ * `null` when a session has emitted no usage at all — nothing measured is not zero measured, and
+ * the difference is visible: the panel stays away instead of claiming a free session.
+ */
+export function summarizeUsage(input: UsageInput): SessionUsage | null {
+  const { calls, latestCall, latestSession, started } = input
+  if (calls.count === 0 && !latestSession) return null
+  const measured = calls.count > 0
+  const fallback = (key: string): number | null => num(latestSession?.[key])
+  return {
+    model:
+      (typeof latestCall?.model === "string" ? latestCall.model : null) ??
+      (typeof started?.model === "string" ? started.model : null),
+    contextTokens: num(latestCall?.contextTokens),
+    // Read off the line that opened the session; older events predate the field, so the model
+    // string is re-read as a fallback rather than leaving the meter blank on a live task.
+    contextWindow: num(started?.contextWindow) ?? contextWindowOf(started?.model as string | undefined),
+    inputTokens: measured ? calls.inputTokens : fallback("inputTokens"),
+    outputTokens: measured ? calls.outputTokens : fallback("outputTokens"),
+    cacheReadTokens: measured ? calls.cacheReadTokens : fallback("cacheReadTokens"),
+    cacheCreationTokens: measured ? calls.cacheCreationTokens : fallback("cacheCreationTokens"),
+    costUsd: fallback("costUsd"),
+    turns: fallback("turns"),
+    durationMs: fallback("durationMs"),
+  }
+}
+
+/** 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.
+ *
+ * The pairing lives here, next to the adapters, because it is the thing that makes normalization
+ * reversible: `type`/`payload` is our reading of the line, `source` is the line. Get the reading
+ * wrong and the line is still there to read again.
+ *
+ * `budget` bounds how many events one pass may produce, so a runaway session cannot blow past the
+ * per-task ceiling in a single chunk. An adapter that throws costs its line, not the pass.
+ */
+export function parseLines(protocol: AgentProtocol, lines: string[], budget: number): SourcedEvent[] {
+  const out: SourcedEvent[] = []
+  for (const line of lines) {
+    if (out.length >= budget) break
+    let events: NormalizedEvent[]
+    try {
+      events = parseStreamLine(protocol, line)
+    } 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 })
+    }
+  }
+  return out
+}
+
+/**
+ * Split a chunk of bytes into whole lines, and say how many bytes that consumed.
+ *
+ * The cursor only ever advances past a **complete** line: a read that lands mid-line leaves the
+ * tail for the next one. Without this, a 3 KB JSON event straddling two reads would be parsed as
+ * two halves — twice — and neither would be valid JSON.
+ */
+export function splitCompleteLines(chunk: Uint8Array): { lines: string[]; consumed: number } {
+  // `Uint8Array` rather than Node's `Buffer`: a Buffer *is* one, so every caller compiles
+  // unchanged, and the package stays runnable anywhere — see the rule in the README. That costs
+  // `lastIndexOf`, which Uint8Array does not have, hence the backwards scan.
+  let lastNewline = -1
+  for (let i = chunk.length - 1; i >= 0; i--) {
+    if (chunk[i] === 0x0a) {
+      lastNewline = i
+      break
+    }
+  }
+  if (lastNewline === -1) return { lines: [], consumed: 0 }
+  const consumed = lastNewline + 1
+  return { lines: new TextDecoder().decode(chunk.subarray(0, consumed)).split("\n"), consumed }
+}