Report unpriced spend honestly, and parse the rest of Codex's items

packages/sdk/src/cloud-mirror-step.ts

@@ -114,6 +114,18 @@ export interface FinalStep {
   model?: string;
   tokensInput?: number;
   tokensOutput?: number;
+  /**
+   * True when tokens were counted but nobody priced them.
+   *
+   * The kernel already records this (`run-state.ts`'s `Spend`), and
+   * `flows status` already prints `(unmetered)` from it. Without it on the
+   * wire, Cloud cannot tell a step that genuinely cost nothing — a
+   * deterministic `echo` — from one that spent real money against an unpriced
+   * model: both arrive as an absent `costUsd` and render blank. Codex is the
+   * everyday case, because it selects its own model and never reports it, so
+   * `MODEL_PRICING` has nothing to match (`model-pricing.ts` says so outright).
+   */
+  costUnmetered?: true;
   costUsd?: number;
   error?: string;
   detail?: Record<string, unknown>;
@@ -314,6 +326,7 @@ interface AttemptRecord {
   tokensIn?: number;
   tokensOut?: number;
   costUsd?: number;
+  costUnmetered?: boolean;
 }
 
 /**
@@ -346,6 +359,7 @@ function attemptsByStep(events: readonly JournalEvent[]): Map<string, AttemptRec
       ...(typeof result?.['total_cost_usd'] === 'number' && Number.isFinite(result['total_cost_usd'])
         && result['total_cost_usd'] >= 0
         ? { costUsd: result['total_cost_usd'] as number } : {}),
+      ...(budget['dollars_unmetered'] === true ? { costUnmetered: true } : {}),
     });
     byStep.set(event.step_id, entries);
   }
@@ -374,6 +388,23 @@ function finalStep(
   // Cloud totals these rows for the run's spend — so a retried agent's earlier
   // charges simply vanished from the run.
   const spentUsd = attempts.reduce((total, entry) => total + (entry.costUsd ?? 0), 0);
+  const priced = attempts.some(entry => entry.costUsd !== undefined);
+  /**
+   * Any unpriced attempt makes the step's cost unknown, even when another
+   * attempt reported one.
+   *
+   * The first cut suppressed the flag whenever `spentUsd > 0`, which published
+   * a partial subtotal as though it were the whole cost: a step that spent
+   * $0.02 on attempt 1 and an unpriced amount on attempt 2 reported exactly
+   * $0.02. The two facts are not exclusive — `costUsd` is then a *lower bound*
+   * and the flag says so. `run-state.ts`'s `addSpend` keeps them together for
+   * the same reason.
+   *
+   * Presence, not a positive sum: an attempt reporting `total_cost_usd: 0` did
+   * produce a price, and testing `spentUsd === 0` would have called that step
+   * unpriced.
+   */
+  const unmetered = attempts.some(entry => entry.costUnmetered === true);
   const detail = stepDetail(attempts, env);
   const verification = step.last_attempt?.verification ?? null;
   // What the step said about itself. A gate's verdict detail is the nearest
@@ -407,7 +438,8 @@ function finalStep(
     ...(model === undefined ? {} : { model }),
     ...(tokensIn > 0 ? { tokensInput: Math.min(tokensIn, MAX_INT32) } : {}),
     ...(tokensOut > 0 ? { tokensOutput: Math.min(tokensOut, MAX_INT32) } : {}),
-    ...(spentUsd > 0 ? { costUsd: spentUsd } : {}),
+    ...(priced ? { costUsd: spentUsd } : {}),
+    ...(unmetered ? { costUnmetered: true as const } : {}),
     ...(error === undefined ? {} : { error }),
     ...(detail.detail === undefined ? {} : { detail: detail.detail }),
     ...(detail.truncated === undefined ? {} : { detailTruncated: detail.truncated }),

packages/sdk/src/cloud-transcript-codex.ts

@@ -32,12 +32,22 @@ export const CODEX_FRAME_TYPES: ReadonlySet<string> = new Set([
 /** Item types whose lifecycles are matched and whose fields are read. */
 const SUPPORTED_ITEMS: ReadonlySet<string> = new Set([
   'agent_message', 'reasoning', 'command_execution', 'file_change', 'mcp_tool_call', 'error',
+  // The rest of Codex's `ThreadItemDetails` union
+  // (codex-rs/exec/src/exec_events.rs). Without these three, a real agent turn
+  // reported them as bare `unknown` placeholders naming a type and a size —
+  // honest, but useless: `todo_list` in particular updates continuously
+  // through a turn, so it was the most frequent thing a reader could not read.
+  'web_search', 'todo_list', 'collab_tool_call',
 ]);
 
 const ITEM_FRAMES: ReadonlySet<string> = new Set(['item.started', 'item.updated', 'item.completed']);
 
 /** Calls are numbered; an `apply_patch` is file activity, not a call. */
-const NUMBERED_ITEMS: ReadonlySet<string> = new Set(['command_execution', 'mcp_tool_call']);
+const NUMBERED_ITEMS: ReadonlySet<string> = new Set([
+  'command_execution', 'mcp_tool_call', 'web_search', 'collab_tool_call',
+]);
+/** Todo entries listed per snapshot; a longer plan is counted, not printed. */
+const TODO_MAX_ITEMS = 12;
 
 interface Lifecycle {
   snapshots: Array<Record<string, unknown>>;
@@ -246,6 +256,65 @@ function mcpEntry(item: Record<string, unknown>, complete: boolean, context: Con
     });
 }
 
+/**
+ * `web_search`: a query and what was done with it (`WebSearchItem` — `query`,
+ * `action`, optional structured `results`). Rendered as a call rather than
+ * prose, so a reader sees the search in sequence beside the commands.
+ */
+function webSearchEntry(item: Record<string, unknown>, complete: boolean, context: Context,
+  seq: number): TranscriptEntry | null {
+  const query = str(item['query']);
+  if (query === null) return null;
+  const action = isRecord(item['action']) ? str(item['action']['type']) : str(item['action']);
+  const results = item['results'];
+  const count = Array.isArray(results) ? results.length : null;
+  return tool('web_search', bounded(query, context.clean),
+    count === null ? null : JSON.stringify(results).length, false, {
+      seq, status: action === null ? null : bounded(action, context.clean, 40),
+      exit_code: null,
+      output_excerpt: count === null ? null : `${count} result${count === 1 ? '' : 's'}`,
+      output_truncated: false, complete, error: null,
+    });
+}
+
+/**
+ * `collab_tool_call`: Codex driving other Codex threads (`CollabToolCallItem` —
+ * `tool`, `sender_thread_id`, `receiver_thread_ids`, `agents_states`).
+ *
+ * The per-agent states are reduced to a count per status rather than listed:
+ * `agents_states` is a map keyed by agent id, and ids are not something a
+ * transcript reader can act on.
+ */
+function collabEntry(item: Record<string, unknown>, complete: boolean, context: Context,
+  seq: number): TranscriptEntry | null {
+  const name = str(item['tool']);
+  if (name === null) return null;
+  const receivers = Array.isArray(item['receiver_thread_ids']) ? item['receiver_thread_ids'].length : 0;
+  const states = isRecord(item['agents_states']) ? item['agents_states'] : null;
+  const byStatus = new Map<string, number>();
+  if (states !== null) {
+    for (const state of Object.values(states)) {
+      const status = isRecord(state) ? str(state['status']) : null;
+      if (status !== null) byStatus.set(status, (byStatus.get(status) ?? 0) + 1);
+    }
+  }
+  // Redacted like every neighbouring field. A status is provider text, not a
+  // closed vocabulary this module controls, and it was the one string here that
+  // reached the page without passing the redactor.
+  const summary = bounded(
+    [...byStatus.entries()].sort().map(([status, n]) => `${n} ${status}`).join(', '),
+    context.clean,
+  );
+  const status = str(item['status']);
+  return tool('collab_tool_call',
+    bounded(`${name}${receivers > 0 ? ` → ${receivers} thread${receivers === 1 ? '' : 's'}` : ''}`, context.clean),
+    null, status === 'failed', {
+      seq, status: status === null ? null : bounded(status, context.clean, 40),
+      exit_code: null, output_excerpt: summary.length === 0 ? null : summary,
+      output_truncated: false, complete, error: null,
+    });
+}
+
 function fileChangeEntry(item: Record<string, unknown>, complete: boolean, context: Context): TranscriptEntry | null {
   const raw = item['changes'];
   if (!Array.isArray(raw)) return null;
@@ -288,12 +357,35 @@ function itemEntries(item: Record<string, unknown>, complete: boolean, context:
     if (message === null) return [placeholder(context, itemType)];
     return [{ kind: 'error', source: 'item', message: bounded(message, context.clean, ERROR_MAX_CHARS) }];
   }
-  if (itemType === 'command_execution' || itemType === 'mcp_tool_call') {
+  if (itemType === 'todo_list') {
+    // A plan, not a call: it carries no status and earns no sequence number.
+    // `items[]` is `{text, completed}` (TodoListItem/TodoItem).
+    const items = Array.isArray(item['items']) ? item['items'] : null;
+    if (items === null) return [placeholder(context, itemType)];
+    const listed = items.slice(0, TODO_MAX_ITEMS).flatMap((entry) => {
+      const todo = isRecord(entry) ? entry : undefined;
+      const text = str(todo?.['text']);
+      return text === null ? [] : [{ text: context.clean(text), done: todo!['completed'] === true }];
+    });
+    // Counted across the whole plan; only the *display* is capped. Counting the
+    // prefix rendered a 13-item plan whose last item was done as `0/13`, which
+    // is exactly backwards from "the rest are counted, not printed".
+    const done = items.filter(entry => isRecord(entry) && entry['completed'] === true).length;
+    return [{
+      kind: 'todo', total: items.length, done,
+      items: listed, ...(items.length > listed.length ? { omitted: items.length - listed.length } : {}),
+      ...(complete ? {} : { complete: false }),
+    }];
+  }
+  if (itemType === 'command_execution' || itemType === 'mcp_tool_call'
+    || itemType === 'web_search' || itemType === 'collab_tool_call') {
     // The number is only spent on a call this module could actually read, so a
     // malformed item leaves no gap in the sequence.
     const seq = context.state.seq + 1;
-    const entry = itemType === 'command_execution'
-      ? commandEntry(item, complete, context, seq) : mcpEntry(item, complete, context, seq);
+    const entry = itemType === 'command_execution' ? commandEntry(item, complete, context, seq)
+      : itemType === 'mcp_tool_call' ? mcpEntry(item, complete, context, seq)
+      : itemType === 'web_search' ? webSearchEntry(item, complete, context, seq)
+      : collabEntry(item, complete, context, seq);
     if (entry === null) return [placeholder(context, itemType)];
     context.state.seq = seq;
     return [entry];

packages/sdk/src/cloud-transcript-types.ts

@@ -138,6 +138,22 @@ export interface TranscriptResult {
   cache_creation: number | null;
 }
 
+/**
+ * Codex's running to-do list (`TodoListItem`). A plan, not a call: it carries
+ * no status and takes no sequence number, and it updates repeatedly through a
+ * turn — which is why leaving it unparsed was the most visible gap.
+ */
+export interface TranscriptTodo {
+  kind: 'todo';
+  total: number;
+  done: number;
+  items: Array<{ text: string; done: boolean }>;
+  /** Entries past the per-snapshot cap: counted, never printed. */
+  omitted?: number;
+  /** False when read off a snapshot that never completed. */
+  complete?: boolean;
+}
+
 export interface TranscriptUnknown {
   kind: 'unknown';
   type: string;
@@ -152,7 +168,8 @@ export interface TranscriptUnparsed {
 export type TranscriptEntry =
   | TranscriptAttempt | TranscriptAttemptOmitted | TranscriptInit | TranscriptMessage
   | TranscriptThinking | TranscriptTool | TranscriptFileChange | TranscriptThread
-  | TranscriptTurn | TranscriptError | TranscriptResult | TranscriptUnknown | TranscriptUnparsed;
+  | TranscriptTurn | TranscriptError | TranscriptResult | TranscriptTodo
+  | TranscriptUnknown | TranscriptUnparsed;
 
 export interface ParsedTranscript {
   entries: TranscriptEntry[];

packages/sdk/src/cloud-transcript.ts

@@ -34,7 +34,7 @@ import { redact } from './redact.js';
 export type {
   ParsedTranscript, TranscriptEntry, TranscriptAttempt, TranscriptAttemptOmitted, TranscriptError,
   TranscriptFileChange, TranscriptInit, TranscriptMessage, TranscriptResult, TranscriptThinking,
-  TranscriptThread, TranscriptTool, TranscriptToolCodex, TranscriptTurn, TranscriptUnknown,
+  TranscriptThread, TranscriptTodo, TranscriptTool, TranscriptToolCodex, TranscriptTurn, TranscriptUnknown,
   TranscriptUnparsed,
 } from './cloud-transcript-types.js';
 
@@ -297,6 +297,14 @@ export function renderAgentTranscript(parsed: ParsedTranscript): string[] {
       case 'thinking':
         lines.push(`  thinking  ${thousands(entry.chars)} chars (not shown)`);
         break;
+      case 'todo': {
+        // The plan the agent is working to, as it stood at this snapshot.
+        const progress = `${entry.done}/${entry.total}`;
+        lines.push(`  plan  ${progress}${entry.complete === false ? ' (in progress)' : ''}`);
+        for (const todo of entry.items) lines.push(`    ${todo.done ? '✓' : '·'} ${safe(todo.text)}`);
+        if (entry.omitted !== undefined) lines.push(`    …${entry.omitted} more`);
+        break;
+      }
       case 'tool': {
         const size = entry.is_error ? 'ERROR'
           : entry.result_chars === null ? 'no result' : `${thousands(entry.result_chars)} chars`;

packages/sdk/tests/cloud-mirror-step.test.ts

@@ -196,6 +196,111 @@ describe('mirrorJournal', () => {
   });
 });
 
+/**
+ * The kernel already records `dollars_unmetered` and `flows status` already
+ * prints `(unmetered)` from it. The mirror dropped it, so Cloud could not tell
+ * a step that genuinely cost nothing from one that spent real money against an
+ * unpriced model — both arrived as an absent `costUsd`. Codex is the everyday
+ * case: it picks its own model and never reports it, so `MODEL_PRICING` has
+ * nothing to match.
+ */
+describe('unpriced spend', () => {
+  function codexStep(budget: Record<string, unknown>, usage?: Record<string, unknown>): JournalEvent[] {
+    seq = 0;
+    return [
+      entry({
+        entry_type: 'run.spawned',
+        payload: { spec: { name: 'codex', steps: [{ id: 'ask', type: 'agent', after: [] }] } },
+      }),
+      entry({ entry_type: 'step.attempt.started', step_id: 'ask', attempt: 1, payload: {} }),
+      entry({
+        entry_type: 'step.completed',
+        step_id: 'ask',
+        attempt: 1,
+        payload: {
+          completionReason: 'success',
+          disposition: 'step_done',
+          budget,
+          trajectory_tail: { transcript: { result: usage === undefined ? {} : { usage } } },
+        },
+      }),
+    ];
+  }
+
+  it('marks a step unmetered when tokens were counted and nobody priced them', () => {
+    const [step] = mirrorJournal('01RUN', codexStep({
+      tokens_in: 13078, tokens_out: 8, dollars: '0', dollars_unmetered: true,
+    }), 1_700_000_010_000, {}).finals;
+
+    expect(step).toMatchObject({ tokensInput: 13078, tokensOutput: 8, costUnmetered: true });
+    // Never a fabricated zero: an absent price is absent, and said so.
+    expect(step).not.toHaveProperty('costUsd');
+  });
+
+  it('does not mark a genuinely free step unmetered', () => {
+    const [step] = mirrorJournal('01RUN', codexStep({
+      tokens_in: 0, tokens_out: 0, dollars: '0', dollars_unmetered: false,
+    }), 1_700_000_010_000, {}).finals;
+
+    expect(step).not.toHaveProperty('costUnmetered');
+    expect(step).not.toHaveProperty('costUsd');
+  });
+
+  /**
+   * The two facts are not exclusive. A step priced on one attempt and unpriced
+   * on another has a cost that is *at least* the known figure — the first cut
+   * suppressed the flag whenever the sum was positive and published that
+   * subtotal as the whole cost.
+   */
+  it('keeps the known figure and the unknown marker together', () => {
+    const events = codexStep({ tokens_in: 1, tokens_out: 1, dollars: '0', dollars_unmetered: true });
+    (events[2]!.payload as Record<string, unknown>)['trajectory_tail'] = {
+      transcript: { result: { total_cost_usd: 0.004 } },
+    };
+    const [step] = mirrorJournal('01RUN', events, 1_700_000_010_000, {}).finals;
+
+    // costUsd is a lower bound, and costUnmetered says so.
+    expect(step).toMatchObject({ costUsd: 0.004, costUnmetered: true });
+  });
+
+  /**
+   * Presence of a price, not a positive sum: an attempt reporting
+   * `total_cost_usd: 0` did produce a price, and testing `spentUsd === 0` would
+   * have reported that step as having none.
+   */
+  it('treats a reported zero as a price, not as absent', () => {
+    const events = codexStep({ tokens_in: 1, tokens_out: 1, dollars: '0', dollars_unmetered: false });
+    (events[2]!.payload as Record<string, unknown>)['trajectory_tail'] = {
+      transcript: { result: { total_cost_usd: 0 } },
+    };
+    const [step] = mirrorJournal('01RUN', events, 1_700_000_010_000, {}).finals;
+
+    expect(step!.costUsd).toBe(0);
+    expect(step).not.toHaveProperty('costUnmetered');
+  });
+
+  /**
+   * `reasoning_output_tokens` is a SUBSET of `output_tokens` — Codex's own
+   * `blended_total()` is `non_cached_input + output_tokens` and nothing in its
+   * protocol adds reasoning to output. Metered output must therefore be the
+   * journal's `tokens_out` verbatim, never a sum with reasoning added, which
+   * would inflate it and, through `maxDollars`, the budget ceiling itself.
+   *
+   * The breakdown is not carried here: the journal's transcript digest does not
+   * record it, so there was nothing to read. The run page reads it off Codex's
+   * own `turn.completed` frame instead.
+   */
+  it('reports metered output verbatim, never summed with reasoning', () => {
+    const [step] = mirrorJournal('01RUN', codexStep(
+      { tokens_in: 13078, tokens_out: 900, dollars: '0', dollars_unmetered: true },
+      { input_tokens: 13078, output_tokens: 900, reasoning_output_tokens: 850 },
+    ), 1_700_000_010_000, {}).finals;
+
+    // 900, not 1,750.
+    expect(step!.tokensOutput).toBe(900);
+  });
+});
+
 describe('the bounds Cloud enforces', () => {
   it('redacts before it clips, so no secret survives as a prefix', () => {
     const secret = 'sk-ant-0123456789abcdefghijklmnopqrstuvwxyz';