traintrack 2.0.0

package/dist/mcp/server.js

@@ -0,0 +1,198 @@
+// ─── Traintrack stdio MCP server ─────────────────────────────────────────────
+// A tiny stdio MCP (Model Context Protocol) server that the lead's TUI talks to.
+// It exposes four tools — spawn_worker, await_results, send_message,
+// check_messages — each operating directly on a local SQLite Channel. There is
+// no RuntimeClient and no Orca runtime here: this process OWNS its Channel.
+//
+// The lead's own handle (used as `from` on outgoing messages and `to` for the
+// inbox it drains) is TRAINTRACK_HANDLE, defaulting to 'lead'. The Channel db path is
+// TRAINTRACK_CHANNEL, defaulting to <cwd>/.traintrack/channel.db.
+//
+// MCP transport is newline-delimited JSON-RPC 2.0 over stdio. The protocol
+// surface we need is small (initialize, tools/list, tools/call, ping, the
+// initialized notification), so this is hand-rolled rather than pulling in the
+// SDK. The protocol logic is split from the stdin/stdout wiring so it is
+// unit-testable without a process.
+import { createInterface } from 'node:readline';
+import { randomBytes } from 'node:crypto';
+import { Channel } from '../channel/channel.js';
+import { resolveChannelPath } from '../channel/resolve.js';
+import { spawnWorker } from '../spawn/spawn.js';
+import { TOOLS, spawnWorkerTool, awaitResultsTool, sendMessageTool, checkMessagesTool, listTeamTool, delegateTaskTool, joinTeamTool, } from './tools.js';
+const SERVER_NAME = 'traintrack';
+const SERVER_VERSION = '0.1.0';
+// The MCP protocol version we implement. We echo the client's requested version
+// when present (forward-compat with newer clients) and fall back to this.
+const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
+function ok(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function errorResult(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+async function callTool(name, args, deps) {
+    try {
+        switch (name) {
+            case 'spawn_worker':
+                return await spawnWorkerTool(args, deps);
+            case 'await_results':
+                return await awaitResultsTool(args, deps);
+            case 'send_message':
+                return await sendMessageTool(args, deps);
+            case 'check_messages':
+                return await checkMessagesTool(args, deps);
+            case 'list_team':
+                return listTeamTool(deps);
+            case 'delegate_task': {
+                const to = typeof args.to === 'string' ? args.to.trim() : '';
+                const task = typeof args.task === 'string' ? args.task.trim() : '';
+                if (!to || !task) {
+                    return errorResult('"to" (a teammate handle) and "task" are both required.');
+                }
+                return delegateTaskTool(deps, to, task);
+            }
+            case 'join_team': {
+                const handle = typeof args.handle === 'string' ? args.handle.trim() : '';
+                const role = typeof args.role === 'string' ? args.role.trim() : '';
+                const agent = typeof args.agent === 'string' ? args.agent.trim() : undefined;
+                if (!handle || !role) {
+                    return errorResult('"handle" and "role" are both required to join a team.');
+                }
+                return joinTeamTool(deps, handle, role, agent);
+            }
+            default:
+                return errorResult(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        // Why: a tool (e.g. spawnWorker's git worktree add) can throw. Surface it as
+        // an isError result so the model sees the failure text rather than the
+        // transport dropping the call.
+        const detail = error instanceof Error ? error.message : String(error);
+        return errorResult(`Tool "${name}" failed: ${detail}`);
+    }
+}
+/** Handle one parsed JSON-RPC message. Returns the response to write, or null
+ *  for notifications (no id) — which get no reply. Pure except for the injected
+ *  deps (Channel + spawnWorker), so it is fully unit-testable. */
+export async function handleMessage(req, deps) {
+    // A JSON-RPC notification omits `id` — process side effects, send nothing
+    // back. This covers notifications/initialized and any other notification.
+    if (req.id === undefined) {
+        return null;
+    }
+    const id = req.id;
+    const method = req.method;
+    if (method === 'initialize') {
+        const requested = req.params?.protocolVersion;
+        const protocolVersion = typeof requested === 'string' ? requested : DEFAULT_PROTOCOL_VERSION;
+        return ok(id, {
+            protocolVersion,
+            capabilities: { tools: {} },
+            serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+        });
+    }
+    if (method === 'ping') {
+        return ok(id, {});
+    }
+    if (method === 'tools/list') {
+        return ok(id, { tools: TOOLS });
+    }
+    if (method === 'tools/call') {
+        const name = typeof req.params?.name === 'string' ? req.params.name : '';
+        const args = req.params?.arguments && typeof req.params.arguments === 'object'
+            ? req.params.arguments
+            : {};
+        return ok(id, withUnreadNudge(await callTool(name, args, deps), name, deps));
+    }
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32601, message: `Method not found: ${method ?? ''}` },
+    };
+}
+/** Build the tool deps from the environment AND auto-join this live session to
+ *  its project team. The channel is resolved to the GIT REPO ROOT (so every
+ *  session in a project shares one team — see resolveChannelPath). The session's
+ *  handle is TRAINTRACK_HANDLE or a freshly-minted `<agent>-<rand>`, its agent is
+ *  TRAINTRACK_AGENT (default 'claude'), and it registers itself as a live member
+ *  on startup so teammates see it immediately. */
+export function buildDepsFromEnv() {
+    const dbPath = resolveChannelPath();
+    const channel = new Channel(dbPath);
+    const agent = process.env['TRAINTRACK_AGENT'] ?? 'claude';
+    const role = process.env['TRAINTRACK_ROLE'] ?? 'lead';
+    const handle = process.env['TRAINTRACK_HANDLE'] ?? `${agent}-${randomBytes(3).toString('hex')}`;
+    // Auto-presence: this hand-driven session joins its project team on startup so
+    // teammates discover it with zero fiddling (no explicit join / channel path).
+    channel.addMember({ handle, agent, role, kind: 'live', status: 'active', worktree: process.cwd() });
+    return { self: handle, channel, spawnWorker };
+}
+/** Append a one-line "you have mail" nudge to a tool result when the session has
+ *  unread messages — so a live agent learns of teammate messages the moment it
+ *  uses any tool, without a fragile per-turn OS hook. check_messages/await_results
+ *  already surface messages, so they are skipped. */
+export function withUnreadNudge(result, name, deps) {
+    if (name === 'check_messages' || name === 'await_results')
+        return result;
+    let unread = 0;
+    try {
+        unread = deps.channel.getUnread(deps.self).length;
+    }
+    catch {
+        return result;
+    }
+    if (unread === 0)
+        return result;
+    const note = `\n\n📨 ${unread} unread message${unread === 1 ? '' : 's'} from teammates — call check_messages to read ${unread === 1 ? 'it' : 'them'}.`;
+    const content = result.content.length ? result.content : [{ type: 'text', text: '' }];
+    const last = content[content.length - 1];
+    return {
+        ...result,
+        content: [...content.slice(0, -1), { type: 'text', text: (last.text || '') + note }],
+    };
+}
+/** Run the stdio MCP loop until the input stream closes. Reads newline-delimited
+ *  JSON-RPC requests and writes newline-delimited responses. Streams + deps are
+ *  injectable so the full loop (readline framing → handler) is testable
+ *  end-to-end; the defaults wire the real process stdio + env. */
+export function runTraintrackMcpServer(io = {}) {
+    const deps = io.deps ?? buildDepsFromEnv();
+    const usingRealStdin = !io.input;
+    const input = io.input ?? process.stdin;
+    const output = io.output ?? process.stdout;
+    const rl = createInterface({ input });
+    rl.on('line', (line) => {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return;
+        }
+        let req;
+        try {
+            req = JSON.parse(trimmed);
+        }
+        catch {
+            output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`);
+            return;
+        }
+        void handleMessage(req, deps).then((res) => {
+            if (res) {
+                output.write(`${JSON.stringify(res)}\n`);
+            }
+        });
+    });
+    rl.on('close', () => {
+        // Mark this session offline so teammates' rosters reflect it leaving.
+        try {
+            deps.channel.setStatus(deps.self, 'offline');
+        }
+        catch {
+            // best-effort; never block shutdown
+        }
+        // Only tear the process down when we own the real stdin; an injected stream
+        // closing (a test) must not kill the host process.
+        if (usingRealStdin) {
+            process.exit(0);
+        }
+    });
+}

package/dist/mcp/tools.js

@@ -0,0 +1,207 @@
+// ─── Traintrack MCP tools ─────────────────────────────────────────────────────
+// The four coordination tools the lead's TUI drives over a local Channel:
+//   spawn_worker(agent, role, task) — hand out work to a fresh worker
+//   await_results(timeoutMs?)       — block for the workers' replies
+//   send_message(to, body)          — fire-and-forget message to one handle
+//   check_messages()                — drain this lead's unread inbox
+//
+// Each tool takes its dependencies (the lead's own handle, the Channel, the
+// spawnWorker impl, and a sleep) injected, so they are unit-testable against a
+// real temp-file Channel with a faked spawnWorker and an instant sleep — no
+// process, no readline, no protocol shell.
+import { gitRoot } from '../channel/resolve.js';
+/** The MCP tool definitions advertised by tools/list. */
+export const TOOLS = [
+    {
+        name: 'spawn_worker',
+        description: "Spawn a new worker agent of the given type and role in its own git worktree, and assign it a task. Returns the new worker's handle so you can reference it later. As lead, call spawn_worker to hand out work, then call await_results to block until the workers reply with their results.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agent: {
+                    type: 'string',
+                    description: 'The agent type to spawn — "claude" or "codex".',
+                },
+                role: {
+                    type: 'string',
+                    description: 'The role name for the new worker, e.g. "api", "ui", "tests".',
+                },
+                task: { type: 'string', description: 'The initial task to assign to the spawned worker.' },
+            },
+            required: ['agent', 'role', 'task'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'await_results',
+        description: "Block until a worker replies with results (or the timeout expires). Use this AFTER calling spawn_worker to collect the workers' replies. Returns the formatted replies addressed to you, or a timeout message if none arrive in time.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                timeoutMs: {
+                    type: 'number',
+                    description: 'How long to wait for results in milliseconds. Defaults to 120000 (2 minutes).',
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'send_message',
+        description: 'Send a message to another agent in this workspace. It is posted to that agent in the BACKGROUND via the channel — they read it on their own cadence with check_messages — so it never interrupts them.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                to: { type: 'string', description: 'The recipient worker handle.' },
+                body: { type: 'string', description: 'The message text to send.' },
+            },
+            required: ['to', 'body'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'check_messages',
+        description: 'Read and consume the unread messages addressed to you — anything your workers have sent, including their results. This marks them read so you do not see them again. Use it to catch up without blocking.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'list_team',
+        description: 'List all teammates currently registered in this workspace — their handles, agent types, roles, and status. Use this to see who you can delegate to before calling delegate_task, or after spawn_worker to confirm a new worker is registered.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'delegate_task',
+        description: 'Assign a task to an existing teammate by handle. This posts a task message to their inbox via the channel — they pick it up on their own cadence. Use list_team to see valid handles, spawn_worker to add a new teammate, then await_results to collect their reply.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                to: { type: 'string', description: 'The handle of the teammate to delegate to (must already exist in the team).' },
+                task: { type: 'string', description: 'The task description to assign to the teammate.' },
+            },
+            required: ['to', 'task'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'join_team',
+        description: 'Join an EXISTING team as a live member. Use this when you are NOT the lead — e.g. a human added your session to a running team and you should start receiving its messages. Registers you in the shared roster under the given handle and role so teammates can reach you, and binds this session to that handle. After joining, call check_messages to pick up anything addressed to you.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handle: { type: 'string', description: 'The unique handle to register yourself under, e.g. "reviewer".' },
+                role: { type: 'string', description: 'Your role on the team, e.g. "reviewer", "qa".' },
+                agent: { type: 'string', description: 'Optional: your agent type, "claude" or "codex" (defaults to "claude").' },
+            },
+            required: ['handle', 'role'],
+            additionalProperties: false,
+        },
+    },
+];
+const VALID_AGENTS = ['claude', 'codex'];
+function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function errorResult(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+function realSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function formatMessage(m) {
+    return `- [${m.id}] from ${m.from}: ${m.body}`;
+}
+/** Drain a non-empty batch of unread messages: mark them read and format. */
+function drain(messages, channel, header) {
+    channel.markRead(messages.map((m) => m.id));
+    return textResult(`${header}:\n${messages.map(formatMessage).join('\n')}`);
+}
+export async function spawnWorkerTool(args, deps) {
+    const agent = typeof args.agent === 'string' ? args.agent.trim() : '';
+    const role = typeof args.role === 'string' ? args.role.trim() : '';
+    const task = typeof args.task === 'string' ? args.task.trim() : '';
+    if (!agent || !role || !task) {
+        return errorResult('"agent", "role", and "task" are all required.');
+    }
+    if (!VALID_AGENTS.includes(agent)) {
+        return errorResult(`Unknown agent "${agent}". Valid agents: ${VALID_AGENTS.join(', ')}.`);
+    }
+    const { handle } = await deps.spawnWorker({
+        channel: deps.channel,
+        // Worktrees must be created from the git root, even if the lead session is in
+        // a subdirectory of the project.
+        repoRoot: gitRoot(process.cwd()) ?? process.cwd(),
+        agent,
+        role,
+        task,
+        leadHandle: deps.self,
+    });
+    return textResult(`Spawned ${agent} worker (${role}) as ${handle}. Call await_results to collect their reply.`);
+}
+export async function sendMessageTool(args, deps) {
+    const to = typeof args.to === 'string' ? args.to.trim() : '';
+    const body = typeof args.body === 'string' ? args.body : '';
+    if (!to || !body.trim()) {
+        return errorResult('Both "to" (a worker handle) and "body" are required.');
+    }
+    deps.channel.insertMessage({ to, from: deps.self, body });
+    return textResult(`Sent to ${to}. They'll pick it up with check_messages — it does not interrupt them.`);
+}
+export async function checkMessagesTool(_args, deps) {
+    const msgs = deps.channel.getUnread(deps.self);
+    if (msgs.length === 0) {
+        return textResult('No messages.');
+    }
+    return drain(msgs, deps.channel, 'Messages');
+}
+export function listTeamTool(deps) {
+    const members = deps.channel.listMembers();
+    if (members.length === 0) {
+        return { content: [{ type: 'text', text: 'No teammates yet. Use spawn_worker to recruit one.' }] };
+    }
+    const lines = members.map((m) => `- ${m.handle} (${m.agent}, role: ${m.role}, ${m.status})`).join('\n');
+    return { content: [{ type: 'text', text: `Team:\n${lines}` }] };
+}
+export function delegateTaskTool(deps, to, task) {
+    if (!deps.channel.getMember(to)) {
+        const valid = deps.channel.listMembers().map((m) => m.handle).join(', ') || '(none)';
+        return { content: [{ type: 'text', text: `No teammate "${to}". Valid: ${valid}. Use list_team / spawn_worker.` }], isError: true };
+    }
+    deps.channel.insertMessage({ to, from: deps.self, body: task, type: 'task' });
+    return { content: [{ type: 'text', text: `Delegated to ${to}. Call await_results to collect the reply.` }] };
+}
+export function joinTeamTool(deps, handle, role, agent) {
+    // Guard against clobbering an existing member — addMember is INSERT OR REPLACE,
+    // so joining under a taken handle (e.g. "lead" or a running worker) would
+    // silently overwrite that member's roster row and scramble addressing. Reject
+    // instead; handles must be unique on the team.
+    const existing = deps.channel.getMember(handle);
+    if (existing) {
+        return errorResult(`Handle "${handle}" is already taken (a ${existing.kind} member, role: ${existing.role}). Pick a different handle — handles must be unique on the team.`);
+    }
+    const a = agent && VALID_AGENTS.includes(agent) ? agent : 'claude';
+    deps.channel.addMember({ handle, agent: a, role, kind: 'live', status: 'active', worktree: null });
+    deps.self = handle;
+    const lines = deps.channel
+        .listMembers()
+        .map((m) => `- ${m.handle} (${m.agent}, role: ${m.role}, ${m.status})`)
+        .join('\n');
+    return textResult(`Joined the team as ${handle} (role: ${role}). You are now a LIVE member — messages addressed to ${handle} land in your inbox; call check_messages whenever you finish a unit of work so you never miss one. Team:\n${lines}`);
+}
+export async function awaitResultsTool(args, deps) {
+    const timeoutMs = typeof args.timeoutMs === 'number' ? args.timeoutMs : 120000;
+    const sleep = deps.sleep ?? realSleep;
+    const deadline = Date.now() + timeoutMs;
+    // Poll every ~250ms for new replies; return the first non-empty batch (marking
+    // it read) or fall out to the timeout message once the deadline passes. We
+    // always poll at least once, so a pre-seeded message returns immediately.
+    for (;;) {
+        const msgs = deps.channel.getUnread(deps.self);
+        if (msgs.length > 0) {
+            return drain(msgs, deps.channel, 'Worker results');
+        }
+        if (Date.now() >= deadline) {
+            return textResult('No results within the timeout.');
+        }
+        await sleep(250);
+    }
+}

package/dist/mcp-server.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// ─── traintrack MCP server entry point ──────────────────────────────────────
+// The executable wired into .mcp.json. Claude Code launches this as a long-lived
+// stdio process; it opens the Channel from TRAINTRACK_CHANNEL (default
+// <cwd>/.traintrack/channel.db) and runs the JSON-RPC readline loop until stdin
+// closes. All the logic lives in ./mcp/server.js — this file is just the shim.
+import { runTraintrackMcpServer } from './mcp/server.js';
+runTraintrackMcpServer();

package/dist/onboarding/briefing.js

@@ -0,0 +1,24 @@
+/** Build the onboarding briefing handed to every team member so it knows the
+ *  team, its teammates, the coordination tools, and that it must watch for messages. */
+export function buildBriefing(args) {
+    const others = args.roster.filter((r) => r.handle !== args.selfHandle);
+    const rosterLines = others.length
+        ? others.map((r) => `  - ${r.handle} (${r.agent}, role: ${r.role})`).join('\n')
+        : '  (no other members yet — more may join)';
+    return [
+        `You are a member of the "${args.teamName}" agent team. Your role: ${args.selfRole}.`,
+        `Your teammates:`,
+        rosterLines,
+        ``,
+        `How you coordinate: you run as a headless worker turn — you do NOT have MCP tools.`,
+        `Just reply in plain text. Your reply is automatically delivered back to whoever`,
+        `messaged you, so you do not need to "send" or "check" anything by hand.`,
+        ``,
+        `To direct your reply at a SPECIFIC teammate instead of the sender, start your`,
+        `reply with @<their-handle-or-role> followed by your message — e.g. "@lead done: ...".`,
+        `Otherwise your reply goes back to whoever messaged you.`,
+        ``,
+        `A teammate may message you at ANY time; each incoming message starts a fresh turn`,
+        `for you with that message included, so you will always see new requests.`
+    ].join('\n');
+}

package/dist/runner/argv.js

@@ -0,0 +1,47 @@
+// Why: build the exact non-interactive argv for one headless agent turn. claude
+// runs `--print --output-format stream-json` (the structured stream the
+// event-parser consumes); codex runs `exec [resume <id>] --json`. Centralizing
+// argv here keeps the codex landmines in one audited place: ALWAYS pass
+// --dangerously-bypass-approvals-and-sandbox (else unattended MCP tool calls
+// auto-cancel, openai/codex #24135) and resume by the CAPTURED thread id, never
+// --last (which is global and cross-wires parallel codex workers).
+// Local helpers: resolve the CLI binary from env or fall back to PATH.
+function resolveClaudeCommand() {
+    return process.env.TRAINTRACK_CLAUDE_BIN ?? 'claude';
+}
+function resolveCodexCommand() {
+    return process.env.TRAINTRACK_CODEX_BIN ?? 'codex';
+}
+// claude print mode + the JSON event stream (stream-json requires --verbose).
+const CLAUDE_STREAM_FLAGS = ['--print', '--output-format', 'stream-json', '--verbose'];
+/** Build {command, args} for a single headless turn. The prompt is always the trailing positional. */
+export function buildHeadlessArgv(input) {
+    const { agent, prompt, model, resumeSessionId } = input;
+    if (agent === 'claude') {
+        const command = input.claudeCommand ?? resolveClaudeCommand();
+        const args = [...CLAUDE_STREAM_FLAGS];
+        if (resumeSessionId) {
+            args.push('--resume', resumeSessionId);
+        }
+        if (model) {
+            args.push('--model', model);
+        }
+        args.push(prompt);
+        return { command, args };
+    }
+    // codex
+    const command = input.codexCommand ?? resolveCodexCommand();
+    const args = ['exec'];
+    if (resumeSessionId) {
+        args.push('resume', resumeSessionId);
+    }
+    args.push('--json');
+    if (input.codexBypassSandbox !== false) {
+        args.push('--dangerously-bypass-approvals-and-sandbox');
+    }
+    if (model) {
+        args.push('-m', model);
+    }
+    args.push(prompt);
+    return { command, args };
+}

package/dist/runner/event-parser.js

@@ -0,0 +1,165 @@
+// Why: a headless agent turn (claude `--print --output-format stream-json` or
+// codex `exec --json`) emits one JSON object per stdout line. This module is the
+// PURE classifier for that stream — no spawning, no I/O — so it can be table-
+// tested against fixture lines. It is the structured, in-band turn-end signal
+// that replaces PTY idle-guessing (see project_headless_worker_pivot): claude's
+// {type:'result'} and codex's {type:'turn.completed'} are authoritative ACKs.
+//
+// Ported from the abandoned Rust conductor's runtime/event_parser.rs.
+export function createTurnParseState(provider) {
+    return {
+        provider,
+        finalText: '',
+        streamedText: '',
+        isError: false,
+        ended: false
+    };
+}
+/**
+ * Parse one NDJSON line to a plain object. Returns null for blank or malformed
+ * lines — NEVER throws (a CLI can interleave non-JSON banner lines on stdout).
+ */
+export function parseJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || (trimmed[0] !== '{' && trimmed[0] !== '[')) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function str(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+function asRecord(v) {
+    return v && typeof v === 'object' && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+/** True when this event is the authoritative turn-end (the ACK). */
+export function isTurnEndEvent(provider, evt) {
+    const type = str(evt.type);
+    return provider === 'claude' ? type === 'result' : type === 'turn.completed';
+}
+/**
+ * The provider session id to pin for resume, if this event carries one.
+ * claude: the {type:'system',subtype:'init'} event (also present on `result`).
+ * codex: the {type:'thread.started'} event (turn 1 only) — load-bearing for
+ * per-agent resume; using --last with >1 codex worker cross-wires threads.
+ */
+export function extractSessionId(provider, evt) {
+    if (provider === 'claude') {
+        const type = str(evt.type);
+        if (type === 'system' && str(evt.subtype) === 'init') {
+            return str(evt.session_id);
+        }
+        if (type === 'result') {
+            return str(evt.session_id);
+        }
+        return undefined;
+    }
+    // codex
+    if (str(evt.type) === 'thread.started') {
+        return str(evt.thread_id) ?? str(evt.session_id);
+    }
+    return undefined;
+}
+/** Incremental assistant text from a streaming event, else undefined. */
+export function extractTextDelta(provider, evt) {
+    if (provider === 'claude') {
+        // {type:'assistant', message:{content:[{type:'text', text:'...'}]}}
+        if (str(evt.type) !== 'assistant') {
+            return undefined;
+        }
+        const message = asRecord(evt.message);
+        const content = message?.content;
+        if (!Array.isArray(content)) {
+            return undefined;
+        }
+        const parts = [];
+        for (const block of content) {
+            const rec = asRecord(block);
+            if (rec && str(rec.type) === 'text') {
+                const t = str(rec.text);
+                if (t) {
+                    parts.push(t);
+                }
+            }
+        }
+        return parts.length ? parts.join('') : undefined;
+    }
+    // codex: {type:'item.completed', item:{type:'agent_message', text:'...'}}
+    if (str(evt.type) !== 'item.completed') {
+        return undefined;
+    }
+    const item = asRecord(evt.item);
+    const itemType = item ? (str(item.type) ?? str(item.item_type)) : undefined;
+    if (item && (itemType === 'agent_message' || itemType === 'assistant_message')) {
+        return str(item.text);
+    }
+    return undefined;
+}
+function applyTurnEnd(state, evt) {
+    state.ended = true;
+    if (state.provider === 'claude') {
+        state.authoritativeText = str(evt.result) ?? state.authoritativeText;
+        state.isError = evt.is_error === true || str(evt.subtype)?.startsWith('error') === true;
+        const usage = asRecord(evt.usage);
+        state.tokensIn = num(usage?.input_tokens) ?? state.tokensIn;
+        state.tokensOut = num(usage?.output_tokens) ?? state.tokensOut;
+        state.costUsd = num(evt.total_cost_usd) ?? state.costUsd;
+    }
+    else {
+        // codex turn.completed
+        const status = str(evt.status);
+        state.isError = status === 'failed' || status === 'interrupted';
+        const usage = asRecord(evt.usage);
+        state.tokensIn = num(usage?.input_tokens) ?? state.tokensIn;
+        state.tokensOut = num(usage?.output_tokens) ?? state.tokensOut;
+    }
+}
+/**
+ * Reduce one stdout line into the accumulator state, mutating it in place.
+ * Returns the streaming text delta produced by this line (if any) so the caller
+ * can forward live tokens to the UI without re-parsing.
+ */
+export function reduceLine(state, line) {
+    const evt = parseJsonLine(line);
+    if (!evt) {
+        return {};
+    }
+    const sessionId = extractSessionId(state.provider, evt);
+    if (sessionId && !state.sessionId) {
+        state.sessionId = sessionId;
+    }
+    let delta;
+    if (!isTurnEndEvent(state.provider, evt)) {
+        delta = extractTextDelta(state.provider, evt);
+        if (delta) {
+            state.streamedText += delta;
+        }
+    }
+    else {
+        applyTurnEnd(state, evt);
+    }
+    return delta ? { delta } : {};
+}
+/** Snapshot the accumulator into a turn result (call after the stream closes). */
+export function finalizeTurn(state) {
+    return {
+        finalText: state.authoritativeText ?? state.streamedText,
+        sessionId: state.sessionId,
+        tokensIn: state.tokensIn,
+        tokensOut: state.tokensOut,
+        costUsd: state.costUsd,
+        isError: state.isError,
+        ended: state.ended
+    };
+}