@agentex/agent 0.0.32 → 0.0.34

package/dist/providers/codex/session.js

@@ -89,6 +89,8 @@ function buildCodexUserInputAnswers(questions, resp) {
     }
     return out;
 }
+const BACKGROUND_TASK_POLL_INTERVAL_MS = 2_000;
+const BACKGROUND_TASK_READ_TIMEOUT_MS = 5_000;
 // ---------------------------------------------------------------------------
 // JSON-RPC 2.0 helpers
 // ---------------------------------------------------------------------------
@@ -116,6 +118,30 @@ function asObj(parent, key) {
         ? v
         : {};
 }
+function obj(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string" && entry.length > 0)
+        : [];
+}
+function codexAgentState(value) {
+    const state = obj(value);
+    const nativeStatus = str(state, "status");
+    const summary = str(state, "message") || null;
+    if (nativeStatus === "completed")
+        return { terminal: true, status: "completed", summary };
+    if (nativeStatus === "errored" || nativeStatus === "notFound") {
+        return { terminal: true, status: "failed", summary };
+    }
+    if (nativeStatus === "interrupted" || nativeStatus === "shutdown") {
+        return { terminal: true, status: "stopped", summary };
+    }
+    return { terminal: false, status: "running", summary };
+}
 function classifyMessage(msg) {
     // Detect JSON-RPC by *structure*, not by the `jsonrpc:"2.0"` discriminator.
     // codex-cli 0.130.0's `app-server` emits responses without the `jsonrpc`
@@ -271,6 +297,18 @@ export class CodexSessionImpl {
     _draining = false;
     /** Shared promise so concurrent / repeated `drain()` calls coalesce. */
     _drainPromise = null;
+    /**
+     * Root turn targeted by `interrupt()`. The id is learned asynchronously from
+     * the leader `turn/start` response or the root `turn/started` notification.
+     * Concurrent sends reuse this latch so a queued response cannot replace the
+     * actual active turn.
+     */
+    _activeTurnId = null;
+    _activeTurnReady = null;
+    /** Successful repeated interrupts coalesce until the terminal notification. */
+    _interruptPromise = null;
+    /** Prevents a late interrupt request after the terminal frame was observed. */
+    _turnTerminalObserved = false;
     /** Stamps `tool_result.toolName` by correlating with prior `tool_call`s. */
     _trackToolName = createToolNameTracker();
     // Per-turn accumulators. Cleared after each result delivery so a subsequent
@@ -279,8 +317,16 @@ export class CodexSessionImpl {
     _turnUsage = null;
     _turnModel = null;
     _turnIsError = false;
+    _turnWasInterrupted = false;
     _turnErrorMessage = null;
     _turnStartedAt = null;
+    /** Child-agent lifecycle is informational and never participates in root turn settlement. */
+    _backgroundTasks = new Map();
+    _backgroundTaskIdsByPath = new Map();
+    /** One protocol-native thread/read poller per child when Codex does not multiplex its notifications. */
+    _backgroundTaskPollers = new Map();
+    /** Cancellable retry delay for each poller. Cleared when the session closes. */
+    _backgroundTaskPollTimers = new Map();
     /**
      * Serial dispatch chain for `onEvent`. Each dispatched event appends a
      * handler invocation; the chain enforces in-order delivery and lets
@@ -348,17 +394,51 @@ export class CodexSessionImpl {
         proc.on("exit", (code, signal) => {
             if (this._state !== "closed") {
                 this._state = "closed";
-                const err = new Error(`Codex process exited unexpectedly (code=${code}, signal=${signal})`);
+                const message = `Codex process exited unexpectedly (code=${code}, signal=${signal})`;
+                this.finalizeActiveBackgroundTasks("failed", message, {
+                    method: "process/exit",
+                    code,
+                    signal,
+                });
+                this.cancelBackgroundTaskPollTimers();
+                const err = new Error(message);
                 this.rejectAllPending(err);
             }
         });
         proc.on("error", (err) => {
             if (this._state !== "closed") {
                 this._state = "closed";
+                this.finalizeActiveBackgroundTasks("failed", err.message, {
+                    method: "process/error",
+                    message: err.message,
+                });
+                this.cancelBackgroundTaskPollTimers();
                 this.rejectAllPending(err);
             }
         });
     }
+    cancelBackgroundTaskPollTimers() {
+        for (const pending of this._backgroundTaskPollTimers.values()) {
+            clearTimeout(pending.timer);
+            pending.resolve();
+        }
+        this._backgroundTaskPollTimers.clear();
+    }
+    finalizeActiveBackgroundTasks(status, summary, raw) {
+        for (const task of this._backgroundTasks.values()) {
+            if (task.terminal)
+                continue;
+            this.dispatchEvent(this.backgroundTaskEvent(task.taskId, "completed", status, {
+                description: task.description,
+                summary,
+                parentTaskId: task.parentTaskId,
+                eventId: this._threadId
+                    ? `codex:${this._threadId}:background-task:${task.taskId}:session-${status}:completed`
+                    : null,
+                raw,
+            }));
+        }
+    }
     /** Reject every pending send() Promise and outgoing JSON-RPC call. */
     rejectAllPending(err) {
         const pending = this._pendingResults.splice(0);
@@ -372,9 +452,75 @@ export class CodexSessionImpl {
         for (const [, p] of this._pendingRpc)
             p.reject(err);
         this._pendingRpc.clear();
+        this.clearActiveTurn(err);
     }
     get sessionId() { return this._threadId; }
     get state() { return this._state; }
+    /** Start the identity latch before writing the leader `turn/start` request. */
+    beginActiveTurn() {
+        let resolveFn;
+        let rejectFn;
+        const promise = new Promise((resolve, reject) => {
+            resolveFn = resolve;
+            rejectFn = reject;
+        });
+        // A turn can finish without anyone calling interrupt(). Keep a later
+        // process-exit rejection from becoming an unhandled promise rejection.
+        void promise.catch(() => { });
+        const ready = {
+            promise,
+            resolve: resolveFn,
+            reject: rejectFn,
+            settled: false,
+        };
+        this._activeTurnId = null;
+        this._activeTurnReady = ready;
+        this._interruptPromise = null;
+        this._turnTerminalObserved = false;
+        this._turnWasInterrupted = false;
+        return ready;
+    }
+    /** First root turn id wins for the current latch. */
+    captureActiveTurnId(turnId, expected) {
+        const ready = this._activeTurnReady;
+        if (!turnId || !ready || ready.settled)
+            return;
+        if (expected && ready !== expected)
+            return;
+        this._activeTurnId = turnId;
+        ready.settled = true;
+        ready.resolve(turnId);
+    }
+    rejectActiveTurnReady(err, expected) {
+        if (this._activeTurnReady !== expected || expected.settled)
+            return;
+        expected.settled = true;
+        expected.reject(err);
+    }
+    /** Clear the current turn and release an interrupt waiting for its id. */
+    clearActiveTurn(err) {
+        const ready = this._activeTurnReady;
+        if (ready && !ready.settled) {
+            ready.settled = true;
+            if (err)
+                ready.reject(err);
+            else
+                ready.resolve(null);
+        }
+        this._activeTurnId = null;
+        this._activeTurnReady = null;
+        this._interruptPromise = null;
+        this._turnTerminalObserved = false;
+    }
+    /** Mark root turn termination and release an interrupt still awaiting its id. */
+    markTurnTerminalObserved() {
+        this._turnTerminalObserved = true;
+        const ready = this._activeTurnReady;
+        if (ready && !ready.settled) {
+            ready.settled = true;
+            ready.resolve(null);
+        }
+    }
     /**
      * Durable identity for persistence + later `attachSession`. Null until Codex
      * has assigned a thread id; serializes `{sessionId, cwd}` through the codec so
@@ -406,6 +552,30 @@ export class CodexSessionImpl {
             this._pendingRpc.set(id, { resolve, reject });
         });
     }
+    /** A bounded RPC whose pending-map entry is removed if Codex never replies. */
+    boundedRpcRequest(method, params, timeoutMs = BACKGROUND_TASK_READ_TIMEOUT_MS) {
+        const id = this._nextId++;
+        this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (!this._pendingRpc.delete(id))
+                    return;
+                reject(new Error(`codex ${method} timed out`));
+            }, timeoutMs);
+            if (typeof timer.unref === "function")
+                timer.unref();
+            this._pendingRpc.set(id, {
+                resolve: (result) => {
+                    clearTimeout(timer);
+                    resolve(result);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            });
+        });
+    }
     /**
      * Bounded RPC for experimental, best-effort methods (the `thread/goal/*`
      * family). An app-server build that doesn't recognize the method may never
@@ -534,6 +704,9 @@ export class CodexSessionImpl {
         // and pass through. If the second `turn/start` lands during the first
         // turn, the per-turn accumulators continue collecting until the result
         // event fires; the result then drains all pending resolvers.
+        const existingTurnReady = this._activeTurnReady;
+        const isTurnLeader = existingTurnReady === null;
+        const turnReady = existingTurnReady ?? this.beginActiveTurn();
         if (this._state === "idle") {
             this._state = "thinking";
             this._turnStartedAt = new Date();
@@ -571,14 +744,30 @@ export class CodexSessionImpl {
         // Per-send timeout / abort, falling back to the session-level
         // ProviderConfig.timeoutSec default when no per-call timeout is given.
         this.armSendDeadline(entry, options);
-        this.rpcRequest("turn/start", turnParams).catch(() => {
-            // Turn-level errors arrive via turn.failed notifications.
-        });
+        const turnStart = this.rpcRequest("turn/start", turnParams);
+        if (isTurnLeader) {
+            void turnStart.then((response) => {
+                const turnId = str(asObj(response, "turn"), "id");
+                if (turnId) {
+                    this.captureActiveTurnId(turnId, turnReady);
+                }
+                // Some app-server versions may omit the id from the response and send
+                // it only in turn/started. Keep the latch open for that notification.
+            }).catch((err) => {
+                this.rejectActiveTurnReady(err instanceof Error ? err : new Error(String(err)), turnReady);
+                // Turn-level failures may also arrive via turn/failed notifications.
+            });
+        }
+        else {
+            void turnStart.catch(() => {
+                // Turn-level failures arrive via turn/failed notifications.
+            });
+        }
         return { uuid, result };
     }
     /**
      * Wire up this send's timeout and/or abort signal. On fire, the active turn
-     * is cancelled (`turn/cancel`) and the send settles with `timeout` /
+     * is interrupted (`turn/interrupt`) and the send settles with `timeout` /
      * `aborted`. No-op when neither a timeout nor a signal applies.
      */
     armSendDeadline(entry, options) {
@@ -621,7 +810,7 @@ export class CodexSessionImpl {
             this._pendingResults.splice(idx, 1);
         // Best-effort cancel of the active turn. With concurrent sends this ends
         // the single shared turn for all of them — see SendOptions JSDoc.
-        void this.interrupt();
+        void this.interrupt().catch(() => { });
         entry.resolve({
             summary: null,
             usage: undefined,
@@ -635,7 +824,7 @@ export class CodexSessionImpl {
     }
     async cancel(_uuid) {
         // Codex's JSON-RPC protocol exposes no per-message cancel — only
-        // turn-wide `turn/cancel` (which is what `interrupt()` calls).
+        // turn-wide `turn/interrupt` (which is what `interrupt()` calls).
         // capabilities.cancelQueuedMessage is false; this is a documented no-op.
         return { cancelled: false };
     }
@@ -689,13 +878,39 @@ export class CodexSessionImpl {
         }
     }
     async interrupt() {
-        if (this._state === "idle" || this._state === "closed")
+        if (this._state === "closed")
             return;
+        const ready = this._activeTurnReady;
+        if (!ready || this._turnTerminalObserved)
+            return;
+        if (this._interruptPromise)
+            return this._interruptPromise;
+        const threadId = this._threadId;
+        if (!threadId) {
+            throw new Error("Cannot interrupt Codex turn before the root thread id is known");
+        }
         this._goals.notifyInterrupted(); // don't let an emulated goal auto-continue
+        const interruptPromise = (async () => {
+            const turnId = this._activeTurnId ?? await ready.promise;
+            // The turn may have completed while interrupt() was waiting for the
+            // leader turn/start response. In that race, completion is the success.
+            if (!turnId || this._activeTurnReady !== ready || this._turnTerminalObserved)
+                return;
+            await this.rpcRequest("turn/interrupt", { threadId, turnId });
+        })();
+        this._interruptPromise = interruptPromise;
         try {
-            await this.rpcRequest("turn/cancel", {});
+            await interruptPromise;
+        }
+        catch (err) {
+            // A rejected control request must reach the host instead of becoming a
+            // false successful Stop. Clear only this turn's failed attempt so a
+            // subsequent click can retry.
+            if (this._activeTurnReady === ready && this._interruptPromise === interruptPromise) {
+                this._interruptPromise = null;
+            }
+            throw err;
         }
-        catch { /* best effort */ }
     }
     async drain() {
         if (this._state === "closed")
@@ -716,6 +931,11 @@ export class CodexSessionImpl {
         if (this._state === "closed")
             return;
         this._state = "closed";
+        this.finalizeActiveBackgroundTasks("stopped", "Codex session closed", {
+            method: "session/closed",
+        });
+        this.cancelBackgroundTaskPollTimers();
+        this.rejectAllPending(new Error("Codex session closed"));
         this.proc.stdin.end();
         // Grace window before SIGKILL is configurable via ProviderConfig.graceSec
         // for sessions running long tools.
@@ -894,7 +1114,461 @@ export class CodexSessionImpl {
         const rootThreadId = this._threadId ?? this._expectedThreadId;
         return !!threadId && !!rootThreadId && threadId !== rootThreadId;
     }
+    backgroundTaskParentIdForPath(agentPath) {
+        if (!agentPath)
+            return null;
+        const separator = agentPath.lastIndexOf("/");
+        if (separator <= 0)
+            return null;
+        return this._backgroundTaskIdsByPath.get(agentPath.slice(0, separator)) ?? null;
+    }
+    agentMessageText(item) {
+        const direct = str(item, "text");
+        if (direct)
+            return direct;
+        const content = Array.isArray(item["content"]) ? item["content"] : [];
+        for (const entry of content) {
+            if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+                continue;
+            const block = entry;
+            const text = str(block, "text");
+            if (text && (str(block, "type") === "output_text" || str(block, "type") === "text")) {
+                return text;
+            }
+        }
+        return null;
+    }
+    backgroundTaskEvent(taskId, phase, status, options) {
+        const rootThreadId = this._threadId ?? this._expectedThreadId;
+        return {
+            type: "background_task",
+            taskId,
+            taskType: "subagent",
+            phase,
+            status,
+            description: options.description ?? null,
+            summary: options.summary ?? null,
+            parentTaskId: options.parentTaskId ?? null,
+            timestamp: new Date().toISOString(),
+            providerType: "codex",
+            sessionId: rootThreadId,
+            messageId: null,
+            eventId: options.eventId ?? null,
+            turnId: options.turnId ?? null,
+            parentToolCallId: null,
+            raw: options.raw,
+        };
+    }
+    reconciledBackgroundTaskRaw(threadId, turn) {
+        const error = turn ? str(asObj(turn, "error"), "message") || null : null;
+        return {
+            method: "thread/read",
+            reconciled: true,
+            threadId,
+            turnId: turn ? str(turn, "id") || null : null,
+            status: turn ? str(turn, "status") || null : null,
+            error,
+        };
+    }
+    /**
+     * Codex 0.144+ represents collaboration as a root collabAgentToolCall item.
+     * A completed spawn call only means the child was created. Register every
+     * receiver and then follow the child thread itself for the real terminus.
+     */
+    handleCollabAgentToolCall(item, raw, parentTaskId) {
+        if (this._state === "closed" || !this.ctx.onEvent)
+            return;
+        const tool = str(item, "tool");
+        const states = asObj(item, "agentsStates");
+        const receiverIds = stringArray(item["receiverThreadIds"]);
+        const taskIds = [...new Set([...receiverIds, ...Object.keys(states)])];
+        const canStart = tool === "spawnAgent";
+        const metadataOnly = tool === "resumeAgent" || tool === "sendInput";
+        const canStopWithoutState = tool === "closeAgent" && str(item, "status") === "completed";
+        for (const taskId of taskIds) {
+            let previous = this._backgroundTasks.get(taskId);
+            const description = str(item, "prompt") || previous?.description || null;
+            const resolvedParentTaskId = previous?.parentTaskId ?? parentTaskId;
+            // The child thread's own turn/started notification is the only
+            // authoritative reactivation edge. Root resume/send calls can arrive
+            // before or after that child turn, so they only enrich an active task.
+            if (metadataOnly) {
+                if (!previous || previous.terminal)
+                    continue;
+                if (description && description !== previous.description) {
+                    this.dispatchEvent(this.backgroundTaskEvent(taskId, "progress", "running", {
+                        description,
+                        summary: previous.summary,
+                        parentTaskId: resolvedParentTaskId,
+                        eventId: this._threadId
+                            ? `codex:${this._threadId}:background-task:${taskId}:${str(item, "id") || "metadata"}:progress`
+                            : null,
+                        raw,
+                    }));
+                }
+                continue;
+            }
+            if (!previous && !canStart)
+                continue;
+            if (!canStart && !canStopWithoutState && !(taskId in states))
+                continue;
+            const hasState = taskId in states;
+            const state = !hasState && tool === "closeAgent" && str(item, "status") === "completed"
+                ? { terminal: true, status: "stopped", summary: null }
+                : codexAgentState(states[taskId]);
+            if (!previous) {
+                this.dispatchEvent(this.backgroundTaskEvent(taskId, "started", "running", {
+                    description,
+                    summary: null,
+                    parentTaskId: resolvedParentTaskId,
+                    eventId: this._threadId
+                        ? `codex:${this._threadId}:background-task:${taskId}:started`
+                        : null,
+                    raw,
+                }));
+                previous = this._backgroundTasks.get(taskId);
+            }
+            else if (previous.terminal) {
+                continue;
+            }
+            else if (description && description !== previous.description) {
+                // thread/started can beat the richer root collab item. Preserve one
+                // start edge, then publish the prompt as ordinary progress metadata.
+                this.dispatchEvent(this.backgroundTaskEvent(taskId, "progress", "running", {
+                    description,
+                    summary: previous.summary,
+                    parentTaskId: resolvedParentTaskId,
+                    eventId: this._threadId
+                        ? `codex:${this._threadId}:background-task:${taskId}:${str(item, "id") || "metadata"}:progress`
+                        : null,
+                    raw,
+                }));
+            }
+            if (state.terminal) {
+                this.dispatchEvent(this.backgroundTaskEvent(taskId, "completed", state.status, {
+                    description,
+                    summary: state.summary,
+                    parentTaskId: resolvedParentTaskId,
+                    eventId: this._threadId
+                        ? `codex:${this._threadId}:background-task:${taskId}:${str(item, "id") || "state"}:completed`
+                        : null,
+                    raw,
+                }));
+            }
+            else {
+                this.startBackgroundTaskPoller(taskId);
+            }
+        }
+    }
+    waitForBackgroundTaskPoll(pollKey) {
+        if (this._state === "closed")
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this._backgroundTaskPollTimers.delete(pollKey);
+                resolve();
+            }, BACKGROUND_TASK_POLL_INTERVAL_MS);
+            if (typeof timer.unref === "function")
+                timer.unref();
+            this._backgroundTaskPollTimers.set(pollKey, { timer, resolve });
+        });
+    }
+    startBackgroundTaskPoller(taskId) {
+        if (this._state === "closed")
+            return;
+        const task = this._backgroundTasks.get(taskId);
+        if (!task || task.terminal)
+            return;
+        const existing = this._backgroundTaskPollers.get(taskId);
+        if (existing?.generation === task.generation)
+            return;
+        const generation = task.generation;
+        const pollKey = `${taskId}:${generation}`;
+        let poller;
+        poller = this.pollBackgroundTask(taskId, generation, pollKey).finally(() => {
+            if (this._backgroundTaskPollers.get(taskId)?.promise === poller) {
+                this._backgroundTaskPollers.delete(taskId);
+            }
+            const pending = this._backgroundTaskPollTimers.get(pollKey);
+            if (pending)
+                clearTimeout(pending.timer);
+            this._backgroundTaskPollTimers.delete(pollKey);
+        });
+        this._backgroundTaskPollers.set(taskId, { generation, promise: poller });
+    }
+    async pollBackgroundTask(taskId, generation, pollKey) {
+        while (this._state !== "closed") {
+            const task = this._backgroundTasks.get(taskId);
+            if (!task || task.generation !== generation || task.terminal)
+                return;
+            try {
+                const response = await this.boundedRpcRequest("thread/read", {
+                    threadId: taskId,
+                    includeTurns: true,
+                });
+                if (this.observeBackgroundTaskThread(response, taskId, generation))
+                    return;
+            }
+            catch {
+                // A child can briefly be pendingInit before thread/read can load it.
+            }
+            const current = this._backgroundTasks.get(taskId);
+            if (!current || current.generation !== generation || current.terminal)
+                return;
+            await this.waitForBackgroundTaskPoll(pollKey);
+        }
+    }
+    /** Return true once thread/read proves that the child's latest turn ended. */
+    observeBackgroundTaskThread(response, taskId, generation) {
+        const task = this._backgroundTasks.get(taskId);
+        if (!task || task.generation !== generation || task.terminal)
+            return true;
+        const thread = asObj(response, "thread");
+        const turns = Array.isArray(thread["turns"])
+            ? thread["turns"].map(obj)
+            : [];
+        const latestTurn = turns[turns.length - 1];
+        if (!latestTurn) {
+            const threadStatus = str(asObj(thread, "status"), "type");
+            if (threadStatus !== "systemError")
+                return false;
+            const failureTurn = { status: "systemError", error: { message: "Subagent failed to initialize" } };
+            this.dispatchEvent(this.backgroundTaskEvent(taskId, "completed", "failed", {
+                description: task.description,
+                summary: "Subagent failed to initialize",
+                parentTaskId: task.parentTaskId,
+                eventId: this._threadId
+                    ? `codex:${this._threadId}:background-task:${taskId}:system-error:completed`
+                    : null,
+                raw: this.reconciledBackgroundTaskRaw(taskId, failureTurn),
+            }));
+            return true;
+        }
+        const nativeStatus = str(latestTurn, "status");
+        if (nativeStatus === "inProgress" || !nativeStatus)
+            return false;
+        const turnId = str(latestTurn, "id") || null;
+        // The child turn/started notification is authoritative for a reactivated
+        // generation. thread/read can briefly lag and still end at an older turn.
+        if (task.activeTurnId && turnId !== task.activeTurnId)
+            return false;
+        const items = Array.isArray(latestTurn["items"])
+            ? latestTurn["items"].map(obj)
+            : [];
+        let summary = null;
+        for (let index = items.length - 1; index >= 0; index--) {
+            const item = items[index];
+            if (str(item, "type") !== "agentMessage")
+                continue;
+            summary = this.agentMessageText(item);
+            if (summary)
+                break;
+        }
+        const errorMessage = str(asObj(latestTurn, "error"), "message") || null;
+        const status = nativeStatus === "failed"
+            ? "failed"
+            : nativeStatus === "interrupted" || nativeStatus === "cancelled"
+                ? "stopped"
+                : "completed";
+        this.dispatchEvent(this.backgroundTaskEvent(taskId, "completed", status, {
+            description: task.description,
+            summary: summary ?? errorMessage,
+            parentTaskId: task.parentTaskId,
+            turnId,
+            eventId: this._threadId && turnId
+                ? `codex:${this._threadId}:background-task:${taskId}:${turnId}:completed`
+                : null,
+            raw: this.reconciledBackgroundTaskRaw(taskId, latestTurn),
+        }));
+        return true;
+    }
+    /**
+     * Maintain just enough child metadata to turn a later foreign-thread
+     * terminal notification into one provider-neutral task event. This reducer
+     * is deliberately separate from every root turn accumulator.
+     */
+    observeBackgroundTask(event) {
+        const previous = this._backgroundTasks.get(event.taskId);
+        // Codex reports `subAgentActivity:interacted` after it forwards a child's
+        // final answer to the parent. The authoritative child turn/completed can
+        // arrive first, so suppress that late progress edge instead of resurrecting
+        // a task that already reached a terminal state. A later child turn/started
+        // explicitly reactivates the record below in handleForeignNotification.
+        if (previous?.terminal)
+            return false;
+        // collabAgentToolCall and child thread/started can both announce the same
+        // spawn. The first edge is sufficient and gives hosts one durable start.
+        if (previous && event.phase === "started")
+            return false;
+        const description = event.description ?? previous?.description ?? null;
+        const summary = event.summary ?? previous?.summary ?? null;
+        const parentTaskId = event.parentTaskId
+            ?? previous?.parentTaskId
+            ?? this.backgroundTaskParentIdForPath(description);
+        event.description = description;
+        event.summary = summary;
+        event.parentTaskId = parentTaskId;
+        this._backgroundTasks.set(event.taskId, {
+            taskId: event.taskId,
+            description,
+            summary,
+            parentTaskId,
+            terminal: event.phase === "completed",
+            generation: previous?.generation ?? 0,
+            activeTurnId: event.phase === "completed"
+                ? null
+                : event.turnId ?? previous?.activeTurnId ?? null,
+        });
+        if (description)
+            this._backgroundTaskIdsByPath.set(description, event.taskId);
+        return true;
+    }
+    /**
+     * A Codex app-server connection also publishes child thread notifications.
+     * They are useful only as background-task metadata. They must never flow
+     * through root state, summary, usage, or `resolveTurn()`.
+     */
+    handleForeignNotification(method, params, rawLine, childThreadId) {
+        if (method === "thread/started") {
+            const thread = asObj(params, "thread");
+            const parentThreadId = str(thread, "parentThreadId") || str(thread, "parent_thread_id");
+            const rootThreadId = this._threadId ?? this._expectedThreadId;
+            const parentTask = this._backgroundTasks.get(parentThreadId);
+            // App-server can publish child thread/started before the corresponding
+            // root subAgentActivity item. Register only descendants of this session,
+            // not unrelated foreign threads multiplexed by a future server version.
+            if (parentThreadId !== rootThreadId && !parentTask)
+                return;
+            const source = asObj(thread, "source");
+            const subAgent = Object.keys(asObj(source, "subAgent")).length > 0
+                ? asObj(source, "subAgent")
+                : asObj(source, "subagent");
+            const spawnSource = Object.keys(asObj(subAgent, "threadSpawn")).length > 0
+                ? asObj(subAgent, "threadSpawn")
+                : asObj(subAgent, "thread_spawn");
+            const description = str(spawnSource, "agentPath")
+                || str(spawnSource, "agent_path")
+                || str(thread, "name")
+                || str(thread, "agentNickname")
+                || str(thread, "agentRole")
+                || null;
+            this.dispatchEvent({
+                type: "background_task",
+                taskId: childThreadId,
+                taskType: "subagent",
+                phase: "started",
+                status: "running",
+                description,
+                summary: null,
+                parentTaskId: parentThreadId === rootThreadId ? null : parentThreadId,
+                timestamp: new Date().toISOString(),
+                providerType: "codex",
+                sessionId: rootThreadId,
+                messageId: null,
+                eventId: rootThreadId
+                    ? `codex:${rootThreadId}:background-task:${childThreadId}:started`
+                    : null,
+                turnId: null,
+                parentToolCallId: null,
+                raw: parseJson(rawLine) ?? params,
+            });
+            this.startBackgroundTaskPoller(childThreadId);
+            return;
+        }
+        const task = this._backgroundTasks.get(childThreadId);
+        if (!task)
+            return;
+        if (method === "turn/started") {
+            if (!task.terminal)
+                return;
+            task.terminal = false;
+            task.summary = null;
+            task.generation += 1;
+            const turn = asObj(params, "turn");
+            const turnId = str(turn, "id") || str(params, "turnId") || null;
+            const rootThreadId = this._threadId ?? this._expectedThreadId;
+            this.dispatchEvent({
+                type: "background_task",
+                taskId: childThreadId,
+                taskType: "subagent",
+                phase: "progress",
+                status: "running",
+                description: task.description,
+                summary: null,
+                parentTaskId: task.parentTaskId,
+                timestamp: new Date().toISOString(),
+                providerType: "codex",
+                sessionId: rootThreadId,
+                messageId: null,
+                eventId: rootThreadId && turnId
+                    ? `codex:${rootThreadId}:background-task:${childThreadId}:${turnId}:progress`
+                    : null,
+                turnId,
+                parentToolCallId: null,
+                raw: parseJson(rawLine) ?? params,
+            });
+            this.startBackgroundTaskPoller(childThreadId);
+            return;
+        }
+        if (method === "item/completed") {
+            const item = asObj(params, "item");
+            const itemType = str(item, "type");
+            if (itemType === "collabAgentToolCall") {
+                this.handleCollabAgentToolCall(item, parseJson(rawLine) ?? params, childThreadId);
+                return;
+            }
+            if ((itemType === "agentMessage" || itemType === "agent_message") && str(item, "phase") !== "commentary") {
+                const summary = this.agentMessageText(item);
+                if (summary)
+                    task.summary = summary;
+            }
+            return;
+        }
+        if (method !== "turn/completed" && method !== "turn/failed")
+            return;
+        const turn = asObj(params, "turn");
+        const turnId = str(turn, "id") || str(params, "turnId") || null;
+        const nativeStatus = method === "turn/failed" ? "failed" : str(turn, "status");
+        const status = nativeStatus === "failed"
+            ? "failed"
+            : nativeStatus === "interrupted" || nativeStatus === "cancelled"
+                ? "stopped"
+                : "completed";
+        const errorMessage = str(asObj(turn, "error"), "message")
+            || str(params, "message")
+            || str(params, "error");
+        const rootThreadId = this._threadId ?? this._expectedThreadId;
+        this.dispatchEvent({
+            type: "background_task",
+            taskId: childThreadId,
+            taskType: "subagent",
+            phase: "completed",
+            status,
+            description: task.description,
+            summary: task.summary ?? (errorMessage || null),
+            parentTaskId: task.parentTaskId,
+            timestamp: new Date().toISOString(),
+            providerType: "codex",
+            sessionId: rootThreadId,
+            messageId: null,
+            eventId: rootThreadId && turnId
+                ? `codex:${rootThreadId}:background-task:${childThreadId}:${turnId}:completed`
+                : null,
+            turnId,
+            parentToolCallId: null,
+            raw: {
+                method,
+                reconciled: false,
+                threadId: childThreadId,
+                turnId,
+                status: nativeStatus || null,
+                error: errorMessage || null,
+            },
+        });
+    }
     handleNotification(method, params, rawLine) {
+        if (this._state === "closed")
+            return;
         // codex/event — legacy wrapper
         if (method === "codex/event") {
             const innerMsg = str(params, "msg");
@@ -911,8 +1585,10 @@ export class CodexSessionImpl {
         // its root thread, so foreign items must not change root state/summary and,
         // most importantly, a child turn/completed must not resolve the root send.
         const notificationThreadId = this.notificationThreadId(params);
-        if (this.isForeignThread(notificationThreadId))
+        if (this.isForeignThread(notificationThreadId)) {
+            this.handleForeignNotification(method, params, rawLine, notificationThreadId);
             return;
+        }
         // Map v2 notification methods to processing
         if (method === "thread/started") {
             // codex-cli 0.130.0+ shape: { thread: { id, sessionId, ... } }
@@ -921,6 +1597,12 @@ export class CodexSessionImpl {
             this.emitStreamEvent(rawLine);
             return;
         }
+        if (method === "turn/started") {
+            this.captureActiveTurnId(str(asObj(params, "turn"), "id") || str(params, "turnId"));
+            // The parser intentionally suppresses this lifecycle-only event.
+            this.emitStreamEvent(rawLine);
+            return;
+        }
         if (method === "item/started") {
             this._state = "tool_executing";
             this.emitStreamEvent(rawLine);
@@ -929,6 +1611,11 @@ export class CodexSessionImpl {
         if (method === "item/completed") {
             this._state = "thinking";
             this.extractSummaryFromItem(params);
+            const item = asObj(params, "item");
+            if (str(item, "type") === "collabAgentToolCall") {
+                this.handleCollabAgentToolCall(item, parseJson(rawLine) ?? params, null);
+                return;
+            }
             this.emitStreamEvent(rawLine);
             return;
         }
@@ -937,6 +1624,7 @@ export class CodexSessionImpl {
             return;
         }
         if (method === "turn/failed") {
+            this.markTurnTerminalObserved();
             this._turnIsError = true;
             this._turnErrorMessage = str(params, "message") || str(params, "error") || "Turn failed";
             // Emit before resolve so the result event is queued onto _eventChain
@@ -963,6 +1651,8 @@ export class CodexSessionImpl {
     // Legacy event handling (NDJSON events with `type` field)
     // -------------------------------------------------------------------------
     handleLegacyEvent(event, rawLine) {
+        if (this._state === "closed")
+            return;
         const type = str(event, "type");
         const eventThreadId = str(event, "thread_id") || str(event, "threadId") || str(event, "session_id") || null;
         // Older NDJSON-shaped events can also carry explicit thread scope. Keep
@@ -991,6 +1681,7 @@ export class CodexSessionImpl {
             return;
         }
         if (type === "turn.failed" || type === "error") {
+            this.markTurnTerminalObserved();
             this._turnIsError = true;
             this._turnErrorMessage = str(event, "message") || str(event, "error") || "Turn failed";
             // Emit before resolve so the result event is queued onto _eventChain
@@ -1038,6 +1729,7 @@ export class CodexSessionImpl {
         }
     }
     handleTurnCompleted(params) {
+        this.markTurnTerminalObserved();
         const usage = typeof params["usage"] === "object" && params["usage"] !== null
             ? params["usage"]
             : null;
@@ -1057,7 +1749,10 @@ export class CodexSessionImpl {
         // the error instead of a false "completed".
         const turn = asObj(params, "turn");
         const turnStatus = str(turn, "status");
-        if (turnStatus === "failed" || turnStatus === "cancelled") {
+        if (turnStatus === "interrupted" || turnStatus === "cancelled") {
+            this._turnWasInterrupted = true;
+        }
+        else if (turnStatus === "failed") {
             this._turnIsError = true;
             const msg = str(asObj(turn, "error"), "message");
             this._turnErrorMessage = msg || this._turnErrorMessage || `Turn ${turnStatus}`;
@@ -1123,9 +1818,9 @@ export class CodexSessionImpl {
             summary: this._turnSummary,
             usage,
             costUsd: null,
-            status: this._turnIsError ? "failed" : "completed",
-            errorCode: this._turnIsError ? "execution_error" : null,
-            errorMessage: this._turnErrorMessage,
+            status: this._turnWasInterrupted ? "aborted" : this._turnIsError ? "failed" : "completed",
+            errorCode: this._turnWasInterrupted ? "aborted" : this._turnIsError ? "execution_error" : null,
+            errorMessage: this._turnWasInterrupted ? "Turn was interrupted" : this._turnErrorMessage,
         };
         // Drain pending onEvent handlers so callers awaiting send() see a settled
         // DB / log / UI state by the time TurnResult resolves. The chain snapshot
@@ -1149,8 +1844,10 @@ export class CodexSessionImpl {
         this._turnUsage = null;
         this._turnModel = null;
         this._turnIsError = false;
+        this._turnWasInterrupted = false;
         this._turnErrorMessage = null;
         this._turnStartedAt = null;
+        this.clearActiveTurn();
         for (const p of pending) {
             // Skip sends already settled early by timeout / abort.
             if (p.settled)
@@ -1181,6 +1878,8 @@ export class CodexSessionImpl {
      * throwing handler does not break delivery of subsequent events.
      */
     dispatchEvent(event) {
+        if (event.type === "background_task" && !this.observeBackgroundTask(event))
+            return;
         // Track native goal_status transitions (keeps getGoal() accurate).
         this._goals.observe(event);
         const cb = this.ctx.onEvent;