[design] Structured engine adapters — parse each CLI's own JSON event stream, not a claude-or-raw switch

[serge-ivo]

Problem

The coding runner (packages/browser-runner/src/coding/headless.ts) picks the engine transcript mode with a single binary switch:

this.mode = config.clientType === "claude" ? "stream-json" : "raw";

• Claude runs as a persistent --input-format/--output-format stream-json process. handle() parses real events (assistant text, tool_use, tool_result, result), so we get: clean isolated messages, exact turn-end, per-turn usage records, and consequential-act attribution (PR/merge).
• Every other engine (codex/grok/gemini) runs runOneShot() and its stdout is captured raw — the assistant's answer is interleaved with every exec/curl/tool line, then clipped by the transcript-line cap, the 8000-char snapshot, and the 400-char timeline tail. Raw engines also return empty usage and empty acts by construction (takeUsage()/takeActs() — see A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers #556).

The result: for any non-Claude engine the console/timeline shows noisy, truncated output; spend is unmetered (#556); acts are unattributed (#594); and the handoff/last-line is scraped from prose (#621). This is not a per-engine bug — it's that mode and handle() are hardcoded to Claude's schema, so a structured-capable CLI (Codex exec --json, Gemini, etc.) has nowhere to plug its events in.

Proposed direction

Replace the claude/raw switch with a small per-engine adapter interface. Each engine declares:

1. how to build its structured-output launch argv (Claude: the stream-json flags in buildClaudeArgs; Codex: exec --json; …), and
2. how to map ONE event line → a normalized event: { assistantText | toolUse | toolResult | usage | turnEnd | error }.

The existing Claude code becomes the Claude adapter (behaviour-identical — pin it with the current headless.test.ts). Raw stdout stays as the generic fallback adapter for any CLI with no structured mode. HeadlessSession keeps its public surface (start/snapshot/runState/ready/input/interrupt/stop/alive, takeUsage/takeActs) — only the guts behind handle()/mode move.

Why this is the right shape

• It's the enabler: once events are normalized, usage (A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers #556, coding_timeline records no per-step token, cost, files-changed or test-result summary — the ordering half of this is fixed #674), act attribution (acts[].ok is documented in two supervision legends and absent from the payload; delegation budgets can enter 'exhausted' with no exit #594), and a structured handoff field (The handoff prompt a user answers is scraped from prose, because no structured field exists to prefer #621) fall out for every engine instead of being re-solved per engine.
• It matches the stated architecture that the platform owns the conversation, the engine's memory is an optimisation ([design] The platform owns the conversation — an engine's own memory is an optimisation, not the source of truth #693).
• One place to add the next engine, rather than a new special-case each time.

Acceptance

• An EngineAdapter (or equivalent) abstraction with: Claude adapter (structured), generic adapter (raw stdout fallback).
• headless.test.ts stays green with the Claude adapter — byte-identical transcript for a Claude turn.
• No behaviour change shipped by this issue alone; it unblocks A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers #556 / coding_timeline records no per-step token, cost, files-changed or test-result summary — the ordering half of this is fixed #674 / acts[].ok is documented in two supervision legends and absent from the payload; delegation budgets can enter 'exhausted' with no exit #594 / The handoff prompt a user answers is scraped from prose, because no structured field exists to prefer #621 and the Codex adapter (filed as a child).

Refs: #556, #674, #693, #621, #594

[serge-ivo]

Review note (adversarial BA assessment, 2026-08-22)

Code claims verified accurate (headless.ts:268 mode switch; takeUsage/takeActs return [] for raw at :781/:797; handle() reads Claude-only field paths). Two additions:

1. This subsumes step 3 of A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers #556 ("consider --json for Codex; if any raw engine grows a structured turn-end event, add it to STRUCTURED_ENGINES"). A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers #556 steps 1–2 are shipped; closing A Codex coding session is completely invisible — unmetered like a tmux drive, but unlike a tmux drive the absence is never recorded, and classifyEngineMetering has zero production callers #556 and forwarding the --json track here (see the epic).

2. Acceptance addition — corrupt-line tolerance is a first-class requirement, not Claude-incidental. The generic/structured adapters must tolerate non-JSON / malformed lines without corrupting or wedging a turn. This isn't hypothetical: Codex --json is reported to emit malformed output when tools are active (openai/codex#15451), so the adapter seam must guarantee "a bad line is dropped, the turn survives" as part of the contract (Claude's handle() already does this at headless.ts:656).

[serge-ivo]

Shipped the #728 adapter seam in 50aecb9.\n\nWhat landed:\n- Added a narrow EngineAdapter abstraction in packages/browser-runner/src/coding/engine-adapter.ts.\n- Claude now owns structured stream-json launch args and normalizes stream-json lines into session/text/tool/result/turn-end events.\n- Non-Claude engines stay on the generic raw fallback with argv passthrough and no structured parsing, preserving current behavior.\n- HeadlessSession now consumes normalized events instead of hardcoding the Claude JSON parse in-line.\n\nVerification:\n- pnpm vitest run packages/browser-runner/src/coding/engine-adapter.test.ts packages/browser-runner/src/coding/headless.test.ts\n- pnpm --filter @proagentstore/browser-runner typecheck\n- pnpm exec biome check packages/browser-runner/src/coding/engine-adapter.ts packages/browser-runner/src/coding/engine-adapter.test.ts packages/browser-runner/src/coding/headless.ts packages/browser-runner/src/coding/headless.test.ts\n- git diff --check