@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/core/codex-ui-mapper.js

@@ -0,0 +1,799 @@
+/**
+ * Pure codex app-server JSON-RPC → protocol-v2 mapper. `mapCodexNotification`
+ * folds one parsed JSONL frame into `UiEvent`s plus the next mapper state;
+ * the runner calls it ALONGSIDE the v1 path (v1 events keep flowing
+ * unchanged).
+ *
+ * Contract: `.ai/analysis/cockpit-ui-redesign/agent-event-protocols.md` §3
+ * (wire format) and §7.1 "Codex (app-server)" (the mapping). Golden fixtures
+ * replaying wire-faithful frame sequences live in `__fixtures__/codex/`.
+ *
+ * Robustness rule: input is untrusted wire data — the mapper never throws;
+ * responses, server→client requests (handled by the session transport) and
+ * unknown methods map to zero events.
+ *
+ * State is explicit and treated as immutable: callers thread the returned
+ * `state` into the next call. Ids are deterministic — codex items and turns
+ * carry stable wire ids which are reused verbatim (`turn_<n>` is minted only
+ * when a turn frame arrives without one) — so replaying a stored transcript
+ * reproduces the exact event sequence.
+ *
+ * Status map (§7.1, kills v1's regex-on-status hack): `inProgress→running`,
+ * `completed→completed`, `failed→failed`, `declined→declined`.
+ */
+import { codexStreamError } from './codex-stream-error.js';
+import { collabParentItemId, mapHookCompleted, threadIdOf } from './codex-hook-mapper.js';
+import { toolDisplay } from '../contract/index.js';
+import { codexTurnOutcome } from './codex-turn-outcome.js';
+export { HOOK_STATUS } from './codex-hook-mapper.js';
+export function createCodexUiState() {
+    return {
+        sessionStarted: false,
+        turnSeq: 0,
+        currentTurnId: null,
+        pendingTurnUsage: null,
+        knownItems: new Set(),
+        outputs: new Map(),
+        reasonings: new Map(),
+        planFromNotification: false,
+        reviewItemId: null,
+        collabTasks: new Map(),
+        backgroundTasks: new Map(),
+    };
+}
+/**
+ * Codex confirms the thread via the `thread/start`/`thread/resume` RESULT
+ * (a response frame the mapper cannot attribute), so the runner calls this
+ * once the thread id is known. Deduplicated against the `thread/started`
+ * notification — whichever arrives first emits `session.started`.
+ */
+export function codexSessionStarted(threadId, state) {
+    if (state.sessionStarted || threadId === '')
+        return { events: [], state };
+    return {
+        events: [{ type: 'session.started', sessionId: threadId, backend: 'codex' }],
+        state: { ...state, sessionStarted: true },
+    };
+}
+/** Fold one parsed JSON-RPC frame into v2 events. Never throws. */
+export function mapCodexNotification(frame, state) {
+    if (!isRecord(frame) || typeof frame.method !== 'string')
+        return { events: [], state };
+    // Server requests are answered by CodexSession, not the notification mapper.
+    if (frame.id !== undefined)
+        return { events: [], state };
+    const params = isRecord(frame.params) ? frame.params : {};
+    const mapper = CODEX_NOTIFICATION_MAPPERS.get(frame.method);
+    if (mapper === undefined) {
+        // thread/status/changed, thread/closed, … — nothing to render yet.
+        return { events: [], state };
+    }
+    return mapper(params, state);
+}
+/** Method → mapper for the notification arms of the §7.1 mapping. */
+const CODEX_NOTIFICATION_MAPPERS = new Map([
+    ['error', mapErrorNotification],
+    ['warning', mapWarningNotification],
+    ['thread/started', mapThreadStartedNotification],
+    ['turn/started', mapTurnStarted],
+    ['turn/completed', (params, state) => mapTurnEnd(params, state, codexTurnOutcome('turn/completed', params))],
+    ['turn/failed', (params, state) => mapTurnEnd(params, state, codexTurnOutcome('turn/failed', params))],
+    ['turn/plan/updated', mapTurnPlanUpdated],
+    ['item/started', (params, state) => mapItemLifecycle(params, state, 'item.started')],
+    ['item/updated', (params, state) => mapItemLifecycle(params, state, 'item.updated')],
+    ['item/completed', (params, state) => mapItemLifecycle(params, state, 'item.completed')],
+    ['item/agentMessage/delta', (params, state) => mapDelta(params, state, 'text')],
+    ['item/reasoning/textDelta', (params, state) => mapDelta(params, state, 'reasoning', 'text')],
+    ['item/reasoning/summaryDelta', (params, state) => mapDelta(params, state, 'reasoning', 'summary')],
+    ['item/reasoning/summaryTextDelta', (params, state) => mapDelta(params, state, 'reasoning', 'summary')],
+    ['item/commandExecution/outputDelta', (params, state) => mapDelta(params, state, 'output')],
+    ['thread/tokenUsage/updated', mapTokenUsage],
+    ['hook/completed', mapHookNotification],
+]);
+function mapErrorNotification(params, state) {
+    const message = codexStreamError(params);
+    return { events: message ? [{ type: 'session.error', message, fatal: params.willRetry === false }] : [], state };
+}
+function mapWarningNotification(params, state) {
+    const message = str(params.message);
+    return { events: message ? [{ type: 'session.error', message, fatal: false }] : [], state };
+}
+function mapThreadStartedNotification(params, state) {
+    return codexSessionStarted(threadIdOf(params) ?? '', state);
+}
+function mapHookNotification(params, state) {
+    // `hook/started` renders nothing: hooks are completion-only
+    // (hearsay-tools/cezarion#961).
+    return { events: mapHookCompleted(params, state), state };
+}
+// ---- turn lifecycle ---------------------------------------------------------
+function mapTurnStarted(params, state) {
+    const turnSeq = state.turnSeq + 1;
+    const turnId = turnIdOf(params) ?? `turn_${turnSeq}`;
+    return {
+        events: [{ type: 'turn.started', turnId }],
+        // planFromNotification is turn-scoped — a new turn re-opens the item arm.
+        // So are the reasoning accumulators: an interrupted item never completes,
+        // so its text would otherwise leak into a later turn that reuses the id
+        // and pin whole chains of thought in memory for the session (#528).
+        state: {
+            ...state,
+            turnSeq,
+            currentTurnId: turnId,
+            pendingTurnUsage: null,
+            planFromNotification: false,
+            reasonings: new Map(),
+        },
+    };
+}
+function mapTurnEnd(params, state, outcome) {
+    let turnSeq = state.turnSeq;
+    const turnId = turnIdOf(params) ?? state.currentTurnId ?? `turn_${++turnSeq}`;
+    const closesActiveTurn = state.currentTurnId === null || turnId === state.currentTurnId;
+    // A review span still open when the turn ends never gets its `exitedReviewMode` — an
+    // interrupted, cancelled or failed turn simply stops. Close it here, or the item stays
+    // `running` forever and the Agents dock reads a finished run as a live fan-out (#474).
+    // The status follows the turn: a turn that failed did not complete its review.
+    const events = [];
+    if (closesActiveTurn && state.reviewItemId !== null) {
+        events.push({
+            type: 'item.completed',
+            item: {
+                kind: 'tool',
+                id: state.reviewItemId,
+                name: 'enteredReviewMode',
+                toolKind: 'task',
+                title: 'Review',
+                status: outcome.error !== undefined ? 'failed' : 'completed',
+            },
+        });
+    }
+    const completed = {
+        type: 'turn.completed',
+        turnId,
+        stopReason: outcome.stopReason,
+    };
+    if (turnId === state.currentTurnId && state.pendingTurnUsage !== null) {
+        completed.usage = state.pendingTurnUsage;
+    }
+    events.push(completed);
+    return {
+        events,
+        state: closesActiveTurn
+            ? { ...state, turnSeq, currentTurnId: null, pendingTurnUsage: null, reviewItemId: null }
+            : { ...state, turnSeq },
+    };
+}
+// ---- plan -------------------------------------------------------------------
+/**
+ * `turn/plan/updated` → the plan dock. This is the ONLY channel codex's
+ * `update_plan` tool reaches the client on: the app-server `ThreadItem` union
+ * has no todo/`todoList` variant, so the plan is a turn-level notification
+ * rather than an item (verified against
+ * `app-server-protocol/schema/typescript/v2/TurnPlanUpdatedNotification.ts`).
+ *
+ * Full replacement: `plan` carries the entire list on every notification and
+ * the steps have no wire ids, so the snapshot IS the plan — no accumulation
+ * (contrast the claude mapper's id-keyed TaskCreate/TaskUpdate fold).
+ *
+ * `explanation` (the model's prose rationale) is deliberately dropped: the dock
+ * renders entries only, and PlanEntry has nowhere to put it.
+ */
+function mapTurnPlanUpdated(params, state) {
+    const entries = turnPlanEntries(params.plan);
+    if (!entries)
+        return { events: [], state };
+    return {
+        events: [{ type: 'plan.updated', entries }],
+        state: state.planFromNotification ? state : { ...state, planFromNotification: true },
+    };
+}
+/** `plan: [{step, status}]` → plan entries. An EMPTY array is a legitimate
+ *  snapshot (the agent cleared its plan) and clears the dock; anything else that
+ *  yields no entries — a non-array, or rows we could not read a step out of —
+ *  is malformed and maps to zero events, so a garbled frame cannot wipe a good
+ *  plan. The distinction matters: "the agent has no steps" and "we failed to
+ *  parse the steps" look identical downstream once they are both `[]`. */
+function turnPlanEntries(plan) {
+    if (!Array.isArray(plan))
+        return undefined;
+    const entries = [];
+    for (const step of plan) {
+        if (!isRecord(step))
+            continue;
+        const content = str(step.step);
+        if (content === undefined)
+            continue;
+        entries.push({ content, status: turnPlanStatus(step.status) });
+    }
+    if (plan.length > 0 && entries.length === 0)
+        return undefined;
+    return entries;
+}
+/** `TurnPlanStepStatus` is camelCase ON THE APP-SERVER WIRE (`inProgress`) even
+ *  though codex's core protocol type is snake_case — the app-server layer
+ *  re-serializes. Accept both spellings rather than depend on that detail, and
+ *  treat anything unknown as `pending` (a step the agent has not reached). */
+function turnPlanStatus(status) {
+    if (status === 'completed')
+        return 'completed';
+    if (status === 'inProgress' || status === 'in_progress')
+        return 'in_progress';
+    return 'pending';
+}
+function mapItemLifecycle(params, state, eventType) {
+    const raw = isRecord(params.item) ? params.item : undefined;
+    if (!raw || typeof raw.type !== 'string')
+        return { events: [], state };
+    const mapper = ITEM_FAMILY_MAPPERS.get(raw.type) ?? mapIdentifiedItem;
+    return mapper(raw, state, params, eventType, raw.type);
+}
+const ITEM_FAMILY_MAPPERS = new Map([
+    ['todoList', mapPlanItem],
+    ['todo_list', mapPlanItem],
+    ['plan', mapPlanItem],
+    ['userMessage', mapUserMessage],
+]);
+// The user's own message echoed back — the client already rendered what it
+// sent, so it maps to zero events (matching the claude mapper).
+function mapUserMessage(_raw, state) {
+    return { events: [], state };
+}
+function mapIdentifiedItem(raw, state, params, eventType, type) {
+    const id = str(raw.id);
+    if (id === undefined)
+        return { events: [], state };
+    // Review mode is a PAIR of frames describing one span of work — folded into a
+    // single lifecycle before the generic arm, which knows only one frame at a time.
+    if (type === 'enteredReviewMode' || type === 'exitedReviewMode') {
+        return mapReviewMode(raw, id, type, eventType, state);
+    }
+    // Internal collaboration telemetry is not a user tool. Codex emits one
+    // `subAgentActivity(kind: started)` when it creates a child thread, followed
+    // by `interacted` bookkeeping as control returns between threads.
+    if (type === 'subAgentActivity')
+        return mapSubAgentActivity(raw, id, collabParentItemId(params, state), state);
+    return mapGenericItem(params, raw, id, type, eventType, state);
+}
+// `plan` / `todoList` items never render as items — they ARE the plan
+// (full-replacement semantics on every lifecycle phase, §7.1).
+//
+// `plan` is the plan-MODE item (`{type:'plan', id, text}`, streamed via
+// `item/plan/delta`) — prose, not a checklist, and mutually exclusive with
+// `update_plan` (codex rejects that tool in plan mode). It becomes the single
+// entry the agent is executing.
+//
+// `todoList` is NOT an app-server item type — the v2 `ThreadItem` union has no
+// todo variant, so this arm is dead on the transport cezar spawns. It is kept
+// as cheap tolerance: these types are marked EXPERIMENTAL upstream, codex's
+// exec transport does emit a `todo_list` item, and a stray snapshot is better
+// rendered than dropped. The real plan channel is `turn/plan/updated`.
+//
+// That makes this the SECOND writer of `plan.updated`, so it yields to the
+// first: once the notification has delivered a real checklist, a prose `plan`
+// item must not flatten it back into a single entry. Upstream says the two are
+// mutually exclusive (codex rejects `update_plan` in plan mode) — this does not
+// depend on that holding.
+function mapPlanItem(raw, state) {
+    if (state.planFromNotification)
+        return { events: [], state };
+    const entries = planEntriesOf(raw);
+    if (!entries)
+        return { events: [], state };
+    return { events: [{ type: 'plan.updated', entries }], state };
+}
+function mapGenericItem(params, raw, id, type, eventType, state) {
+    const item = type === 'agentMessage'
+        ? messageItem(raw, id)
+        : type === 'reasoning'
+            ? reasoningItem(raw, id, state)
+            : toolItem(raw, id, type, eventType, state);
+    if (type === 'collabAgentToolCall' || type === 'collabToolCall') {
+        return mapCollabToolCall(raw, id, eventType, state);
+    }
+    const parentItemId = collabParentItemId(params, state);
+    if (parentItemId !== undefined)
+        item.parentItemId = parentItemId;
+    const events = [{ type: eventType, item }];
+    // Track live ids (for delta synthesis) and drop bookkeeping on completion.
+    if (eventType === 'item.completed') {
+        if (!state.knownItems.has(id) && !state.outputs.has(id) && !state.reasonings.has(id)) {
+            return { events, state };
+        }
+        const knownItems = new Set(state.knownItems);
+        knownItems.delete(id);
+        const outputs = new Map(state.outputs);
+        outputs.delete(id);
+        const reasonings = new Map(state.reasonings);
+        reasonings.delete(id);
+        return { events, state: { ...state, knownItems, outputs, reasonings } };
+    }
+    if (state.knownItems.has(id))
+        return { events, state };
+    return { events, state: { ...state, knownItems: new Set(state.knownItems).add(id) } };
+}
+function mapSubAgentActivity(raw, id, parentItemId, state) {
+    const kind = str(raw.kind);
+    const agentThreadId = str(raw.agentThreadId);
+    if (kind === 'completed')
+        return mapSubAgentCompleted(agentThreadId, state);
+    if (kind !== 'started' || state.knownItems.has(id))
+        return { events: [], state };
+    const agentPath = str(raw.agentPath);
+    const agentName = agentPath?.split('/').filter(Boolean).at(-1)?.replaceAll('_', ' ');
+    const display = toolDisplay('Task', agentName ? { description: agentName } : undefined);
+    const task = { itemId: id, ...(agentName ? { prompt: agentName } : {}) };
+    const collabTasks = new Map(state.collabTasks);
+    if (agentThreadId)
+        collabTasks.set(agentThreadId, task);
+    // The child runs in its own thread and may outlive the parent turn (hearsay-tools/cezarion#2431).
+    // A spawn on a child's thread is that child's work: it nests under the child's row and is not
+    // one of the parent's background subagents, though its row still ends on its own completion.
+    const item = {
+        kind: 'tool', id, name: 'spawnAgent', toolKind: 'task', title: display.title, status: 'running',
+        input: { ...(agentPath ? { agentPath } : {}), ...(agentThreadId ? { agentThreadId } : {}) },
+        ...(parentItemId === undefined ? { background: true } : { parentItemId }),
+    };
+    return {
+        events: [{ type: 'item.started', item }],
+        state: {
+            ...state, knownItems: new Set(state.knownItems).add(id), collabTasks,
+            backgroundTasks: new Map(state.backgroundTasks).set(id, item),
+        },
+    };
+}
+/**
+ * A child's end: Codex reports it on the PARENT thread as `subAgentActivity(kind: completed)`,
+ * stamped with the parent turn that spawned it, which may have completed long before. It
+ * completes that spawn's background row once, so a repeat emits nothing. A collaboration
+ * tool-call row is left alone: its `wait` call already reports the child's state. Codex 0.164.0
+ * reports no failed or interrupted child here.
+ */
+function mapSubAgentCompleted(agentThreadId, state) {
+    const task = agentThreadId === undefined ? undefined : state.collabTasks.get(agentThreadId);
+    const running = task === undefined ? undefined : state.backgroundTasks.get(task.itemId);
+    if (!task || !running)
+        return { events: [], state };
+    const backgroundTasks = new Map(state.backgroundTasks);
+    backgroundTasks.delete(task.itemId);
+    return { events: [{ type: 'item.completed', item: { ...running, status: 'completed' } }], state: { ...state, backgroundTasks } };
+}
+/** A spawn creates one task row; later send/wait/resume/close calls update the
+ * same row through receiver-thread correlation instead of creating duplicates. */
+function mapCollabToolCall(raw, id, eventType, state) {
+    const operation = str(raw.tool) ?? str(raw.operation);
+    const receiverIds = stringArray(raw.receiverThreadIds ?? raw.receiver_thread_ids);
+    const isSpawn = operation === 'spawnAgent' || operation === 'spawn_agent';
+    if (isSpawn) {
+        const prompt = str(raw.prompt);
+        const model = str(raw.model);
+        const task = { itemId: id, ...(prompt ? { prompt } : {}), ...(model ? { model } : {}) };
+        let collabTasks = state.collabTasks;
+        if (receiverIds.length > 0) {
+            const next = new Map(state.collabTasks);
+            for (const threadId of receiverIds)
+                next.set(threadId, task);
+            collabTasks = next;
+        }
+        const status = collabStatus(raw, receiverIds, eventType);
+        const mappedType = eventType === 'item.started'
+            ? eventType
+            : status === 'running' || status === 'pending' ? 'item.updated' : 'item.completed';
+        return {
+            events: [{ type: mappedType, item: collabTaskItem(task, status) }],
+            state: { ...state, collabTasks },
+        };
+    }
+    const tasks = new Map();
+    for (const threadId of receiverIds) {
+        const task = state.collabTasks.get(threadId);
+        if (task)
+            tasks.set(task.itemId, task);
+    }
+    if (tasks.size === 0)
+        return { events: [], state };
+    const status = collabStatus(raw, receiverIds, eventType);
+    const mappedType = status === 'running' || status === 'pending' ? 'item.updated' : 'item.completed';
+    return {
+        events: [...tasks.values()].map((task) => ({ type: mappedType, item: collabTaskItem(task, status) })),
+        state,
+    };
+}
+function collabTaskItem(task, status) {
+    const display = toolDisplay('Task', task.prompt ? { description: task.prompt } : undefined);
+    const input = {};
+    if (task.prompt)
+        input.prompt = task.prompt;
+    if (task.model)
+        input.model = task.model;
+    return {
+        kind: 'tool', id: task.itemId, name: 'spawnAgent', toolKind: 'task', title: display.title, status,
+        ...(Object.keys(input).length > 0 ? { input } : {}),
+    };
+}
+function collabStatus(raw, receiverIds, eventType) {
+    const states = isRecord(raw.agentsStates) ? raw.agentsStates
+        : isRecord(raw.agents_states) ? raw.agents_states : undefined;
+    const statuses = receiverIds
+        .map((threadId) => (states && isRecord(states[threadId]) ? states[threadId].status : undefined))
+        .filter((status) => typeof status === 'string');
+    if (statuses.some((status) => status === 'errored' || status === 'notFound' || status === 'not_found'))
+        return 'failed';
+    if (statuses.some((status) => status === 'interrupted'))
+        return 'declined';
+    if (statuses.length > 0 && statuses.every((status) => status === 'completed' || status === 'shutdown'))
+        return 'completed';
+    if (statuses.some((status) => status === 'running' || status === 'pendingInit' || status === 'pending_init'))
+        return 'running';
+    return toolStatus(raw, eventType);
+}
+/**
+ * §7.1: review-mode items → tool(kind task) — but ONE item for the pair, not two.
+ *
+ * `enteredReviewMode` opens the item (`running`); `exitedReviewMode` completes
+ * **that same id**, so the cockpit sees one "Review" span with a lifecycle instead
+ * of two childless task items that would read as two sub-agents (spec
+ * `.ai/specs/2026-07-20-grouped-subagent-display.md` §"Codex-mapper fix", #474).
+ *
+ * The fallback matters: an exit with no open item — a resumed thread, a replay that
+ * starts mid-review — still maps to its own completed item, so no frame is dropped.
+ */
+function mapReviewMode(raw, id, type, eventType, state) {
+    const reviewItem = (itemId, name, status) => ({
+        kind: 'tool',
+        id: itemId,
+        name,
+        toolKind: 'task',
+        // One stable title across the lifecycle: the row must not rename itself on exit.
+        title: 'Review',
+        status,
+    });
+    if (type === 'enteredReviewMode') {
+        const status = toolStatus(raw, eventType);
+        const events = [];
+        // A second entered frame with no intervening exit displaces the open span. Settle the
+        // displaced item rather than leaking a permanently `running` row — the same rule the
+        // opencode mapper's subtask slot follows.
+        if (state.reviewItemId !== null && state.reviewItemId !== id) {
+            events.push({
+                type: 'item.completed',
+                item: reviewItem(state.reviewItemId, 'enteredReviewMode', 'completed'),
+            });
+        }
+        events.push({ type: eventType, item: reviewItem(id, type, status) });
+        // Latch on the RESOLVED status, not the event phase: an entered frame that already
+        // carries a terminal wire status closes the span whichever lifecycle phase it arrived in,
+        // and one that is still in progress stays open even on an `item/completed` frame.
+        const settled = status !== 'running' && status !== 'pending';
+        return { events, state: { ...state, reviewItemId: settled ? null : id } };
+    }
+    const openId = state.reviewItemId;
+    if (openId === null) {
+        // Unpaired exit — today's shape, under the exit frame's own id.
+        return {
+            events: [{ type: 'item.completed', item: reviewItem(id, type, toolStatus(raw, 'item.completed')) }],
+            state,
+        };
+    }
+    return {
+        events: [
+            {
+                type: 'item.completed',
+                // The item was introduced by the entered frame, so it keeps that identity.
+                item: reviewItem(openId, 'enteredReviewMode', toolStatus(raw, 'item.completed')),
+            },
+        ],
+        state: { ...state, reviewItemId: null },
+    };
+}
+/** `agentMessage` → message item; `phase` commentary|final_answer→'commentary'|'final'. */
+function messageItem(raw, id) {
+    const item = {
+        kind: 'message',
+        id,
+        role: 'assistant',
+        text: typeof raw.text === 'string' ? raw.text : '',
+    };
+    if (raw.phase === 'commentary')
+        item.phase = 'commentary';
+    else if (raw.phase === 'final_answer')
+        item.phase = 'final';
+    return item;
+}
+/** `reasoning` → reasoning item. Precedence, most authoritative first:
+ *  wire `content` → streamed raw chain of thought → the fuller of the wire
+ *  `summary` and the streamed summary.
+ *
+ *  The accumulators matter on `item.completed`: deltas never reach disk, so a
+ *  completed snapshot without `content` would otherwise persist the short
+ *  summary (or nothing) and the row would read back empty after a reload
+ *  (#528). They are consulted on `item.started` too — a delta can outrun its
+ *  `item/started`, and re-emitting an empty snapshot would blank the row the
+ *  synthesized item already filled.
+ *
+ *  Summary picks the LONGER of the two sources rather than preferring the
+ *  stream: a mapper attached mid-turn, or any dropped frame, leaves a partial
+ *  accumulator that must not overwrite a complete `summary` from the wire. */
+function reasoningItem(raw, id, state) {
+    const streamed = state.reasonings.get(id);
+    // app-server v2 snapshots use arrays for both fields. Deltas remain scalar
+    // strings, and older recorded transcripts may still contain scalar snapshots,
+    // so accept both without weakening the untrusted-wire boundary.
+    const summary = longer(reasoningSnapshotText(raw.summary), str(streamed?.summary));
+    return {
+        kind: 'reasoning',
+        id,
+        text: reasoningSnapshotText(raw.content) ?? str(streamed?.text) ?? summary ?? '',
+    };
+}
+/** Join app-server reasoning parts without flattening their boundaries. Scalar
+ *  strings remain accepted for replay compatibility with older transcripts. */
+function reasoningSnapshotText(value) {
+    if (typeof value === 'string')
+        return str(value);
+    if (!Array.isArray(value))
+        return undefined;
+    const parts = value.filter((part) => typeof part === 'string' && part !== '');
+    return parts.length > 0 ? parts.join('\n') : undefined;
+}
+/** The longer of two optional strings — neither present yields undefined. */
+function longer(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return b.length > a.length ? b : a;
+}
+/** The §7.1 status map — the wire word wins; an item without one derives its
+ *  status from the lifecycle phase it arrived in. */
+export const STATUS_MAP = {
+    inProgress: 'running',
+    in_progress: 'running',
+    completed: 'completed',
+    failed: 'failed',
+    declined: 'declined',
+};
+function toolStatus(raw, eventType) {
+    const mapped = typeof raw.status === 'string' ? STATUS_MAP[raw.status] : undefined;
+    return mapped ?? (eventType === 'item.completed' ? 'completed' : 'running');
+}
+function toolItem(raw, id, type, eventType, state) {
+    const status = toolStatus(raw, eventType);
+    let item;
+    switch (type) {
+        case 'commandExecution': {
+            const display = toolDisplay('commandExecution', raw);
+            item = { kind: 'tool', id, name: type, toolKind: display.toolKind, title: display.title, status };
+            if (raw.command !== undefined)
+                item.input = { command: raw.command };
+            // Wire output wins; else the final snapshot carries what outputDelta streamed.
+            const output = str(raw.aggregatedOutput) ??
+                str(raw.output) ??
+                (eventType === 'item.completed' ? state.outputs.get(id) : undefined);
+            if (output !== undefined)
+                item.output = output;
+            const exitCode = num(raw.exitCode);
+            if (exitCode !== undefined)
+                item.exitCode = exitCode;
+            break;
+        }
+        case 'fileChange': {
+            const display = toolDisplay('fileChange', raw);
+            item = { kind: 'tool', id, name: type, toolKind: display.toolKind, title: display.title, status };
+            const artifacts = changeArtifacts(raw.changes);
+            if (artifacts) {
+                item.diffs = artifacts.diffs;
+                item.locations = artifacts.locations;
+            }
+            break;
+        }
+        case 'mcpToolCall': {
+            const server = str(raw.server);
+            const tool = str(raw.tool);
+            const display = toolDisplay('mcpToolCall', raw);
+            item = {
+                kind: 'tool',
+                id,
+                // §7.1: the item is named after what it called, `server.tool`.
+                name: server && tool ? `${server}.${tool}` : type,
+                toolKind: display.toolKind,
+                title: display.title,
+                status,
+            };
+            if (raw.arguments !== undefined)
+                item.input = raw.arguments;
+            const result = raw.result;
+            if (typeof result === 'string')
+                item.output = result;
+            else if (result !== undefined)
+                item.output = safeStringify(result);
+            break;
+        }
+        case 'webSearch': {
+            const display = toolDisplay('webSearch', raw);
+            item = { kind: 'tool', id, name: type, toolKind: display.toolKind, title: display.title, status };
+            break;
+        }
+        default: {
+            // Unknown item types stay visible as generic tool cards (v1 parity —
+            // a future codex tool must not silently vanish from the thread).
+            const display = toolDisplay(type, raw);
+            item = { kind: 'tool', id, name: type, toolKind: display.toolKind, title: display.title, status, input: raw };
+        }
+    }
+    const error = errorMessage(raw.error);
+    if (error !== undefined)
+        item.error = error;
+    return item;
+}
+/** `fileChange.changes[]` `{path, kind, diff}` → `diffs[]` (unified) + locations. */
+function changeArtifacts(changes) {
+    if (!Array.isArray(changes))
+        return undefined;
+    const diffs = [];
+    const locations = [];
+    for (const change of changes) {
+        if (!isRecord(change) || typeof change.path !== 'string' || change.path === '')
+            continue;
+        // Codex sends unified diffs only — the old text is unknown, not "empty".
+        const diff = { path: change.path, oldText: null };
+        const unified = str(change.diff);
+        if (unified !== undefined)
+            diff.unified = unified;
+        diffs.push(diff);
+        locations.push({ path: change.path });
+    }
+    if (diffs.length === 0)
+        return undefined;
+    return { diffs, locations };
+}
+/** `todoList` items `{text, completed}` (and plan step arrays) → plan entries;
+ *  a text-only `plan` item becomes the single entry the agent is executing. */
+function planEntriesOf(raw) {
+    const list = Array.isArray(raw.items) ? raw.items : Array.isArray(raw.plan) ? raw.plan : undefined;
+    if (list) {
+        const entries = [];
+        for (const entry of list) {
+            if (!isRecord(entry))
+                continue;
+            const content = str(entry.text) ?? str(entry.step) ?? str(entry.content);
+            if (content === undefined)
+                continue;
+            if (typeof entry.completed === 'boolean') {
+                entries.push({ content, status: entry.completed ? 'completed' : 'pending' });
+            }
+            else if (entry.status === 'pending' || entry.status === 'completed') {
+                entries.push({ content, status: entry.status });
+            }
+            else if (entry.status === 'inProgress' || entry.status === 'in_progress') {
+                entries.push({ content, status: 'in_progress' });
+            }
+            else {
+                entries.push({ content, status: 'pending' });
+            }
+        }
+        return entries;
+    }
+    const text = str(raw.text);
+    if (text === undefined)
+        return undefined;
+    return [{ content: text, status: 'in_progress' }];
+}
+// ---- streaming deltas -------------------------------------------------------
+/** Minimal item synthesized when a delta outruns its `item/started` — gives
+ *  consumers a valid target to upsert; the completed snapshot reconciles. */
+function synthesizedItem(itemId, field) {
+    if (field === 'text')
+        return { kind: 'message', id: itemId, role: 'assistant', text: '' };
+    if (field === 'reasoning')
+        return { kind: 'reasoning', id: itemId, text: '' };
+    const display = toolDisplay('commandExecution');
+    return { kind: 'tool', id: itemId, name: 'commandExecution', toolKind: display.toolKind, title: display.title, status: 'running' };
+}
+function mapDelta(params, state, field, 
+/** Which reasoning stream fed this delta — see `ReasoningAccumulator`. */
+reasoningChannel = 'text') {
+    const itemId = str(params.itemId);
+    const delta = typeof params.delta === 'string' ? params.delta : '';
+    if (itemId === undefined || delta === '')
+        return { events: [], state };
+    const events = [];
+    let knownItems = state.knownItems;
+    if (!knownItems.has(itemId)) {
+        const item = synthesizedItem(itemId, field);
+        const parentItemId = collabParentItemId(params, state);
+        if (parentItemId !== undefined)
+            item.parentItemId = parentItemId;
+        events.push({ type: 'item.started', item });
+        knownItems = new Set(knownItems).add(itemId);
+    }
+    events.push({ type: 'item.delta', itemId, field, delta });
+    let outputs = state.outputs;
+    if (field === 'output') {
+        const next = new Map(state.outputs);
+        next.set(itemId, (next.get(itemId) ?? '') + delta);
+        outputs = next;
+    }
+    let reasonings = state.reasonings;
+    if (field === 'reasoning') {
+        const next = new Map(state.reasonings);
+        const prev = next.get(itemId) ?? { text: '', summary: '' };
+        next.set(itemId, reasoningChannel === 'text'
+            ? { ...prev, text: prev.text + delta }
+            : { ...prev, summary: prev.summary + delta });
+        reasonings = next;
+    }
+    return { events, state: { ...state, knownItems, outputs, reasonings } };
+}
+// ---- telemetry ---------------------------------------------------------------
+/** `thread/tokenUsage/updated` → usage.updated. Raw CUMULATIVE totals from
+ *  `tokenUsage.total`; codex reports no USD cost, so none is ever fabricated. */
+function mapTokenUsage(params, state) {
+    if (!isRecord(params.tokenUsage))
+        return { events: [], state };
+    const tokenUsage = params.tokenUsage;
+    const total = isRecord(tokenUsage.total) ? tokenUsage.total : undefined;
+    if (!total)
+        return { events: [], state };
+    const usage = codexUsage(total);
+    if (usage === undefined)
+        return { events: [], state };
+    const contextWindow = num(tokenUsage.modelContextWindow);
+    if (contextWindow !== undefined)
+        usage.contextWindow = contextWindow;
+    const last = isRecord(tokenUsage.last) ? codexUsage(tokenUsage.last) : undefined;
+    const nextState = state.currentTurnId !== null && last !== undefined ? { ...state, pendingTurnUsage: last } : state;
+    return { events: [{ type: 'usage.updated', usage }], state: nextState };
+}
+function codexUsage(raw) {
+    const input = nonNegative(raw.inputTokens);
+    const output = nonNegative(raw.outputTokens);
+    if (input === undefined || output === undefined)
+        return undefined;
+    const total = nonNegative(raw.totalTokens) ?? input + output;
+    const usage = { input, output, total };
+    const cacheRead = nonNegative(raw.cachedInputTokens);
+    const reasoning = nonNegative(raw.reasoningOutputTokens);
+    if (cacheRead !== undefined)
+        usage.cacheRead = cacheRead;
+    if (reasoning !== undefined)
+        usage.reasoning = reasoning;
+    return usage;
+}
+// ---- tiny guards --------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nonNegative(value) {
+    const parsed = num(value);
+    return parsed !== undefined && parsed >= 0 ? parsed : undefined;
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string' && entry !== '') : [];
+}
+function turnIdOf(params) {
+    const turn = isRecord(params.turn) ? params.turn : undefined;
+    return (turn && str(turn.id)) ?? str(params.turnId);
+}
+function errorMessage(error) {
+    if (typeof error === 'string')
+        return str(error);
+    if (isRecord(error))
+        return str(error.message);
+    return undefined;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=codex-ui-mapper.js.map