SDK: first-class headless adapter per agent CLI, replacing raw -p wrapper scripts

[khaliqgant]

Problem

An agent step today is spawn(cli, [instruction]) (sdk/src/worker.ts), and the "CLI" is a per-flow wrapper script that calls claude -p … and hands back stdout (testdata/preflight/analyze-story-claude-cli). The research example's first shim did the same. Consequences:

• No trajectory. claude -p prints only the final message; the step's journal gets one line. RFC-0001 says an agent step's output is artifact + diff + trajectory.
• No budget line. Token usage and cost are discarded, so decision 10 (every token has one owner) cannot be enforced or even observed.
• No subagent evidence. A flow that instructs "spawn two subagents" cannot tell whether it happened.
• Fail-open success. A CLI that exits 0 with no readable final message reads as a success with an empty summary.
• Every flow re-invents the invocation, and each wrapper drifts (model flag, permissions flag, prompt via argv vs stdin).

What exists

Every supported CLI has a non-interactive mode with structured output and usage, verified 2026-09-02:

CLI	Invocation	Final message	Usage / cost	Session	Extra
claude	-p --output-format stream-json --verbose	{"type":"result","result"}	usage.*, total_cost_usd	session_id	subagent_stats, modelUsage, is_error
codex	exec --json -	item.completed / agent_message.text	turn.completed.usage (no cost)	thread.started.thread_id	—
grok	--prompt-file F --output-format json	text	usage.*, total_cost_usd	sessionId	thought, modelUsage

Proposal

A first-class headless adapter per CLI in the SDK, owned by AgentWorker, replacing per-flow wrapper scripts:

interface HeadlessAdapter {
  invocation(opts: { model?: string; promptFile: string; cwd: string }): { argv: string[]; stdin: "prompt" | "none" };
  parse(stdout: string): { finalText: string; usage?: Usage; sessionId?: string; subagents?: unknown; events: unknown[] };
}

• The instruction travels by stdin or prompt file, never argv (ARG_MAX).
• parse throws when there is no final message → worker_error, never an empty success.
• events are journaled as the step's trajectory; usage (cost as a decimal string) is the step's budget line and feeds the kernel's budget envelope; subagents lets a gate assert delegation happened.
• RELAYFLOW_MODEL semantics unchanged: set only when declared.
• flows check preflight can use the same adapter for the auth status probe, so the probe and the real invocation cannot disagree.
• Adding a CLI (opencode, gemini) is adding one adapter, not touching every flow.

Reference implementation

examples/research/shims/headless.ts on branch research-flow implements the three adapters above with parser tests against the verified shapes (examples/research/tests/research.test.ts), and shims/agent-cli.ts consumes it: writes <step>.trajectory.jsonl, returns usage, sessionId, subagents. Live smoke 2026-09-02: all three CLIs returned final text, usage, session ids and trajectories (12 / 10 / 1 events) in ~19s. Its header says REPLACE-WHEN: the SDK's AgentWorker owns a headless adapter per CLI — this issue.

Done when

• AgentWorker dispatches a declared cli: claude|codex|grok through the adapter with no wrapper script; testdata/preflight/analyze-story-claude-cli is deleted or reduced to a fixture.
• The journal's step.complete for an agent step carries trajectory, usage and sessionId.
• A step whose CLI exits 0 without a final message completes worker_error.
• The research example's shims/headless.ts is deleted and the flow runs unchanged.

Related: #132 (v2 authoring ergonomics).

[khaliqgant]

Prior art in ../relayflows (v1) — port, don't reinvent

v1 already solved most of this; none of it was carried into the rewrite:

• packages/core/src/schema.ts:59-78 — interactive?: boolean per agent, with presets: lead → interactive PTY, relay-aware; worker / reviewer / analyst → interactive: false, structured output, no sub-agents.
• packages/core/src/cli-registry.ts — CLI_REGISTRY with binaries, nonInteractiveArgs, bypassFlag (+ aliases), searchPaths, ignoreExitCode for claude, codex, gemini, opencode, droid, aider, goose, cursor-agent, agent, cursor, api. Vendored from @agent-relay/sdk v7 when v8 moved spawning to @agent-relay/harnesses.
• packages/core/src/process-spawner.ts — PTY vs plain subprocess by interactive.
• packages/core/src/cli-session-collector.ts + collectors/{claude,codex,opencode}.ts — recover sessionId, model, cost, tokens {input, output, cacheRead}, toolCalls, errors, finalStatus from each CLI's on-disk session files after the run.

What v1 got right and the adapter should keep: one registry, per-CLI bypass flags, well-known install paths, ignoreExitCode for CLIs that misreport, the interactive/non-interactive split as a declared property of the agent.

What the adapter should do better than v1: v1 put the task on argv (nonInteractiveArgs: (task) => ['-p', ..., task], ARG_MAX) and used bare -p, recovering usage after the fact by reading session files. Claude, Codex and Grok now emit usage, session id and (Claude) subagent_stats in-band via structured output, so the collector becomes the fallback for CLIs without a structured mode rather than the primary path.

The interactive half maps to a different v2 primitive: v1's PTY + relay-channel coordination is what gate 4's durable kernel streams replace. So: port the registry + collectors into the headless adapter now (this issue); the interactive mode is a gate-4 concern and should be tracked there, not here.