sidekick-shared 0.29.1 → 0.30.0

package/dist/testing/codexSubagentFixtures.js

@@ -0,0 +1,344 @@
+"use strict";
+/**
+ * Redacted rollouts in the shape Codex 0.166 writes for multi-agent sessions:
+ * a parent that spawns a child (`spawn_agent` → `SubAgentActivity` started →
+ * `{"task_name": …}` output → MESSAGE / FINAL_ANSWER agent messages →
+ * `completed`), a failed spawn, `followup_task` / `send_message` /
+ * `interrupt_agent` interactions, and a forked child whose rollout embeds the
+ * parent's history (and session_meta) before its
+ * `subagent_history_start_ordinal`, which itself spawns a grandchild.
+ * Payload text is placeholder; ids are synthetic.
+ *
+ * Test-only helpers.
+ *
+ * @module testing/codexSubagentFixtures
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRANDCHILD_PATH = exports.CHILD_PATH = exports.CHILD_TURN_ID = exports.CALL_SPAWN_GRANDCHILD = exports.CALL_INTERRUPT = exports.CALL_SEND = exports.CALL_FOLLOWUP = exports.CALL_SPAWN_FAILED = exports.CALL_SPAWN = exports.GRANDCHILD_ID = exports.CHILD_ID = exports.PARENT_ID = void 0;
+exports.at = at;
+exports.parentRollout = parentRollout;
+exports.childRollout = childRollout;
+exports.grandchildRollout = grandchildRollout;
+exports.toJsonl = toJsonl;
+exports.PARENT_ID = '01a18f87-0000-7000-8000-000000000001';
+exports.CHILD_ID = '01a18f9d-0000-7000-8000-000000000002';
+exports.GRANDCHILD_ID = '01a18fa0-0000-7000-8000-000000000003';
+exports.CALL_SPAWN = 'call_spawn_builder';
+exports.CALL_SPAWN_FAILED = 'call_spawn_failed';
+exports.CALL_FOLLOWUP = 'call_followup_builder';
+exports.CALL_SEND = 'call_send_builder';
+exports.CALL_INTERRUPT = 'call_interrupt_builder';
+exports.CALL_SPAWN_GRANDCHILD = 'call_spawn_deep_dive';
+exports.CHILD_TURN_ID = '01a18f9d-0000-7000-8000-0000000000t1';
+exports.CHILD_PATH = '/root/review_builder';
+exports.GRANDCHILD_PATH = '/root/review_builder/deep_dive';
+/** `2026-10-31T01:<minute>:<second>.000Z`. */
+function at(minute, second = 0) {
+    return `2026-10-31T01:${String(minute).padStart(2, '0')}:${String(second).padStart(2, '0')}.000Z`;
+}
+function numbered(rows) {
+    return rows.map((row, ordinal) => ({ timestamp: row.timestamp, ordinal, ...row }));
+}
+function tokenCount(timestamp, total, last) {
+    return {
+        timestamp,
+        type: 'event_msg',
+        payload: {
+            type: 'token_count',
+            info: {
+                total_token_usage: { input_tokens: total, output_tokens: 0, total_tokens: total },
+                last_token_usage: { input_tokens: last, output_tokens: 0, total_tokens: last },
+            },
+        },
+    };
+}
+function functionCall(timestamp, callId, name, args, namespace = 'collaboration') {
+    return {
+        timestamp,
+        type: 'response_item',
+        payload: {
+            type: 'function_call',
+            status: 'completed',
+            id: `fc_${callId}`,
+            name,
+            ...(namespace ? { namespace } : {}),
+            arguments: JSON.stringify(args),
+            call_id: callId,
+        },
+    };
+}
+function output(timestamp, callId, text) {
+    return {
+        timestamp,
+        type: 'response_item',
+        payload: { type: 'function_call_output', call_id: callId, output: text },
+    };
+}
+function activity(timestamp, threadId, item) {
+    return {
+        timestamp,
+        type: 'event_msg',
+        payload: {
+            type: 'item_completed',
+            thread_id: threadId,
+            turn_id: `${threadId}-turn`,
+            item: { type: 'SubAgentActivity', model: null, reasoning_effort: null, ...item },
+        },
+    };
+}
+function agentMessage(timestamp, id, author, recipient, messageType, payload) {
+    return {
+        timestamp,
+        type: 'response_item',
+        payload: {
+            type: 'agent_message',
+            id,
+            author,
+            recipient,
+            content: [
+                {
+                    type: 'input_text',
+                    text: `Message Type: ${messageType}\nTask name: ${recipient}\nSender: ${author}\nPayload:\n${payload}`,
+                },
+                ...(payload ? [] : [{ type: 'encrypted_content', encrypted_content: 'gAAAA-redacted' }]),
+            ],
+        },
+    };
+}
+function exec(timestamp, callId) {
+    return functionCall(timestamp, callId, 'exec_command', { cmd: 'rg TODO' }, undefined);
+}
+/** The parent session's rollout (ordinals 0…). */
+function parentRollout(options) {
+    const rows = [
+        {
+            timestamp: at(15),
+            type: 'session_meta',
+            payload: {
+                id: exports.PARENT_ID,
+                session_id: exports.PARENT_ID,
+                timestamp: at(15),
+                cwd: options.cwd,
+                originator: 'codex-tui',
+                cli_version: '0.166.0',
+                source: 'vscode',
+                thread_source: 'user',
+                history_mode: 'paginated',
+                base_instructions: { text: 'Parent base instructions.' },
+            },
+        },
+        {
+            timestamp: at(15, 1),
+            type: 'turn_context',
+            payload: { model: 'gpt-test', cwd: options.cwd },
+        },
+        {
+            timestamp: at(15, 2),
+            type: 'response_item',
+            payload: {
+                type: 'message',
+                role: 'user',
+                content: [{ type: 'input_text', text: 'Review the builder.' }],
+            },
+        },
+        tokenCount(at(15, 3), 1000, 1000),
+        functionCall(at(40, 33), exports.CALL_SPAWN, 'spawn_agent', {
+            task_name: 'review_builder',
+            message: 'gAAAA-redacted',
+        }),
+        options.withoutActivity
+            ? null
+            : activity(at(40, 33), exports.PARENT_ID, {
+                id: exports.CALL_SPAWN,
+                kind: 'started',
+                model: 'gpt-test',
+                reasoning_effort: 'high',
+                agent_thread_id: exports.CHILD_ID,
+                agent_path: exports.CHILD_PATH,
+            }),
+        output(at(40, 34), exports.CALL_SPAWN, JSON.stringify({ task_name: exports.CHILD_PATH })),
+        functionCall(at(40, 35), exports.CALL_SPAWN_FAILED, 'spawn_agent', {
+            task_name: 'review_extra',
+            message: 'gAAAA-redacted',
+        }),
+        output(at(40, 35), exports.CALL_SPAWN_FAILED, 'collab spawn failed: agent thread limit reached'),
+        {
+            timestamp: at(41, 8),
+            type: 'inter_agent_communication_metadata',
+            payload: { trigger_turn: false },
+        },
+        agentMessage(at(41, 8), 'amsg_progress', exports.CHILD_PATH, '/root', 'MESSAGE', ''),
+        options.withoutActivity || options.withoutCompleted
+            ? null
+            : activity(at(42, 21), exports.PARENT_ID, {
+                id: `subagent-completed-${exports.CHILD_TURN_ID}`,
+                kind: 'completed',
+                agent_thread_id: exports.CHILD_ID,
+                agent_path: exports.CHILD_PATH,
+            }),
+        agentMessage(at(42, 25), 'amsg_final', exports.CHILD_PATH, '/root', 'FINAL_ANSWER', 'Found two issues.'),
+        functionCall(at(45, 37), exports.CALL_FOLLOWUP, 'followup_task', {
+            target: 'review_builder',
+            message: 'gAAAA-redacted',
+        }),
+        options.withoutActivity
+            ? null
+            : activity(at(45, 37), exports.PARENT_ID, {
+                id: exports.CALL_FOLLOWUP,
+                kind: 'interacted',
+                agent_thread_id: exports.CHILD_ID,
+                agent_path: exports.CHILD_PATH,
+            }),
+        output(at(45, 38), exports.CALL_FOLLOWUP, ''),
+        functionCall(at(45, 40), exports.CALL_SEND, 'send_message', {
+            target: 'review_builder',
+            message: 'gAAAA-redacted',
+        }),
+        options.withoutActivity
+            ? null
+            : activity(at(45, 40), exports.PARENT_ID, {
+                id: exports.CALL_SEND,
+                kind: 'interacted',
+                agent_thread_id: exports.CHILD_ID,
+                agent_path: exports.CHILD_PATH,
+            }),
+        functionCall(at(46, 0), exports.CALL_INTERRUPT, 'interrupt_agent', { target: 'review_builder' }),
+        options.withoutActivity
+            ? null
+            : activity(at(46, 0), exports.PARENT_ID, {
+                id: exports.CALL_INTERRUPT,
+                kind: 'interrupted',
+                agent_thread_id: exports.CHILD_ID,
+                agent_path: exports.CHILD_PATH,
+            }),
+        tokenCount(at(46, 5), 2000, 1000),
+    ];
+    return numbered(rows.filter((row) => row !== null));
+}
+/** Records the child inherits from the parent (re-stamped at fork time, as Codex does). */
+const INHERITED_RECORDS = 5;
+/** The forked child's rollout: its meta, the parent's history, then its own records. */
+function childRollout(options) {
+    const start = 1 + INHERITED_RECORDS;
+    return numbered([
+        {
+            timestamp: at(40, 33),
+            type: 'session_meta',
+            payload: {
+                id: exports.CHILD_ID,
+                session_id: exports.PARENT_ID,
+                forked_from_id: exports.PARENT_ID,
+                parent_thread_id: exports.PARENT_ID,
+                timestamp: at(40, 33),
+                cwd: options.cwd,
+                originator: 'codex-tui',
+                cli_version: '0.166.0',
+                source: {
+                    subagent: {
+                        thread_spawn: {
+                            parent_thread_id: exports.PARENT_ID,
+                            depth: 1,
+                            agent_path: exports.CHILD_PATH,
+                            agent_nickname: 'Banach',
+                            agent_role: null,
+                        },
+                    },
+                },
+                thread_source: 'subagent',
+                agent_nickname: 'Banach',
+                agent_path: exports.CHILD_PATH,
+                history_mode: 'paginated',
+                subagent_history_start_ordinal: start,
+                multi_agent_version: 'v2',
+            },
+        },
+        // The parent's history, embedded by the fork.
+        {
+            timestamp: at(40, 33),
+            type: 'session_meta',
+            payload: {
+                id: exports.PARENT_ID,
+                timestamp: at(15),
+                cwd: '/somewhere/else',
+                source: 'vscode',
+                base_instructions: { text: 'Parent base instructions.' },
+            },
+        },
+        { timestamp: at(40, 33), type: 'turn_context', payload: { model: 'gpt-parent' } },
+        exec(at(40, 33), 'call_parent_exec'),
+        tokenCount(at(40, 33), 5000, 5000),
+        {
+            timestamp: at(40, 33),
+            type: 'response_item',
+            payload: {
+                type: 'message',
+                role: 'developer',
+                content: [{ type: 'input_text', text: 'You are now a newly spawned child agent.' }],
+            },
+        },
+        // The child's own records.
+        {
+            timestamp: at(40, 34),
+            type: 'event_msg',
+            payload: { type: 'task_started', turn_id: exports.CHILD_TURN_ID },
+        },
+        { timestamp: at(40, 34), type: 'turn_context', payload: { model: 'gpt-test' } },
+        exec(at(40, 35), 'call_child_exec'),
+        output(at(40, 36), 'call_child_exec', 'Process exited with code 0'),
+        tokenCount(at(40, 37), 300, 300),
+        functionCall(at(40, 38), exports.CALL_SPAWN_GRANDCHILD, 'spawn_agent', {
+            task_name: 'deep_dive',
+            message: 'gAAAA-redacted',
+        }),
+        activity(at(40, 38), exports.CHILD_ID, {
+            id: exports.CALL_SPAWN_GRANDCHILD,
+            kind: 'started',
+            agent_thread_id: exports.GRANDCHILD_ID,
+            agent_path: exports.GRANDCHILD_PATH,
+        }),
+        output(at(40, 39), exports.CALL_SPAWN_GRANDCHILD, JSON.stringify({ task_name: exports.GRANDCHILD_PATH })),
+        tokenCount(at(42, 20), 500, 200),
+    ]);
+}
+/** The grandchild's rollout (depth 2): a fork of the child. */
+function grandchildRollout(options) {
+    return numbered([
+        {
+            timestamp: at(40, 38),
+            type: 'session_meta',
+            payload: {
+                id: exports.GRANDCHILD_ID,
+                session_id: exports.PARENT_ID,
+                forked_from_id: exports.CHILD_ID,
+                parent_thread_id: exports.CHILD_ID,
+                timestamp: at(40, 38),
+                cwd: options.cwd,
+                cli_version: '0.166.0',
+                source: {
+                    subagent: {
+                        thread_spawn: {
+                            parent_thread_id: exports.CHILD_ID,
+                            depth: 2,
+                            agent_path: exports.GRANDCHILD_PATH,
+                            agent_nickname: 'Noether',
+                            agent_role: 'explorer',
+                        },
+                    },
+                },
+                thread_source: 'subagent',
+                agent_nickname: 'Noether',
+                agent_path: exports.GRANDCHILD_PATH,
+                agent_role: 'explorer',
+                subagent_history_start_ordinal: 3,
+            },
+        },
+        { timestamp: at(40, 38), type: 'session_meta', payload: { id: exports.CHILD_ID, cwd: options.cwd } },
+        exec(at(40, 38), 'call_child_exec'),
+        exec(at(40, 40), 'call_grandchild_exec'),
+        tokenCount(at(40, 41), 50, 50),
+    ]);
+}
+/** Rows as JSONL text. */
+function toJsonl(rows) {
+    return rows.map((row) => JSON.stringify(row)).join('\n') + '\n';
+}

package/dist/toolCallOrigins.d.ts

@@ -32,6 +32,11 @@ export interface FindToolCallOriginsOptions {
     providers?: PromptHistoryProvider[];
     /** Stops between files and lines; the promise rejects with the signal's reason. */
     signal?: AbortSignal;
+    /**
+     * Codex: also search compressed rollouts (`….jsonl.zst`), as for
+     * `collectPromptHistory()`. Default false.
+     */
+    includeCompressedRollouts?: boolean;
 }
 export interface ToolCallOrigin {
     provider: PromptHistoryProvider;

package/dist/toolCallOrigins.js

@@ -57,6 +57,8 @@ exports.findToolCallOrigins = findToolCallOrigins;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
+const stream_1 = require("stream");
+const compressedRollouts_1 = require("./providers/compressedRollouts");
 const promptHistory_1 = require("./promptHistory");
 const codexRolloutOrigin_1 = require("./parsers/codexRolloutOrigin");
 const workspaceRoots_1 = require("./workspaceRoots");
@@ -78,7 +80,9 @@ async function findToolCallOrigins(options) {
         return found;
     const providers = options.providers ?? ['claude-code', 'codex'];
     const sinceMs = options.since ? options.since.getTime() : null;
-    const candidates = await (0, promptHistory_1.listCandidates)(providers, listingRoots, sinceMs);
+    const candidates = await (0, promptHistory_1.listCandidates)(providers, listingRoots, sinceMs, {
+        includeCompressedRollouts: options.includeCompressedRollouts,
+    });
     const byProviderSession = new Map();
     for (const candidate of candidates) {
         byProviderSession.set(`${candidate.provider}:${candidate.sessionId}`, candidate);
@@ -188,21 +192,15 @@ function claudeSubagentTranscripts(sessionFile, sessionId) {
     }));
 }
 async function readFirstRecord(filePath) {
-    let handle;
     try {
-        handle = await fs.promises.open(filePath, 'r');
-        const buffer = Buffer.alloc(256 * 1024);
-        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
-        const text = buffer.subarray(0, bytesRead).toString('utf8');
+        // A compressed rollout's head is decompressed.
+        const text = (await (0, compressedRollouts_1.readRolloutHeadAsync)(filePath, 256 * 1024)).toString('utf8');
         const newline = text.indexOf('\n');
         return JSON.parse(newline === -1 ? text : text.slice(0, newline));
     }
     catch {
         return undefined;
     }
-    finally {
-        await handle?.close();
-    }
 }
 /** Fail-closed scope check on a recorded working directory. */
 function inScope(cwd, roots, realpaths) {
@@ -223,7 +221,16 @@ async function scanForIds(filePath, provider, wanted, roots, realpaths, signal)
     const hits = [];
     let stream;
     try {
-        stream = fs.createReadStream(filePath, { encoding: 'utf8' });
+        if ((0, compressedRollouts_1.isCompressedRolloutPath)(filePath)) {
+            // Compressed rollouts are complete; search their decompressed content.
+            const content = await (0, compressedRollouts_1.readRolloutBufferAsync)(filePath);
+            if (!content)
+                return hits;
+            stream = stream_1.Readable.from([content.toString('utf8')]);
+        }
+        else {
+            stream = fs.createReadStream(filePath, { encoding: 'utf8' });
+        }
     }
     catch {
         return hits;

package/dist/toolCategory.js

@@ -20,7 +20,11 @@ exports.TOOL_CATEGORIES = [
     'mcp',
     'other',
 ];
-/** Lower-cased tool names of every provider, by category. */
+/**
+ * Lower-cased tool names of every provider, by category. Codex's bare `wait`
+ * is a code-mode cell wait, not a subagent wait (that is `wait_agent`), so it
+ * is `other`.
+ */
 const CATEGORY_BY_NAME = new Map([
     [
         'shell',
@@ -54,7 +58,7 @@ const CATEGORY_BY_NAME = new Map([
             'send_message',
             'followup_task',
             'list_agents',
-            'wait',
+            'interrupt_agent',
         ],
     ],
     [

package/dist/transcript.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectSessionTranscript = projectSessionTranscript;
 const usageNormalization_1 = require("./usageNormalization");
 const subagentSpawn_1 = require("./subagentSpawn");
+const subagentActivity_1 = require("./subagentActivity");
 const EMPTY_TOTALS = {
     uncachedInputTokens: 0,
     cacheReadTokens: 0,
@@ -30,7 +31,10 @@ function projectSessionTranscript(events, options = {}) {
     let gitBranch;
     events.forEach((event, eventIndex) => {
         // A reader's synthetic notice that a background task finished, not a message.
-        if ((0, subagentSpawn_1.isTaskNotificationSystemEvent)(event))
+        if ((0, subagentSpawn_1.isTaskNotificationSystemEvent)(event) || (0, subagentSpawn_1.isTaskStatusSystemEvent)(event))
+            return;
+        // Likewise a subagent lifecycle record (opt-in Codex parser event).
+        if ((0, subagentActivity_1.isSubagentActivitySystemEvent)(event))
             return;
         if (nonEmpty(event.cwd))
             cwd = event.cwd;

package/dist/turns/assistantTurn.d.ts

@@ -70,7 +70,10 @@ export interface ReasoningSummary {
     body: string;
 }
 export declare function reasoningSummary(text: string): ReasoningSummary;
-/** Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`). */
+/**
+ * Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`).
+ * Codex `spawn_agent` is not included here (its turns project as before).
+ */
 export declare function isAssistantTurnSubagentTool(toolName: string | undefined): boolean;
 export declare function segmentAssistantTurn(events: readonly AssistantTurnEvent[], options?: SegmentAssistantTurnOptions): AssistantTurnProjection;
 export declare function assistantTurnEventsFromSessionEvents(events: readonly SessionEvent[]): AssistantTurnEvent[];

package/dist/turns/assistantTurn.js

@@ -29,9 +29,12 @@ function reasoningSummary(text) {
     }
     return { title: null, body: trimmed };
 }
-/** Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`). */
+/**
+ * Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`).
+ * Codex `spawn_agent` is not included here (its turns project as before).
+ */
 function isAssistantTurnSubagentTool(toolName) {
-    return (0, subagentSpawn_1.isSubagentSpawnTool)(toolName);
+    return typeof toolName === 'string' && subagentSpawn_1.SUBAGENT_SPAWN_TOOL_NAMES.includes(toolName);
 }
 function segmentAssistantTurn(events, options = {}) {
     const maxNarrationChars = options.maxNarrationChars ?? DEFAULT_NARRATION_CHARS;

package/dist/types/codex.d.ts

@@ -16,6 +16,12 @@ export interface CodexRolloutLine {
     timestamp: string;
     /** Discriminator for the payload type */
     type: 'session_meta' | 'response_item' | 'compacted' | 'turn_context' | 'event_msg';
+    /**
+     * Zero-based position of the record in its rollout (recent Codex versions).
+     * In a forked subagent rollout, records before the child's
+     * `session_meta.subagent_history_start_ordinal` are the parent's history.
+     */
+    ordinal?: number;
     /** Type-specific payload */
     payload: CodexSessionMeta | CodexResponseItem | CodexCompacted | CodexTurnContext | CodexEventMsg;
 }
@@ -37,13 +43,32 @@ export interface CodexSessionMeta {
         dirty?: boolean;
     };
     forked_from_id?: string;
+    /** The root session of a subagent tree (recent Codex versions). */
+    session_id?: string;
+    /** Subagents: the thread that spawned this one. */
+    parent_thread_id?: string;
+    /** `user`, `subagent`, … (recent Codex versions). */
+    thread_source?: string;
+    /** Subagents: display nickname, e.g. `Banach`. */
+    agent_nickname?: string | null;
+    /** Subagents: agent path, e.g. `/root/review_builder`. */
+    agent_path?: string | null;
+    /** Subagents: requested role (`agent_type`), when one was given. */
+    agent_role?: string | null;
+    /**
+     * Forked subagents: the ordinal of the first record that is the child's
+     * own; earlier records are the parent's history the fork embeds.
+     */
+    subagent_history_start_ordinal?: number;
+    history_mode?: string;
+    multi_agent_version?: string;
 }
 /**
  * A response item from the model.
  * The payload IS the item directly (no .item wrapper).
  * Tagged union on `type`.
  */
-export type CodexResponseItem = CodexMessageItem | CodexReasoningItem | CodexFunctionCallItem | CodexFunctionCallOutputItem | CodexLocalShellCallItem | CodexWebSearchCallItem | CodexCustomToolCallItem | CodexCustomToolCallOutputItem;
+export type CodexResponseItem = CodexMessageItem | CodexAgentMessageItem | CodexReasoningItem | CodexFunctionCallItem | CodexFunctionCallOutputItem | CodexLocalShellCallItem | CodexWebSearchCallItem | CodexCustomToolCallItem | CodexCustomToolCallOutputItem;
 /** Chat message (user, assistant, or developer). */
 export interface CodexMessageItem {
     type: 'message';
@@ -53,6 +78,22 @@ export interface CodexMessageItem {
     status?: string;
     phase?: string;
 }
+/**
+ * A message between agents of a multi-agent session (`author` and
+ * `recipient` are agent paths such as `/root/review_builder` and `/root`).
+ * Its first text part starts `Message Type: MESSAGE | NEW_TASK |
+ * FINAL_ANSWER`, followed by `Task name:`, `Sender:`, and `Payload:` lines.
+ */
+export interface CodexAgentMessageItem {
+    type: 'agent_message';
+    id?: string;
+    author?: string;
+    recipient?: string;
+    content: Array<CodexContentPart | {
+        type: 'encrypted_content';
+        encrypted_content?: string;
+    }>;
+}
 /** Content part within a message. */
 export interface CodexContentPart {
     type: 'output_text' | 'input_text' | 'refusal' | 'text';
@@ -79,6 +120,8 @@ export interface CodexFunctionCallItem {
     name: string;
     arguments: string;
     status?: string;
+    /** Tool namespace, e.g. `collaboration` for the multi-agent tools. */
+    namespace?: string;
 }
 /** Result of a function call. */
 export interface CodexFunctionCallOutputItem {
@@ -140,7 +183,7 @@ export interface CodexTurnContext {
  * Tagged union on `type`.
  */
 export type CodexEventMsg = CodexEvent;
-export type CodexEvent = CodexTurnStartedEvent | CodexTurnCompleteEvent | CodexTaskStartedEvent | CodexTaskCompleteEvent | CodexTurnAbortedEvent | CodexTokenCountEvent | CodexAgentMessageEvent | CodexAgentReasoningEvent | CodexUserMessageEvent | CodexExecCommandBeginEvent | CodexExecCommandEndEvent | CodexMcpToolCallBeginEvent | CodexMcpToolCallEndEvent | CodexErrorEvent | CodexContextCompactedEvent | CodexPatchAppliedEvent | CodexBackgroundEvent | CodexGenericEvent;
+export type CodexEvent = CodexTurnStartedEvent | CodexTurnCompleteEvent | CodexTaskStartedEvent | CodexTaskCompleteEvent | CodexTurnAbortedEvent | CodexTokenCountEvent | CodexAgentMessageEvent | CodexAgentReasoningEvent | CodexUserMessageEvent | CodexExecCommandBeginEvent | CodexExecCommandEndEvent | CodexMcpToolCallBeginEvent | CodexMcpToolCallEndEvent | CodexErrorEvent | CodexContextCompactedEvent | CodexPatchAppliedEvent | CodexItemCompletedEvent | CodexBackgroundEvent | CodexGenericEvent;
 export interface CodexTurnStartedEvent {
     type: 'turn_started';
     turn_id?: string;
@@ -264,6 +307,28 @@ export interface CodexPatchAppliedEvent {
     additions?: number;
     deletions?: number;
 }
+/**
+ * A completed turn item. `SubAgentActivity` items record the multi-agent
+ * lifecycle: `kind` `started` (id = the spawn call), `completed` (id =
+ * `subagent-completed-<child turn id>`), `interacted` (id = a
+ * `followup_task` / `send_message` call), `interrupted` (id = an
+ * `interrupt_agent` call).
+ */
+export interface CodexItemCompletedEvent {
+    type: 'item_completed';
+    thread_id?: string;
+    turn_id?: string;
+    item?: {
+        type?: string;
+        id?: string;
+        kind?: string;
+        agent_thread_id?: string;
+        agent_path?: string;
+        model?: string | null;
+        reasoning_effort?: string | null;
+        [key: string]: unknown;
+    };
+}
 export interface CodexBackgroundEvent {
     type: 'background';
     message?: string;
@@ -291,6 +356,10 @@ export interface CodexDbThread {
     source?: string;
     agent_nickname?: string | null;
     agent_role?: string | null;
+    /** Subagents: agent path, e.g. `/root/review_builder` (recent schemas). */
+    agent_path?: string | null;
+    /** `user`, `subagent`, … (recent schemas). */
+    thread_source?: string | null;
     /** 1 once the thread is archived; Codex then moves its rollout to `archived_sessions/`. */
     archived?: number;
     /** Unix seconds when the thread was archived. */