Tracking: terminal output rendering — work streams for agent team pickup #152

Architecture (established from relay source + CLI capabilities)

Relay supports two spawn transports. The default for Claude/Codex is PTY, but transport: 'headless' (piped stdin/stdout) works for any CLI — relay just forwards the chunks:

Claude — no relay changes needed

Pear passes --output-format stream-json --include-partial-messages as spawn args. Relay spawns Claude as a piped subprocess. Claude outputs NDJSON to stdout. Relay forwards chunks via worker_stream → broker:pty-chunk IPC. Pear renderer parses NDJSON and formats for xterm (V1) or custom UI (V2).

NDJSON shape to parse:

{ "event": { "type": "content_block_delta", "delta": { "type": "text_delta", "text": "..." } } }

Codex — relay has native app-server support

codex_session.rs in the relay broker uses .stdin(Stdio::piped()).stdout(Stdio::piped()) — Codex's app-server protocol is already understood by relay. Spawn with transport: 'headless' and relay handles the rest.

OpenCode — headless via HTTP SSE (different mechanism)

OpenCode runs opencode serve --port N and exposes /event SSE. Events: message.delta, file.changed, permission.requested.

Grok — PTY only (for now)

No structured output format available from xAI yet. Tracked in #141.

What "no PTY" means for user-facing features

Image paste is the main regression risk when moving off PTY. For V1, this is acceptable if documented. V2 can add an explicit image attach button.

Work streams

Stream 1 — Merge immediately (safe, no dependencies) ✅

• PR feat: improve terminal visual quality #142 — terminal visual quality (lineHeight, letterSpacing, bar cursor, 10k scrollback, tab fade)
• PR feat: add OpenCode to spawn dialogs and empty-state UI #143 — OpenCode in spawn dialogs and empty-state UI (UI-only)
• PR feat: add Grok as first-class harness #138 — Grok as first-class harness (PTY, correct for now)

Merge order: #142 and #143 first, then #138 (resolve trivial 3-way conflict in SpawnAgentDialog, TerminalPane, SpawnAgentCli).

Stream 2 — Claude headless + NDJSON rendering (V1)

Goal: spawn Claude with --output-format stream-json, parse NDJSON chunks in the renderer, display clean formatted text in xterm. No raw JSON visible.

Steps:

1. broker.ts: route Claude spawns through spawnCli({ transport: 'headless', args: ['--output-format', 'stream-json', '--include-partial-messages'] }).
2. Track runtime per agent session in BrokerManager.
3. Renderer: for headless Claude agents, parse broker:pty-chunk NDJSON before passing to xterm — extract content_block_delta.text_delta.text, emit clean text only.
4. Handle trust/permissions: either --dangerously-skip-permissions flag or confirm MCP trust approach in relay.

Note: PR #139 has the right shape for this work but has two blockers — relay 8.3.0 lockfile not updated, and the NDJSON parsing (step 3) is absent so raw JSON hits xterm. Fix both before merging.

Stream 3 — Codex headless + app-server rendering (V1)

Relay's broker already understands Codex's app-server protocol (codex_session.rs). Steps:

1. broker.ts: route Codex spawns through spawnCli({ transport: 'headless' }).
2. Parse Codex app-server event chunks in renderer: AgentMessageDelta, FileChangePatchUpdated, ApplyPatchApprovalParams.
3. Emit formatted text to xterm.

Can be done in same PR as Stream 2 or separately.

Stream 4 — OpenCode headless routing + SSE rendering (V1)

PR #140 has the right idea but depends on PR #139. Once #139 is fixed and merged:

1. Route OpenCode through spawnCli({ transport: 'headless' }).
2. Parse message.delta SSE chunks → formatted xterm text.

Stream 5 — V2 native Pear UI (all headless CLIs)

No xterm for headless agents. Replace terminal pane with React components:

• message.delta → message bubbles
• file.changed → diff cards
• permission.requested → native approval dialogs
• Claude tool use events → collapsible tool call cards

Separate PR track, not blocking V1.

Stream 6 — Grok headless (blocked on xAI, tracked in #141)

Nothing to build until xAI ships structured output. When it arrives, follows Stream 2 pattern.

PRs at a glance

Agent team pickup checklist

• Merge feat: improve terminal visual quality #142
• Merge feat: add OpenCode to spawn dialogs and empty-state UI #143
• Merge feat: add Grok as first-class harness #138 (resolve 3-way conflict)
• Fix ⛔ DO NOT MERGE — feat: upgrade @agent-relay to 8.3.0, wire headless spawn routing and runtime tracking #139: run npm install, commit lockfile; add NDJSON renderer parsing (Stream 2 step 3)
• Fix ⛔ DO NOT MERGE — feat: wire OpenCode into spawn dialogs and empty-state UI (headless routing) #140: rebase on fixed ⛔ DO NOT MERGE — feat: upgrade @agent-relay to 8.3.0, wire headless spawn routing and runtime tracking #139; add OpenCode SSE rendering
• Merge ⛔ DO NOT MERGE — feat: upgrade @agent-relay to 8.3.0, wire headless spawn routing and runtime tracking #139 → merge ⛔ DO NOT MERGE — feat: wire OpenCode into spawn dialogs and empty-state UI (headless routing) #140
• Stream 3: Codex app-server rendering (can be added to ⛔ DO NOT MERGE — feat: upgrade @agent-relay to 8.3.0, wire headless spawn routing and runtime tracking #139 or separate PR)
• Stream 5: V2 native UI (separate PR track, not blocking)
• Watch feat: enable headless spawn for Grok once relay confirms streaming-json support #141 for xAI announcement