One live console to monitor Claude Code and Codex agents across machines, track context and spend, and unblock sessions that need you.
// Codex session files: where they are, which one belongs to a thread, and what one record says.
// Read-only throughout: Codex owns `~/.codex`, its files and its SQLite, so another program may only read them, and nothing
// here opens anything for writing. Record shapes are Codex's own (`codex-rs/history` RolloutLine, `protocol` EventMsg,
// `rollout/src/policy.rs`); unknown fields and record types are ignored.
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import readline from 'node:readline';
import { pipeline } from 'node:stream';
import zlib from 'node:zlib';
import { LIMITS, RESPOND_LIMITS } from '../../server/src/fleet/protocol.js';
import { activityText, clip, clipFreeText, excerpt, promptName, redact, summarizeCall } from './report.js';
import type { Line } from './spool.js';
/** `$CODEX_HOME`, else `~/.codex`, as Codex finds its home (`utils/home-dir/src/lib.rs:13-40`). */
export function codexHome(): string {
const env = process.env.CODEX_HOME?.trim();
return env ? path.resolve(env) : path.join(os.homedir(), '.codex');
}
/**
* The thread id of a rollout file name, compressed or not: `rollout-<YYYY-MM-DDThh-mm-ss>-<thread>[_<rollout>].jsonl[.zst]`
* (`rollout_file_name.rs`; a reverted thread's new file carries a rollout id after its own).
*/
export function threadOfFile(name: string): string | null {
const plain = name.endsWith('.zst') ? name.slice(0, -'.zst'.length) : name;
if (!plain.startsWith('rollout-') || !plain.endsWith('.jsonl')) return null;
const core = plain.slice('rollout-'.length, -'.jsonl'.length);
if (core[19] !== '-') return null;
const id = core.slice(20).split('_')[0] ?? '';
return /^[0-9a-f-]{36}$/i.test(id) ? id : null;
}
export interface RolloutFile {
path: string;
thread: string;
mtimeMs: number;
}
/**
* Every rollout file under `sessions`, plain and compressed. Codex compresses a file cold for 7 days to `.jsonl.zst`, keeping
* its mtime, and writes the plain file again before it appends after a resume; a compressed file is left out while its plain
* sibling exists, as Codex reads them (`rollout/src/compression.rs:99-183, 211-241, 853-975, 1334-1336`).
*/
export function listRollouts(home: string): RolloutFile[] {
const out: RolloutFile[] = [];
const walk = (dir: string, depth: number) => {
let entries: fs.Dirent[];
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
const names = new Set(entries.map((e) => e.name));
for (const e of entries) {
const p = path.join(dir, e.name);
if (e.isDirectory()) {
if (depth < 4) walk(p, depth + 1);
continue;
}
const thread = threadOfFile(e.name);
if (!thread || (e.name.endsWith('.zst') && names.has(e.name.slice(0, -'.zst'.length)))) continue;
try {
out.push({ path: p, thread, mtimeMs: fs.statSync(p).mtimeMs });
} catch {
// gone since the listing (compressed or restored): the next scan finds it as it is now
}
}
};
walk(path.join(home, 'sessions'), 0);
return out;
}
/**
* A rollout file's lines, plain or compressed, streamed: a compressed one through Node's own zstd decoder, so no whole file is
* held in memory and the reporter's tick is never held up by it. `at` is each line's byte offset in the decompressed file.
*/
export async function* fileLines(file: string): AsyncGenerator<Line> {
// pipeline passes a read error on to the decoder, whose error ends the iteration below: its callback has nothing left to do.
const input = file.endsWith('.zst') ? pipeline(fs.createReadStream(file), zlib.createZstdDecompress(), () => undefined) : fs.createReadStream(file);
const lines = readline.createInterface({ input, crlfDelay: Infinity });
let at = 0;
try {
for await (const text of lines) {
yield { text, at };
at += Buffer.byteLength(text) + 1;
}
} finally {
lines.close();
input.destroy();
}
}
/**
* The session a rollout file belongs to, from its first line: `session_meta.session_id`, the session tree's root, else the
* thread's own `id`. Null while the file has no complete first line.
*/
export async function sessionOfFile(file: string): Promise<string | null> {
for await (const line of fileLines(file)) {
const r = parseRolloutLine(line.text, line.at)?.record;
return r?.kind === 'meta' ? (r.sessionId ?? r.id) : null;
}
return null;
}
/** Codex's own thread names by thread id (threadNames), and the state of the index file they were read from. */
export interface ThreadNames {
/** The index's inode, size and mtime when read; empty when there was none to read. */
stamp: string;
byId: ReadonlyMap<string, string>;
}
export const NO_NAMES: ThreadNames = { stamp: '', byId: new Map() };
/**
* The names Codex keeps for its threads, in `$CODEX_HOME/session_index.jsonl` (`rollout/src/session_index.rs:20-33`): one
* `{ id, thread_name, updated_at }` line is appended each time a thread is named or renamed, and an id's newest nonempty name
* is its name (`:137-170`); dropping a thread's names rewrites the file (`:73-105`). Read whole only when the file's inode,
* size or mtime differs from `last`'s, else `last` itself is returned, so a caller sees a change by identity. No file, or one
* that cannot be read now, holds no names.
*/
export function threadNames(home: string, last: ThreadNames): ThreadNames {
const file = path.join(home, 'session_index.jsonl');
const byId = new Map<string, string>();
let stamp = '';
try {
const st = fs.statSync(file);
stamp = `${st.ino}:${st.size}:${st.mtimeMs}`;
if (stamp === last.stamp) return last;
for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
const e = parseJson(line);
const name = typeof e?.thread_name === 'string' ? e.thread_name.trim() : '';
if (name && typeof e?.id === 'string') byId.set(e.id, name);
}
} catch {
stamp = '';
}
return stamp === last.stamp ? last : { stamp, byId };
}
// ---- one record ---------------------------------------------------------------------------------
export interface RawUsage {
input: number;
cached: number;
cacheWrite: number;
output: number;
/** `reasoning_output_tokens`: read only to recognize Codex's fill to the window (mapping.ts isWindowFill). */
reasoning: number;
total: number;
}
export interface RawWindow {
usedPercent: number;
windowMinutes: number | null;
resetsAt: number | null;
}
/** What one session-file record says, in the reporter's terms. Free text is already cut and redacted: nothing longer is kept. */
export type RolloutRecord =
| {
kind: 'meta';
id: string;
sessionId: string | null;
parentId: string | null;
nickname: string | null;
role: string | null;
/** The agent path a multi-agent v2 spawn gave the thread (`/root/<task>`…), what a v2 message names it by; null otherwise. */
agentPath: string | null;
startedAt: number | null;
cwd: string | null;
cliVersion: string | null;
/** `session_meta.originator`: the client that started the thread (`Codex Desktop` for the desktop app, `codex-tui` …). */
originator: string | null;
historyMode: 'legacy' | 'paginated' | null;
}
| { kind: 'turnContext'; model: string | null; effort: string | null; cwd: string | null }
| { kind: 'turnStarted'; turnId: string | null; contextWindow: number | null }
| { kind: 'turnEnded'; aborted: boolean; failed: boolean; errorCategory: string | null; answer: string | null }
| { kind: 'tokens'; total: RawUsage | null; last: RawUsage | null; window: number | null; primary: RawWindow | null; secondary: RawWindow | null; hasLimits: boolean }
/** One billed model response's own tokens (`token_usage_record`, Codex `protocol/src/protocol.rs:2391-2402`). */
| { kind: 'usage'; threadId: string; responseId: string; usage: RawUsage }
| {
kind: 'call';
callId: string;
name: string;
summary: string;
plan: { step: string; status: string }[] | null;
spawnPrompt: string | null;
paths: string[];
/** A valid `request_user_input_async` call's questions. */
questions?: AsyncQuestion[];
/** What a call that sends another agent of the session a message sends, and to whom. */
message?: SentMessage;
}
/** `accepted`: the output is Codex's `{"accepted":true}`, which an async question call returns when it is shown. */
| { kind: 'callOutput'; callId: string; spawnedId: string | null; accepted: boolean }
| { kind: 'command'; id: string; summary: string; status: string; exitCode: number | null }
| { kind: 'fileChange'; id: string; paths: string[] }
| { kind: 'spawned'; prompt: string; receivers: string[] }
| { kind: 'message'; text: string }
/** A user message that is the reply envelope of async questions: only the question ids it answers are kept. */
| { kind: 'questionReply'; ids: string[] }
/** A user message's text, redacted as free text and cut to a session name's length (promptOf); nothing else of it is kept. */
| { kind: 'prompt'; text: string };
/**
* One `request_user_input_async` question as its ask needs it: the title, redacted and bounded, and the option labels the
* dashboard can show unaltered, kept as written so a chosen one is sent back exactly (nothing else is kept).
*/
export interface AsyncQuestion {
title: string;
options: string[];
}
/**
* One agent's message to another: `target` as the call names it (an agent id, or a v2 agent path or task name),
* redacted and cut to LIMITS.short; `text` the message, redacted and cut to LIMITS.text, empty when Codex holds it encrypted.
*/
export interface SentMessage {
target: string;
text: string;
}
export interface ParsedLine {
ts: number;
/** A stable key for the record within its file: its ordinal, else its byte offset. */
key: string;
record: RolloutRecord;
}
type Obj = Record<string, unknown>;
const obj = (v: unknown): Obj | null => (v && typeof v === 'object' && !Array.isArray(v) ? (v as Obj) : null);
const str = (v: unknown): string | null => (typeof v === 'string' && v ? v : null);
const num = (v: unknown): number | null => (typeof v === 'number' && Number.isFinite(v) ? v : null);
/** The record types and payload types the reporter reads; every other line is skipped without being parsed. */
const WANTED_EVENTS = new Set(['task_started', 'task_complete', 'turn_aborted', 'token_count', 'item_completed', 'agent_message', 'patch_apply_end', 'user_message']);
const WANTED_ITEMS = new Set(['function_call', 'custom_tool_call', 'local_shell_call', 'function_call_output', 'custom_tool_call_output']);
const HEAD = /"type":"([a-z_]+)"(?:,"payload":\{"type":"([A-Za-z_]+)")?/;
/** The markers of the reply envelope the Codex desktop app and TUI answer async questions with (`context-fragments/src/answered_question.rs:41-46`). */
export const REPLY_OPEN = '<send_user_message_question_reply>';
export const REPLY_CLOSE = '</send_user_message_question_reply>';
/**
* One session-file line in the reporter's terms; null for a line it does not read. `usageOnly`: only usage records and the
* `turn_context`s that name their model are read (a thread's older files). Never throws.
*/
export function parseRolloutLine(text: string, at: number, usageOnly = false): ParsedLine | null {
const head = HEAD.exec(text.slice(0, 400));
if (usageOnly && head?.[1] !== 'turn_context' && head?.[1] !== 'token_usage_record') return null;
if (head) {
const [, type, sub] = head;
if (type !== 'session_meta' && type !== 'turn_context' && type !== 'event_msg' && type !== 'response_item' && type !== 'token_usage_record') return null;
if (type === 'event_msg' && sub && !WANTED_EVENTS.has(sub)) return null;
// A message is read only when it may be a reply to async questions; the envelope's markers are never JSON-escaped.
if (type === 'response_item' && sub && !WANTED_ITEMS.has(sub) && !(sub === 'message' && text.includes(REPLY_OPEN))) return null;
}
let line: Obj | null;
try {
line = obj(JSON.parse(text));
} catch {
return null;
}
if (!line) return null;
const ts = Date.parse(String(line.timestamp ?? ''));
const payload = obj(line.payload);
if (!Number.isFinite(ts) || !payload) return null;
const ordinal = num(line.ordinal);
const record = recordOf(String(line.type ?? ''), payload);
return record ? { ts, key: ordinal !== null ? `o${ordinal}` : `b${at}`, record } : null;
}
function usageOf(v: unknown): RawUsage | null {
const u = obj(v);
if (!u) return null;
const input = num(u.input_tokens);
const output = num(u.output_tokens);
if (input === null || output === null) return null;
return {
input,
cached: num(u.cached_input_tokens) ?? 0,
cacheWrite: num(u.cache_write_input_tokens) ?? 0,
output,
reasoning: num(u.reasoning_output_tokens) ?? 0,
total: num(u.total_tokens) ?? input + output,
};
}
function windowOf(v: unknown): RawWindow | null {
const w = obj(v);
const used = num(w?.used_percent);
return w && used !== null ? { usedPercent: used, windowMinutes: num(w.window_minutes), resetsAt: num(w.resets_at) } : null;
}
/**
* `codex_error_info` as Codex serializes it: a snake_case name, or `{ "<name>": { … } }` for a variant with fields. Null when
* the error has none: it is then not an API failure category, whatever else it says.
*/
function errorCategory(v: unknown): string | null {
const info = obj(v)?.codex_error_info;
if (typeof info === 'string') return info || null;
const o = obj(info);
return (o && Object.keys(o)[0]) || null;
}
/** The file paths an `apply_patch` body names (`*** Add File:`, `*** Update File:`, `*** Delete File:`, `*** Move to:`); the body itself is not kept. */
export function patchPaths(patch: string): string[] {
const out: string[] = [];
for (const m of patch.matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/gm)) {
const p = m[1]!.trim();
if (p && !out.includes(p)) out.push(p);
if (out.length >= 50) break;
}
return out;
}
function parseJson(text: string): Obj | null {
try {
return obj(JSON.parse(text));
} catch {
return null;
}
}
/** A shell command's argv as one line: the script of `<shell> -lc <script>`, else the words joined. */
function commandLine(argv: unknown): string {
if (!Array.isArray(argv)) return typeof argv === 'string' ? argv : '';
const words = argv.filter((w): w is string => typeof w === 'string');
if (words.length === 3 && /^-l?c$/.test(words[1]!)) return words[2]!;
return words.join(' ');
}
function recordOf(type: string, p: Obj): RolloutRecord | null {
if (type === 'session_meta') {
const id = str(p.id);
if (!id) return null;
const source = p.source;
const spawn = obj(obj(obj(source)?.subagent)?.thread_spawn);
const mode = p.history_mode === 'paginated' ? 'paginated' : p.history_mode === 'legacy' ? 'legacy' : null;
const started = Date.parse(String(p.timestamp ?? ''));
return {
kind: 'meta',
id,
sessionId: str(p.session_id),
parentId: str(spawn?.parent_thread_id) ?? str(p.parent_thread_id),
nickname: str(spawn?.agent_nickname) ?? str(p.agent_nickname),
role: str(spawn?.agent_role) ?? str(p.agent_role),
agentPath: str(spawn?.agent_path),
startedAt: Number.isFinite(started) ? started : null,
cwd: str(p.cwd),
cliVersion: str(p.cli_version),
originator: str(p.originator),
// A rollout without the field predates paginated history (`#[serde(default)]` is legacy).
historyMode: mode ?? (p.history_mode === undefined ? 'legacy' : null),
};
}
if (type === 'turn_context') {
return { kind: 'turnContext', model: str(p.model), effort: str(p.effort), cwd: str(p.cwd) };
}
if (type === 'token_usage_record') {
// Only `usage`, the response's own tokens: `turn_token_usage` and `thread_token_usage` beside it are running totals.
const threadId = str(p.thread_id);
const responseId = str(p.response_id);
const usage = usageOf(p.usage);
return threadId && responseId && usage ? { kind: 'usage', threadId, responseId, usage } : null;
}
if (type === 'event_msg') {
switch (p.type) {
case 'task_started':
return { kind: 'turnStarted', turnId: str(p.turn_id), contextWindow: num(p.model_context_window) };
// `error` is the turn's terminal error (a failed turn); its `codex_error_info`, when present, is the category.
case 'task_complete':
return { kind: 'turnEnded', aborted: false, failed: !!p.error, errorCategory: errorCategory(p.error), answer: str(p.last_agent_message) ? excerpt(p.last_agent_message as string) : null };
case 'turn_aborted':
return { kind: 'turnEnded', aborted: true, failed: !!p.error, errorCategory: errorCategory(p.error), answer: null };
case 'token_count': {
const info = obj(p.info);
const limits = obj(p.rate_limits);
return {
kind: 'tokens',
total: usageOf(info?.total_token_usage),
last: usageOf(info?.last_token_usage),
window: num(info?.model_context_window),
primary: windowOf(limits?.primary),
secondary: windowOf(limits?.secondary),
hasLimits: limits !== null,
};
}
case 'agent_message':
return str(p.message) ? { kind: 'message', text: activityText(p.message as string) } : null;
// A legacy-history thread's user message; a paginated one's is an `item_completed` UserMessage (itemOf).
case 'user_message':
return promptOf(str(p.message) ?? '');
case 'patch_apply_end': {
const changes = obj(p.changes);
return changes ? { kind: 'fileChange', id: str(p.call_id) ?? '', paths: Object.keys(changes).slice(0, 50) } : null;
}
case 'item_completed':
return itemOf(obj(p.item));
default:
return null;
}
}
if (type === 'response_item') return responseItemOf(p);
return null;
}
/** A paginated-history item (`TurnItem`, tagged with its PascalCase variant name). */
function itemOf(item: Obj | null): RolloutRecord | null {
if (!item) return null;
switch (item.type) {
case 'CommandExecution':
return { kind: 'command', id: str(item.id) ?? '', summary: summarizeCall('Shell', { command: commandLine(item.command) }), status: String(item.status ?? ''), exitCode: num(item.exit_code) };
case 'FileChange': {
const changes = obj(item.changes);
return changes ? { kind: 'fileChange', id: str(item.id) ?? '', paths: Object.keys(changes).slice(0, 50) } : null;
}
case 'CollabAgentToolCall': {
if (item.tool !== 'spawn_agent') return null;
const receivers = Array.isArray(item.receiver_thread_ids) ? item.receiver_thread_ids.filter((r): r is string => typeof r === 'string') : [];
return receivers.length ? { kind: 'spawned', prompt: excerpt(str(item.prompt) ?? ''), receivers } : null;
}
case 'AgentMessage': {
const parts = Array.isArray(item.content) ? item.content.map((c) => str(obj(c)?.text) ?? '').filter(Boolean) : [];
return parts.length ? { kind: 'message', text: activityText(parts.join(' ')) } : null;
}
// Its text inputs joined, as Codex's `UserMessageItem::message` joins them (`protocol/src/items.rs:545-554`; only the text
// input has a `text`, `protocol/src/user_input.rs:16-57`).
case 'UserMessage':
return promptOf(Array.isArray(item.content) ? item.content.map((c) => str(obj(c)?.text) ?? '').join('') : '');
default:
return null;
}
}
/** Where an IDE extension's user message starts what the user typed, after the context it prepends (`protocol/src/protocol.rs:148`). */
const USER_MESSAGE_BEGIN = '## My request for Codex:';
/**
* A user message as a session name: its text as Codex previews a thread's first user message in its thread list
* (`protocol/src/protocol.rs:150-156, 2743-2747` user_message_preview, read by `rollout/src/list.rs:1061-1076`) — what follows
* an IDE context's USER_MESSAGE_BEGIN, trimmed — then redacted as free text and cut to a name's length (report.ts promptName).
* Null for a message with no text (Codex's `[Image]` and `[Audio]` placeholders name nothing) and for a reply to async
* questions, which answers rather than asks.
*/
function promptOf(text: string): RolloutRecord | null {
const at = text.indexOf(USER_MESSAGE_BEGIN);
const own = (at === -1 ? text : text.slice(at + USER_MESSAGE_BEGIN.length)).trim();
const name = own && !questionReplyIds(text) ? promptName(own, LIMITS.name) : '';
return name ? { kind: 'prompt', text: name } : null;
}
/** How many questions, and options per question, a call keeps: past the ask's limits it is not announced anyway. */
const QUESTIONS_KEPT = 8;
/**
* The questions of a `request_user_input_async` call, checked as Codex checks them before it shows any
* (`core/src/tools/handlers/request_user_input_async.rs:29-33, 106-129`; `protocol/src/items.rs:144-150`, both
* `deny_unknown_fields`): null when Codex would refuse the call and show nothing. Titles and labels are kept redacted and
* bounded; nothing else of the call is.
*/
function asyncQuestionsOf(args: Obj | null): AsyncQuestion[] | null {
if (!args || Object.keys(args).some((k) => k !== 'questions') || !Array.isArray(args.questions) || args.questions.length === 0) return null;
const out: AsyncQuestion[] = [];
for (const raw of args.questions) {
const q = obj(raw);
if (!q || Object.keys(q).some((k) => k !== 'title' && k !== 'options') || typeof q.title !== 'string' || !q.title.trim()) return null;
const options = q.options ?? null;
if (options !== null && (!Array.isArray(options) || options.length === 0 || options.some((o) => typeof o !== 'string' || !o.trim()))) return null;
out.push({ title: clip(q.title, 2000), options: ((options ?? []) as string[]).slice(0, 32).filter(showsUnaltered).slice(0, QUESTIONS_KEPT) });
}
return out.slice(0, QUESTIONS_KEPT);
}
/**
* Whether the dashboard can show an option label exactly as written — within 512 bytes and our label limit, on one line with
* no whitespace to fold, nothing redaction would change. Codex's TUI keeps at most 32 options, drops any label over 512
* bytes, and lets only a fully displayed option become the answer (`tui/src/bottom_pane/async_questions/state.rs:29-39,
* 121-130`); an option the dashboard would have to alter is dropped the same way, never shown altered.
*/
function showsUnaltered(label: string): boolean {
return Buffer.byteLength(label) <= 512 && label.length <= RESPOND_LIMITS.label && redact(label.replace(/\s+/g, ' ').trim()) === label;
}
/**
* The question ids a user message's text answers, parsed as Codex's TUI recognizes the desktop's replies from any client
* (`tui/src/async_question_reply.rs:15-37`): the text trimmed, past an optional IDE-context prefix, must be exactly the reply
* envelope around one reply or an array of them, each with string `questionItemId`, `question` and `answer`. Null otherwise.
*/
export function questionReplyIds(text: string): string[] | null {
let t = text.trim();
if (t.startsWith('# Context from my IDE setup:\n')) {
const at = t.lastIndexOf('\n## My request for Codex:\n');
if (at === -1) return null;
t = t.slice(at + '\n## My request for Codex:\n'.length).trim();
}
if (!t.startsWith(REPLY_OPEN) || !t.endsWith(REPLY_CLOSE) || t.length < REPLY_OPEN.length + REPLY_CLOSE.length) return null;
let parsed: unknown;
try {
parsed = JSON.parse(t.slice(REPLY_OPEN.length, t.length - REPLY_CLOSE.length));
} catch {
return null;
}
const replies = Array.isArray(parsed) ? parsed : [parsed];
const ids: string[] = [];
for (const r of replies) {
const o = obj(r);
if (!o || typeof o.questionItemId !== 'string' || typeof o.question !== 'string' || typeof o.answer !== 'string') return null;
ids.push(o.questionItemId);
}
return ids.length ? ids : null;
}
/** Codex's shell tools (exec_command, core/src/tools/handlers/shell_spec.rs:89; shell and shell_command before it). */
const SHELL_TOOLS = new Set(['exec_command', 'shell', 'shell_command']);
/**
* The namespaces Codex dispatches its message tools from: v1's fixed one (`core/src/tools/handlers/multi_agents_spec.rs:14`) and
* v2's default (`core/src/config/mod.rs:263`; a v2 namespace configured otherwise is not recognized). The same names in any
* other namespace (an MCP server's `send_message`) are not messages between agents.
*/
const MULTI_AGENT_V1 = 'multi_agent_v1';
const MULTI_AGENT_V2 = 'collaboration';
/**
* The message a function call sends another agent of its session, null for any other call. Codex's message tools:
* v1 `send_input` — `{ target, message?, items? }`, the target an agent id (`handlers/multi_agents/send_input.rs:146-153`),
* the input a message or items, shown as Codex previews it for "Sent input to" (`agent/control.rs:739-760`, item paths left
* out); v2 `send_message` and `followup_task` — `{ target, message }`, the target an agent id or a task name or path
* (`handlers/multi_agents_v2/message_tool.rs:16-30`). A v2 message may reach the session file encrypted; it is shown only when
* Codex itself takes it as plain text — the call's `encrypted_function_args` present and empty (`tools/router.rs:56-71`,
* `handlers/multi_agents_v2.rs:54-67`) — and is otherwise left empty, unknown.
*/
function messageOf(p: Obj, args: Obj): SentMessage | null {
// The tool's own name, without the namespace a call's name carries.
const name = str(p.name);
const v1 = name === 'send_input' && p.namespace === MULTI_AGENT_V1;
const v2 = (name === 'send_message' || name === 'followup_task') && p.namespace === MULTI_AGENT_V2;
const target = str(args.target);
if (!(v1 || v2) || !target) return null;
let text: string;
if (v2) {
const plain = Array.isArray(p.encrypted_function_args) && p.encrypted_function_args.length === 0;
text = plain ? (str(args.message) ?? '') : '';
} else if (typeof args.message === 'string') {
text = args.message;
} else if (Array.isArray(args.items)) {
text = args.items
.map((item) => {
const o = obj(item);
return o?.type === 'text' ? (str(o.text) ?? '') : `[${str(o?.type) ?? 'input'}]`;
})
.join('\n');
} else return null;
// The message is a tool's free-text argument: the broader rules, then the narrow ones.
return { target: excerpt(target, LIMITS.short), text: clipFreeText(text.replace(/\s+/g, ' ').trim(), LIMITS.text) };
}
function responseItemOf(p: Obj): RolloutRecord | null {
if (p.type === 'message') {
// Like the TUI's parse_input: a user message whose only content is one text (`tui/src/async_question_reply.rs:49-60`).
const content = Array.isArray(p.content) ? p.content : [];
const only = content.length === 1 ? obj(content[0]) : null;
const ids = p.role === 'user' && only?.type === 'input_text' && typeof only.text === 'string' ? questionReplyIds(only.text) : null;
return ids ? { kind: 'questionReply', ids: ids.slice(0, 50).map((id) => id.slice(0, 600)) } : null;
}
const callId = str(p.call_id);
if (p.type === 'function_call_output' || p.type === 'custom_tool_call_output') {
if (!callId) return null;
// Only a spawn_agent result's child and an async question call's acceptance are read; nothing else in an output is.
const out = typeof p.output === 'string' ? parseJson(p.output) : null;
return { kind: 'callOutput', callId, spawnedId: str(out?.agent_id), accepted: out?.accepted === true };
}
if (p.type === 'local_shell_call') {
const action = obj(p.action);
return callId ? { kind: 'call', callId, name: 'local_shell', summary: summarizeCall('Shell', { command: commandLine(action?.command) }), plan: null, spawnPrompt: null, paths: [] } : null;
}
// A namespaced call keeps its namespace (an MCP tool reads `mcp__<server>__<tool>`, as Codex names it to hooks), so no
// server's tool takes a built-in's name. Codex's own V1 spawn keeps the name `spawn_agent`, as Codex names it to hooks
// (registry.rs:1030-1036).
const ns = str(p.namespace);
const own = str(p.name);
const name = own && ns && ns !== 'functions' && !(ns === 'multi_agent_v1' && own === 'spawn_agent') ? `${ns}__${own}` : own;
if (!callId || !name) return null;
// A shell tool's call is summarized as `Shell`, as a local_shell_call is, so its command gets the free-text rules.
const tool = SHELL_TOOLS.has(name) ? 'Shell' : name;
if (p.type === 'custom_tool_call') {
const input = typeof p.input === 'string' ? p.input : '';
if (name === 'apply_patch') return { kind: 'call', callId, name, summary: summarizeCall(name, {}), plan: null, spawnPrompt: null, paths: patchPaths(input) };
return { kind: 'call', callId, name, summary: summarizeCall(tool, { input }), plan: null, spawnPrompt: null, paths: [] };
}
const args = typeof p.arguments === 'string' ? (parseJson(p.arguments) ?? {}) : {};
if (name === 'update_plan') {
const steps = Array.isArray(args.plan)
? args.plan.map((s) => obj(s)).filter((s): s is Obj => !!s && typeof s.step === 'string').map((s) => ({ step: s.step as string, status: String(s.status ?? 'pending') }))
: [];
return { kind: 'call', callId, name, summary: summarizeCall(name, {}), plan: steps, spawnPrompt: null, paths: [] };
}
if (name === 'spawn_agent') {
const message = str(args.message) ?? '';
return { kind: 'call', callId, name, summary: summarizeCall(name, { agent_type: args.agent_type ?? '' }), plan: null, spawnPrompt: excerpt(message), paths: [] };
}
if (name === 'apply_patch') {
return { kind: 'call', callId, name, summary: summarizeCall(name, {}), plan: null, spawnPrompt: null, paths: patchPaths(str(args.input) ?? str(args.patch) ?? '') };
}
if (name === 'request_user_input_async') {
// The call id is the id of the agent message that carries the questions (request_user_input_async.rs:131-140).
const questions = asyncQuestionsOf(typeof p.arguments === 'string' ? parseJson(p.arguments) : null);
return { kind: 'call', callId, name, summary: summarizeCall(name, {}), plan: null, spawnPrompt: null, paths: [], ...(questions ? { questions } : {}) };
}
const message = messageOf(p, args);
// Summarized by its target, as a spawn by its agent type: the message itself is the event's.
if (message) return { kind: 'call', callId, name, summary: summarizeCall(tool, { target: message.target }), plan: null, spawnPrompt: null, paths: [], message };
return { kind: 'call', callId, name, summary: summarizeCall(tool, args), plan: null, spawnPrompt: null, paths: [] };
}