yepanywhere 0.5.2 → 0.6.0

package/dist/sdk/providers/codex.js

@@ -9,11 +9,13 @@ import { homedir } from "node:os";
 import { promisify } from "node:util";
 import { HELPER_SIDE_MODEL_CHEAPEST, } from "../../../bundled/@yep-anywhere/shared/dist/index.js";
 import { isCodexCorrelationDebugEnabled, logCodexCorrelationDebug, summarizeCodexNormalizedMessage, } from "../../codex/correlationDebugLogger.js";
-import { canonicalizeCodexToolName, isCodexBackgroundProcessOutput, isCodexInterruptedToolOutput, normalizeCodexCommandExecutionOutput, normalizeCodexToolInvocation, normalizeCodexToolOutputWithContext, parseCodexToolArguments, } from "../../codex/normalization.js";
+import { canonicalizeCodexToolName, isCodexBackgroundProcessOutput, isCodexInterruptedToolOutput, normalizeCodexCommandActionInvocation, normalizeCodexCommandExecutionOutput, normalizeCodexToolInvocation, normalizeCodexToolOutputWithContext, parseCodexToolArguments, } from "../../codex/normalization.js";
 import { getLogger } from "../../logging/logger.js";
 import { findCodexCliPath } from "../cli-detection.js";
 import { logSDKMessage } from "../messageLogger.js";
 import { MessageQueue } from "../messageQueue.js";
+import { createAgentctlSessionEnvBridge } from "./agentctl-session-env.js";
+import { CODEX_BUILTIN_COMMANDS } from "./staticSlashCommands.js";
 const log = getLogger().child({ component: "codex-provider" });
 const execFileAsync = promisify(execFile);
 function logSdkCorrelationDebug(sessionId, message, metadata = {}) {
@@ -58,13 +60,14 @@ const CODEX_CLI_GPT55_MIN_VERSION = "0.124.0";
 const CODEX_FAILURE_TRACE_LIMIT = 12;
 const CODEX_FAILURE_PREVIEW_CHARS = 240;
 const CODEX_RECAP_TIMEOUT_MS = 20_000;
+const CODEX_SUMMARY_TIMEOUT_MS = 60_000;
 const CODEX_RECAP_MAX_TOTAL_CHARS = 6000;
 const CODEX_RECAP_CHEAPEST_MODEL_PREFERENCES = [
     "gpt-5.4-mini",
     "gpt-5.1-codex-mini",
     "gpt-5.3-codex-spark",
 ];
-const CODEX_DISABLE_LIVE_DELTAS_ENV = "YA_CODEX_DISABLE_LIVE_DELTAS";
+const CODEX_DISABLE_LIVE_DELTAS_ENV = "YEP_CODEX_DISABLE_LIVE_DELTAS";
 const CODEX_LIVE_DELTA_NOTIFICATION_METHODS = new Set([
     "item/agentMessage/delta",
     "item/plan/delta",
@@ -78,13 +81,6 @@ function isCodexLiveDeltaSuppressionEnabled() {
 function isCodexLiveDeltaNotificationMethod(method) {
     return CODEX_LIVE_DELTA_NOTIFICATION_METHODS.has(method);
 }
-const CODEX_BUILTIN_COMMANDS = [
-    {
-        name: "goal",
-        description: "Keep working toward a verifiable end state until it is met",
-        argumentHint: "<verifiable end state>",
-    },
-];
 const CODEX_THINKING_OFF_MIN_REASONING_EFFORT_PREFIXES = [
     "gpt-5.3-codex-spark",
 ];
@@ -100,10 +96,12 @@ const CODEX_POLICY_OVERRIDES = {
     sandbox: null,
 };
 /**
- * When enabled, declare Codex session originator as "Codex Desktop"
- * when initializing app-server sessions.
+ * When enabled, declare Codex session originator as "Codex Desktop" when
+ * initializing app-server sessions. Disabled by default so we report
+ * "yep-anywhere" as the originator, making Yep Anywhere usage visible in the
+ * Codex/ChatGPT token-usage UI.
  */
-const DECLARE_CODEX_ORIGINATOR = true;
+const DECLARE_CODEX_ORIGINATOR = false;
 const DECLARED_CODEX_ORIGINATOR = "Codex Desktop";
 const YEP_ANYWHERE_ORIGINATOR = "yep-anywhere";
 const PREFERRED_MODEL_ORDER = [
@@ -269,7 +267,21 @@ async function terminateChildProcess(child, graceMs = APP_SERVER_SHUTDOWN_GRACE_
     const exited = new Promise((resolve) => {
         child.once("exit", () => resolve());
     });
-    const killTarget = process.platform !== "win32" && child.pid > 0 ? -child.pid : child.pid;
+    if (process.platform === "win32") {
+        const taskkill = new Promise((resolve) => {
+            execFile("taskkill", ["/pid", String(child.pid), "/T", "/F"], () => resolve());
+        });
+        await Promise.race([
+            taskkill,
+            new Promise((resolve) => setTimeout(resolve, graceMs)),
+        ]);
+        await Promise.race([
+            exited,
+            new Promise((resolve) => setTimeout(resolve, 100)),
+        ]);
+        return;
+    }
+    const killTarget = child.pid > 0 ? -child.pid : child.pid;
     try {
         process.kill(killTarget, "SIGTERM");
     }
@@ -356,6 +368,7 @@ class CodexAppServerClient {
     shouldSuppressNotification;
     process = null;
     stdoutBuffer = "";
+    closePromise = null;
     /** OS PID of the spawned app-server child process */
     get pid() {
         return this.process?.pid;
@@ -553,7 +566,10 @@ class CodexAppServerClient {
     async nextNotification(signal) {
         return await this.notifications.shift(signal);
     }
-    close() {
+    async close() {
+        if (this.closePromise) {
+            return await this.closePromise;
+        }
         if (this.closed)
             return;
         this.closed = true;
@@ -565,7 +581,8 @@ class CodexAppServerClient {
         this.notifications.close(closeError);
         const child = this.process;
         this.process = null;
-        void terminateChildProcess(child);
+        this.closePromise = terminateChildProcess(child);
+        await this.closePromise;
     }
     handleProcessClose(error) {
         if (this.closed)
@@ -1091,8 +1108,78 @@ export class CodexProvider {
                 });
                 return true;
             },
+            runProviderCommand: async (command) => {
+                // Only `/compact` is dispatched natively; every other slash command
+                // falls through to ordinary turn delivery.
+                const name = command.trim().replace(/^\/+/, "").toLowerCase();
+                if (name !== "compact") {
+                    return { handled: false };
+                }
+                // Codex compaction takes no instructions, so any trailing argument is
+                // intentionally dropped here — there is no app-server surface for it.
+                if (!activeClient || !runtimeState.threadId) {
+                    return {
+                        handled: true,
+                        error: "Codex session is not ready for compaction yet",
+                    };
+                }
+                // A compact runs as its own (non-steerable) turn; refuse mid-turn so we
+                // do not collide with active work or send `/compact` as plain text.
+                if (runtimeState.activeTurnId) {
+                    return {
+                        handled: true,
+                        error: "Cannot compact while a turn is in progress",
+                    };
+                }
+                try {
+                    await activeClient.request("thread/compact/start", {
+                        threadId: runtimeState.threadId,
+                    });
+                    return { handled: true };
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    log.warn({ threadId: runtimeState.threadId, error: message }, "Codex thread/compact/start failed");
+                    return { handled: true, error: message };
+                }
+            },
         };
     }
+    async forkSession(options) {
+        const codexCommand = await this.resolveCodexCommand();
+        const appServer = new CodexAppServerClient(codexCommand, options.cwd, this.getCodexEnv());
+        appServer.setServerRequestHandler((request) => this.handleForkServerRequest(request));
+        try {
+            await appServer.connect();
+            const experimentalApiEnabled = await this.initializeAppServer(appServer);
+            appServer.notify("initialized");
+            const rollbackCount = options.upToMessageId
+                ? await this.resolveCodexForkRollbackCount(appServer, options.sessionId, options.upToMessageId)
+                : 0;
+            const policy = this.mapPermissionModeToThreadPolicy(undefined);
+            const fork = await appServer.request("thread/fork", this.createThreadForkParams(options, policy, experimentalApiEnabled));
+            const forkSessionId = fork.thread?.id;
+            if (!forkSessionId) {
+                throw new Error("Codex thread/fork did not return a thread id");
+            }
+            if (rollbackCount > 0) {
+                await appServer.request("thread/rollback", {
+                    threadId: forkSessionId,
+                    numTurns: rollbackCount,
+                });
+            }
+            log.info({
+                sourceSessionId: options.sessionId,
+                forkSessionId,
+                upToMessageId: options.upToMessageId ?? null,
+                rollbackCount,
+            }, "Forked Codex app-server thread");
+            return { sessionId: forkSessionId };
+        }
+        finally {
+            await appServer.close();
+        }
+    }
     async probeCodexLiveness(activeClient, runtimeState) {
         const checkedAt = new Date();
         const source = "codex:thread/read";
@@ -1117,7 +1204,9 @@ export class CodexProvider {
                 threadId: runtimeState.threadId,
                 includeTurns: false,
             });
-            const status = response.thread?.status;
+            const status = response.thread?.status && typeof response.thread.status === "object"
+                ? response.thread.status
+                : null;
             const statusType = status?.type;
             const activeFlags = Array.isArray(status?.activeFlags)
                 ? status.activeFlags.filter((flag) => typeof flag === "string")
@@ -1186,7 +1275,17 @@ export class CodexProvider {
      */
     async *runSession(options, queue, signal, runtimeState, setActiveClient) {
         const codexCommand = await this.resolveCodexCommand();
-        const appServer = new CodexAppServerClient(codexCommand, options.cwd, this.getCodexEnv(), (notification) => this.shouldSuppressLiveDeltaNotification(notification, options));
+        const agentctlSessionEnvBridge = createAgentctlSessionEnvBridge(options.resumeSessionId);
+        const codexEnv = agentctlSessionEnvBridge.extendEnv(this.getCodexEnv());
+        if (options.resumeSessionId) {
+            // The bridge only reaches bash tool shells that source BASH_ENV, which
+            // codex's sandbox may strip. For resume the id is known at spawn, so set
+            // it directly in the app-server env too; every shell codex launches
+            // inherits it regardless of BASH_ENV. New sessions (id unknown until
+            // thread/start) stay on the bridge alone.
+            codexEnv.AGENTCTL_SESSION_ID = options.resumeSessionId;
+        }
+        const appServer = new CodexAppServerClient(codexCommand, options.cwd, codexEnv, (notification) => this.shouldSuppressLiveDeltaNotification(notification, options));
         setActiveClient(appServer);
         let sessionId = options.resumeSessionId ?? "";
         const usageByTurnId = new Map();
@@ -1210,6 +1309,7 @@ export class CodexProvider {
             const threadStartParams = this.createThreadStartParams(options, policy);
             const threadResult = await this.startOrResumeThread(appServer, options, threadStartParams, threadResumeParams);
             sessionId = threadResult.thread.id;
+            agentctlSessionEnvBridge.publishSessionId(sessionId);
             runtimeState.threadId = sessionId;
             failureTrace.sessionId = sessionId;
             log.info({
@@ -1366,7 +1466,8 @@ export class CodexProvider {
         }
         finally {
             runtimeState.activeTurnId = null;
-            appServer.close();
+            await appServer.close();
+            agentctlSessionEnvBridge.cleanup();
         }
         yield {
             type: "result",
@@ -1483,7 +1584,6 @@ export class CodexProvider {
             ...this.buildThreadPermissionParams(policy),
             config: this.buildThreadConfigOverrides(options),
             experimentalRawEvents: false,
-            persistExtendedHistory: false,
         };
     }
     createThreadResumeParams(options, sessionId, policy, experimentalApiEnabled = false) {
@@ -1494,13 +1594,78 @@ export class CodexProvider {
             cwd: options.cwd,
             ...this.buildThreadPermissionParams(policy),
             config: this.buildThreadConfigOverrides(options),
-            persistExtendedHistory: false,
         };
         if (experimentalApiEnabled) {
             params.excludeTurns = true;
         }
         return params;
     }
+    createThreadForkParams(options, policy, experimentalApiEnabled = false) {
+        const params = {
+            threadId: options.sessionId,
+            cwd: options.cwd,
+            ...this.buildThreadPermissionParams(policy),
+            config: null,
+        };
+        if (experimentalApiEnabled) {
+            params.excludeTurns = true;
+        }
+        return params;
+    }
+    async resolveCodexForkRollbackCount(appServer, sessionId, upToMessageId) {
+        const response = await appServer.request("thread/read", {
+            threadId: sessionId,
+            includeTurns: true,
+        });
+        const turns = response.thread.turns ?? [];
+        return this.computeCodexForkRollbackCount(turns, upToMessageId);
+    }
+    computeCodexForkRollbackCount(turns, upToMessageId) {
+        const anchor = this.findCodexForkAnchor(turns, upToMessageId);
+        if (!anchor) {
+            throw new Error(`Codex fork anchor ${upToMessageId} was not found in source thread`);
+        }
+        if (anchor.itemIndex !== null) {
+            const turn = turns[anchor.turnIndex];
+            if (!turn) {
+                throw new Error(`Codex fork anchor ${upToMessageId} resolved to a missing turn`);
+            }
+            if (anchor.itemIndex < turn.items.length - 1) {
+                throw new Error(`Codex fork anchor ${upToMessageId} is inside a turn; Codex can only fork at completed turn boundaries`);
+            }
+        }
+        return turns.length - anchor.turnIndex - 1;
+    }
+    findCodexForkAnchor(turns, upToMessageId) {
+        for (const [turnIndex, turn] of turns.entries()) {
+            if (turn.id === upToMessageId ||
+                `codex-turn-interrupted-${turn.id}` === upToMessageId) {
+                return { turnIndex, itemIndex: null };
+            }
+            for (const [itemIndex, item] of turn.items.entries()) {
+                if (this.codexItemMatchesForkAnchor(item, turn.id, upToMessageId)) {
+                    return { turnIndex, itemIndex };
+                }
+            }
+            if (`codex-compaction-${turn.id}` === upToMessageId) {
+                return { turnIndex, itemIndex: turn.items.length - 1 };
+            }
+        }
+        return null;
+    }
+    codexItemMatchesForkAnchor(item, turnId, upToMessageId) {
+        const candidates = new Set();
+        candidates.add(item.id);
+        candidates.add(`${item.id}-${turnId}`);
+        candidates.add(`${item.id}-result`);
+        const itemRecord = item;
+        const clientId = this.getOptionalString(itemRecord.clientId);
+        if (clientId) {
+            candidates.add(clientId);
+            candidates.add(`${clientId}-${turnId}`);
+        }
+        return candidates.has(upToMessageId);
+    }
     buildThreadPermissionParams(policy) {
         return {
             approvalPolicy: policy.approvalPolicy,
@@ -1536,9 +1701,19 @@ export class CodexProvider {
      * not natively emit prompt_suggestion messages, but it can still run the YA
      * simulated recap helper without mutating the parent session transcript.
      */
-    async generateRecap(recentAssistantText, options) {
+    async generateSummary(request) {
+        switch (request.strategy) {
+            case "side-session": {
+                const text = await this.generateSideSessionRecap(request.recentAssistantText, request.model);
+                return { text };
+            }
+            case "fork":
+                return await this.generateForkBackedSummary(request);
+        }
+    }
+    async generateSideSessionRecap(recentAssistantText, requestedModel) {
         const userPrompt = this.createRecapPrompt(recentAssistantText);
-        const model = await this.resolveRecapHelperModel(options?.model);
+        const model = await this.resolveRecapHelperModel(requestedModel);
         const codexCommand = await this.resolveCodexCommand();
         const abortController = new AbortController();
         let timedOut = false;
@@ -1560,7 +1735,6 @@ export class CodexProvider {
                 sandbox: "read-only",
                 ephemeral: true,
                 experimentalRawEvents: false,
-                persistExtendedHistory: false,
                 developerInstructions: "You are a recap helper. Reply with the recap text only, no preamble. Do not call tools.",
             });
             const turnResult = await appServer.request("turn/start", {
@@ -1609,7 +1783,7 @@ export class CodexProvider {
         finally {
             clearTimeout(timeout);
             abortController.abort();
-            appServer.close();
+            await appServer.close();
         }
     }
     createRecapPrompt(recentAssistantText) {
@@ -1646,6 +1820,174 @@ export class CodexProvider {
             transcript,
         ].join("\n");
     }
+    async generateForkBackedSummary(request) {
+        const userPrompt = request.purpose === "session-retitle"
+            ? this.createSessionRetitlePrompt(request)
+            : request.purpose === "recap"
+                ? this.createForkedRecapPrompt()
+                : this.createForkAfterSummaryPrompt(request);
+        const codexCommand = await this.resolveCodexCommand();
+        const appServer = new CodexAppServerClient(codexCommand, request.cwd, this.getCodexEnv());
+        const abortController = new AbortController();
+        let timedOut = false;
+        const abortFromRequest = () => {
+            abortController.abort();
+            void appServer.close();
+        };
+        if (request.signal?.aborted) {
+            abortController.abort();
+        }
+        else {
+            request.signal?.addEventListener("abort", abortFromRequest, {
+                once: true,
+            });
+        }
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            abortController.abort();
+            void appServer.close();
+        }, CODEX_SUMMARY_TIMEOUT_MS);
+        timeout.unref?.();
+        appServer.setServerRequestHandler((serverRequest) => this.handleNonTurnServerRequest(serverRequest, "summary helper"));
+        try {
+            if (abortController.signal.aborted) {
+                throw new DOMException("Summary generation cancelled", "AbortError");
+            }
+            await appServer.connect();
+            const experimentalApiEnabled = await this.initializeAppServer(appServer);
+            appServer.notify("initialized");
+            const threadResult = await appServer.request("thread/resume", this.createForkSummaryThreadResumeParams(request, experimentalApiEnabled));
+            const threadId = threadResult.thread.id || request.generatorSessionId;
+            const turnResult = await appServer.request("turn/start", {
+                threadId,
+                input: [{ type: "text", text: userPrompt, text_elements: [] }],
+                effort: "low",
+                summary: "auto",
+                approvalPolicy: "untrusted",
+            });
+            const textByItemId = new Map();
+            this.captureRecapTextFromTurnItems(turnResult.turn.items, textByItemId);
+            if (turnResult.turn.status === "failed") {
+                throw new Error(turnResult.turn.error?.message ?? "Codex summary generation failed");
+            }
+            const turnId = turnResult.turn.id;
+            let turnComplete = turnResult.turn.status !== "inProgress";
+            while (!turnComplete && !abortController.signal.aborted) {
+                const notification = await appServer.nextNotification(abortController.signal);
+                this.captureRecapTextFromNotification(notification, textByItemId);
+                if (notification.method === "turn/completed") {
+                    const completed = this.asTurnCompletedNotification(notification.params);
+                    if (completed?.turn.id !== turnId) {
+                        continue;
+                    }
+                    this.captureRecapTextFromTurnItems(completed.turn.items, textByItemId);
+                    if (completed.turn.status === "failed") {
+                        throw new Error(completed.turn.error?.message ??
+                            "Codex summary generation failed");
+                    }
+                    turnComplete = true;
+                    continue;
+                }
+                if (notification.method === "error") {
+                    const error = this.asErrorNotification(notification.params);
+                    if (error?.turnId === turnId && !error.willRetry) {
+                        throw new Error(error.error.message ?? "Codex summary generation failed");
+                    }
+                }
+            }
+            if (abortController.signal.aborted) {
+                if (request.signal?.aborted) {
+                    throw new DOMException("Summary generation cancelled", "AbortError");
+                }
+                throw new Error("Timed out generating Codex summary");
+            }
+            const cleaned = [...textByItemId.values()].join("\n").trim();
+            if (!cleaned) {
+                throw new Error("Summary generation returned empty text");
+            }
+            return { text: cleaned };
+        }
+        catch (error) {
+            if (request.signal?.aborted) {
+                throw new DOMException("Summary generation cancelled", "AbortError");
+            }
+            if (timedOut) {
+                throw new Error("Timed out generating Codex summary");
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+            request.signal?.removeEventListener("abort", abortFromRequest);
+            abortController.abort();
+            await appServer.close();
+        }
+    }
+    createForkSummaryThreadResumeParams(request, experimentalApiEnabled = false) {
+        const params = {
+            threadId: request.generatorSessionId,
+            model: null,
+            cwd: request.cwd,
+            approvalPolicy: "untrusted",
+            sandbox: "read-only",
+            config: null,
+            developerInstructions: request.purpose === "session-retitle"
+                ? "You are a title helper. Reply with the session title only, no preamble. Do not call tools."
+                : request.purpose === "recap"
+                    ? "You are a recap helper. Reply with the recap text only, no preamble. Do not call tools."
+                    : "You are a handoff summary helper. Reply with the summary text only, no preamble. Do not call tools.",
+        };
+        if (experimentalApiEnabled) {
+            params.excludeTurns = true;
+        }
+        return params;
+    }
+    createForkAfterSummaryPrompt(request) {
+        const instructions = request.instructions?.trim();
+        const boundaryContext = request.afterTurnContext?.trim();
+        return [
+            "The first non-empty line must be a concise title of at most 120 characters, with no trailing period.",
+            "Write it as: Title: <title>",
+            "Then leave one blank line before the handoff summary.",
+            "",
+            "Summarize the useful state after the retained fork boundary for a peer-agent handoff.",
+            `The target fork retains the conversation through completed-turn message id ${request.afterTurnMessageId}.`,
+            boundaryContext
+                ? `The retained boundary is the completed turn ending with this excerpt:\n${boundaryContext}`
+                : undefined,
+            "The target fork already includes the original request and the assistant/tool work through that selected completed turn.",
+            "Do not repeat setup, instruction loading, initial repository orientation, or investigation already present in that retained prefix.",
+            "Preserve decisions, constraints, current state, changed files, verification evidence, open risks, and the next useful action.",
+            "Do not continue the task. Write text that can be submitted as the next user turn in the target fork.",
+            instructions ? "" : undefined,
+            instructions ? "Additional user instructions:" : undefined,
+            instructions || undefined,
+        ]
+            .filter((part) => part !== undefined)
+            .join("\n");
+    }
+    createForkedRecapPrompt() {
+        return [
+            "The user stepped away and is coming back.",
+            "Recap the current session state in under 40 words, 1-2 plain sentences, no markdown.",
+            "Lead with what the assistant did or is doing; mention any pending next action.",
+            "Do not greet, do not ask a question, do not add a sign-off.",
+        ].join("\n");
+    }
+    createSessionRetitlePrompt(request) {
+        const lengthTarget = request.lengthTarget ?? 80;
+        const currentTitle = request.currentTitle?.trim();
+        return [
+            "What is a good new title for this session?",
+            "",
+            `Target length: under ${lengthTarget} characters.`,
+            currentTitle ? `Current title: ${currentTitle}` : undefined,
+            "Prefer a concrete task/result phrase over a generic chat title.",
+            "Return only the title. Do not quote it. Do not add a trailing period.",
+        ]
+            .filter((part) => part !== undefined)
+            .join("\n");
+    }
     async resolveRecapHelperModel(requestedModel) {
         if (!requestedModel || requestedModel !== HELPER_SIDE_MODEL_CHEAPEST) {
             return requestedModel ?? null;
@@ -1660,7 +2002,13 @@ export class CodexProvider {
             null);
     }
     handleRecapServerRequest(request) {
-        log.warn({ method: request.method, requestId: request.id }, "Declining Codex recap helper server request");
+        return this.handleNonTurnServerRequest(request, "recap helper");
+    }
+    handleForkServerRequest(request) {
+        return this.handleNonTurnServerRequest(request, "fork");
+    }
+    handleNonTurnServerRequest(request, purpose) {
+        log.warn({ method: request.method, requestId: request.id, purpose }, "Declining Codex non-turn server request");
         switch (request.method) {
             case "item/commandExecution/requestApproval":
             case "item/fileChange/requestApproval":
@@ -2532,6 +2880,11 @@ export class CodexProvider {
                 return { id, type: "agent_message", text };
             }
             case "command_execution": {
+                const commandActions = (Array.isArray(itemRecord.commandActions)
+                    ? itemRecord.commandActions
+                    : Array.isArray(itemRecord.command_actions)
+                        ? itemRecord.command_actions
+                        : undefined) ?? undefined;
                 return {
                     id,
                     type: "command_execution",
@@ -2543,6 +2896,7 @@ export class CodexProvider {
                         this.getOptionalNumber(itemRecord.exitCode) ??
                         undefined,
                     status: this.normalizeStatus(itemRecord.status),
+                    ...(commandActions ? { commandActions } : {}),
                 };
             }
             case "file_change": {
@@ -2650,6 +3004,18 @@ export class CodexProvider {
                     items,
                 };
             }
+            case "sub_agent_activity": {
+                const kind = this.getOptionalString(itemRecord.kind) ?? "updated";
+                const agentPath = this.getOptionalString(itemRecord.agentPath) ?? "";
+                return {
+                    id,
+                    type: "subagent_activity",
+                    kind,
+                    agentThreadId: this.getOptionalString(itemRecord.agentThreadId) ?? "",
+                    agentPath,
+                    text: this.formatSubagentActivity(kind, agentPath),
+                };
+            }
             case "context_compaction":
                 return { id, type: "context_compaction" };
             case "image_view": {
@@ -2688,6 +3054,19 @@ export class CodexProvider {
         }
         return "";
     }
+    formatSubagentActivity(kind, agentPath) {
+        const target = agentPath ? `: ${agentPath}` : "";
+        switch (kind) {
+            case "started":
+                return `Subagent started${target}`;
+            case "interacted":
+                return `Subagent updated${target}`;
+            case "interrupted":
+                return `Subagent interrupted${target}`;
+            default:
+                return `Subagent ${kind}${target}`;
+        }
+    }
     normalizeStatus(status) {
         if (typeof status !== "string")
             return "unknown";
@@ -2891,8 +3270,17 @@ export class CodexProvider {
     buildItemMessageUuid(turnId, itemId) {
         return `${itemId}-${turnId}`;
     }
-    buildItemResultUuid(turnId, itemId) {
-        return `${this.buildItemMessageUuid(turnId, itemId)}-result`;
+    // Tool items carry Codex's globally-unique call_id as their thread item id,
+    // and the durable rollout persists the same call_id on the matching response
+    // item. Key the rendered uuid on call_id alone (no turn scoping — call_id is
+    // already unique) so the streamed message and its durable backfill row share
+    // a uuid and dedup by id instead of the content+timestamp backstop. See
+    // topics/stream-durable-id-dedup.md (Codex tool calls).
+    buildItemToolUuid(callId) {
+        return callId;
+    }
+    buildItemResultUuid(callId) {
+        return `${callId}-result`;
     }
     isResultBackedThreadItem(item) {
         return (item.type === "command_execution" ||
@@ -2901,6 +3289,12 @@ export class CodexProvider {
             item.type === "dynamic_tool_call" ||
             item.type === "image_view");
     }
+    // Thread items whose rendered uuid keys on call_id (item.id) so the streamed
+    // message matches its durable backfill row. web_search emits a tool_use but is
+    // not result-backed, so it is not covered by isResultBackedThreadItem.
+    isToolBackedThreadItem(item) {
+        return this.isResultBackedThreadItem(item) || item.type === "web_search";
+    }
     recordLiveResultBackedToolItem(liveEventState, turnId, itemId) {
         const items = liveEventState.resultBackedToolItemsByTurnId.get(turnId) ?? new Set();
         items.add(itemId);
@@ -2977,7 +3371,7 @@ export class CodexProvider {
         const message = withCodexTimestamp({
             type: "user",
             session_id: sessionId,
-            uuid: this.buildItemResultUuid(turnId, itemId),
+            uuid: this.buildItemResultUuid(itemId),
             _isStreaming: true,
             message: {
                 role: "user",
@@ -3030,7 +3424,7 @@ export class CodexProvider {
                 const message = withCodexTimestamp({
                     type: "assistant",
                     session_id: sessionId,
-                    uuid: this.buildItemMessageUuid(params.turnId, callId),
+                    uuid: this.buildItemToolUuid(callId),
                     message: {
                         role: "assistant",
                         content: [
@@ -3074,7 +3468,7 @@ export class CodexProvider {
                 const message = withCodexTimestamp({
                     type: "user",
                     session_id: sessionId,
-                    uuid: this.buildItemResultUuid(params.turnId, callId),
+                    uuid: this.buildItemResultUuid(callId),
                     message: {
                         role: "user",
                         content: [toolResult],
@@ -3110,7 +3504,7 @@ export class CodexProvider {
                 const message = withCodexTimestamp({
                     type: "assistant",
                     session_id: sessionId,
-                    uuid: this.buildItemMessageUuid(params.turnId, callId),
+                    uuid: this.buildItemToolUuid(callId),
                     message: {
                         role: "assistant",
                         content: [
@@ -3154,7 +3548,7 @@ export class CodexProvider {
                 const message = withCodexTimestamp({
                     type: "user",
                     session_id: sessionId,
-                    uuid: this.buildItemResultUuid(params.turnId, callId),
+                    uuid: this.buildItemResultUuid(callId),
                     message: {
                         role: "user",
                         content: [toolResult],
@@ -3200,8 +3594,12 @@ export class CodexProvider {
     convertItemToSDKMessages(item, sessionId, turnId, sourceEvent) {
         const isComplete = sourceEvent === "item/completed";
         const observedAt = new Date().toISOString();
-        // Create unique UUID by combining item.id with turn ID.
-        const uuid = `${item.id}-${turnId}`;
+        // Tool items key the uuid on call_id (item.id) so stream and durable rows
+        // dedup by id; message/reasoning items use a counter id (item-N) with no
+        // durable equivalent, so they stay turn-scoped and rely on the backstop.
+        const uuid = this.isToolBackedThreadItem(item)
+            ? this.buildItemToolUuid(item.id)
+            : `${item.id}-${turnId}`;
         switch (item.type) {
             case "reasoning": {
                 const message = withCodexTimestamp({
@@ -3248,9 +3646,10 @@ export class CodexProvider {
             }
             case "command_execution": {
                 const messages = [];
-                const normalizedInvocation = normalizeCodexToolInvocation("Bash", {
-                    command: item.command,
-                });
+                const normalizedInvocation = normalizeCodexCommandActionInvocation(item.command, item.commandActions) ??
+                    normalizeCodexToolInvocation("Bash", {
+                        command: item.command,
+                    });
                 const toolContext = {
                     toolName: normalizedInvocation.toolName,
                     input: normalizedInvocation.input,
@@ -3566,6 +3965,26 @@ export class CodexProvider {
                 });
                 return [message];
             }
+            case "subagent_activity": {
+                const message = withCodexTimestamp({
+                    type: "system",
+                    subtype: "subagent_activity",
+                    session_id: sessionId,
+                    uuid,
+                    content: item.text,
+                    codexSubagentKind: item.kind,
+                    codexSubagentThreadId: item.agentThreadId,
+                    codexSubagentPath: item.agentPath,
+                }, observedAt);
+                logSdkCorrelationDebug(sessionId, message, {
+                    eventKind: "subagent_activity",
+                    turnId,
+                    itemId: item.id,
+                    phase: isComplete ? "completed" : "started",
+                    sourceEvent,
+                });
+                return [message];
+            }
             case "context_compaction": {
                 const message = withCodexTimestamp({
                     type: "system",
@@ -3690,6 +4109,7 @@ export class CodexProvider {
             case "acceptEdits":
             case "plan":
             case "bypassPermissions":
+            case "auto":
                 return mode;
             default:
                 return undefined;