@agentex/agent 0.0.32 → 0.0.34

package/src/providers/codex/session.ts

@@ -132,6 +132,33 @@ interface PendingResult {
   cleanup?: () => void;
 }
 
+interface TrackedBackgroundTask {
+  taskId: string;
+  description: string | null;
+  summary: string | null;
+  parentTaskId: string | null;
+  terminal: boolean;
+  generation: number;
+  activeTurnId: string | null;
+}
+
+interface CodexBackgroundTaskState {
+  terminal: boolean;
+  status: "running" | "completed" | "failed" | "stopped";
+  summary: string | null;
+}
+
+const BACKGROUND_TASK_POLL_INTERVAL_MS = 2_000;
+const BACKGROUND_TASK_READ_TIMEOUT_MS = 5_000;
+
+/** Identity latch for the root turn currently represented by this session. */
+interface ActiveTurnReady {
+  promise: Promise<string | null>;
+  resolve: (turnId: string | null) => void;
+  reject: (err: Error) => void;
+  settled: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // JSON-RPC 2.0 helpers
 // ---------------------------------------------------------------------------
@@ -163,6 +190,32 @@ function asObj(parent: Record<string, unknown>, key: string): Record<string, unk
     : {};
 }
 
+function obj(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0)
+    : [];
+}
+
+function codexAgentState(value: unknown): CodexBackgroundTaskState {
+  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 };
+}
+
 /** Discriminated incoming message from the Codex CLI. */
 type IncomingMessage =
   | { kind: "response"; id: number; result?: Record<string, unknown>; error?: { code: number; message: string } }
@@ -342,6 +395,19 @@ export class CodexSessionImpl implements AgentSession {
   /** Shared promise so concurrent / repeated `drain()` calls coalesce. */
   private _drainPromise: Promise<void> | null = 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.
+   */
+  private _activeTurnId: string | null = null;
+  private _activeTurnReady: ActiveTurnReady | null = null;
+  /** Successful repeated interrupts coalesce until the terminal notification. */
+  private _interruptPromise: Promise<void> | null = null;
+  /** Prevents a late interrupt request after the terminal frame was observed. */
+  private _turnTerminalObserved = false;
+
   /** Stamps `tool_result.toolName` by correlating with prior `tool_call`s. */
   private readonly _trackToolName = createToolNameTracker();
 
@@ -351,9 +417,24 @@ export class CodexSessionImpl implements AgentSession {
   private _turnUsage: { inputTokens: number; outputTokens: number } | null = null;
   private _turnModel: string | null = null;
   private _turnIsError = false;
+  private _turnWasInterrupted = false;
   private _turnErrorMessage: string | null = null;
   private _turnStartedAt: Date | null = null;
 
+  /** Child-agent lifecycle is informational and never participates in root turn settlement. */
+  private readonly _backgroundTasks = new Map<string, TrackedBackgroundTask>();
+  private readonly _backgroundTaskIdsByPath = new Map<string, string>();
+  /** One protocol-native thread/read poller per child when Codex does not multiplex its notifications. */
+  private readonly _backgroundTaskPollers = new Map<string, {
+    generation: number;
+    promise: Promise<void>;
+  }>();
+  /** Cancellable retry delay for each poller. Cleared when the session closes. */
+  private readonly _backgroundTaskPollTimers = new Map<string, {
+    timer: ReturnType<typeof setTimeout>;
+    resolve: () => void;
+  }>();
+
   /**
    * Serial dispatch chain for `onEvent`. Each dispatched event appends a
    * handler invocation; the chain enforces in-order delivery and lets
@@ -422,7 +503,14 @@ export class CodexSessionImpl implements AgentSession {
     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);
       }
     });
@@ -430,11 +518,43 @@ export class CodexSessionImpl implements AgentSession {
     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);
       }
     });
   }
 
+  private cancelBackgroundTaskPollTimers(): void {
+    for (const pending of this._backgroundTaskPollTimers.values()) {
+      clearTimeout(pending.timer);
+      pending.resolve();
+    }
+    this._backgroundTaskPollTimers.clear();
+  }
+
+  private finalizeActiveBackgroundTasks(
+    status: "failed" | "stopped",
+    summary: string,
+    raw: Record<string, unknown>,
+  ): void {
+    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. */
   private rejectAllPending(err: Error): void {
     const pending = this._pendingResults.splice(0);
@@ -446,11 +566,78 @@ export class CodexSessionImpl implements AgentSession {
     }
     for (const [, p] of this._pendingRpc) p.reject(err);
     this._pendingRpc.clear();
+    this.clearActiveTurn(err);
   }
 
   get sessionId(): string | null { return this._threadId; }
   get state(): SessionState { return this._state; }
 
+  /** Start the identity latch before writing the leader `turn/start` request. */
+  private beginActiveTurn(): ActiveTurnReady {
+    let resolveFn!: (turnId: string | null) => void;
+    let rejectFn!: (err: Error) => void;
+    const promise = new Promise<string | null>((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: ActiveTurnReady = {
+      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. */
+  private captureActiveTurnId(turnId: string, expected?: ActiveTurnReady): void {
+    const ready = this._activeTurnReady;
+    if (!turnId || !ready || ready.settled) return;
+    if (expected && ready !== expected) return;
+    this._activeTurnId = turnId;
+    ready.settled = true;
+    ready.resolve(turnId);
+  }
+
+  private rejectActiveTurnReady(err: Error, expected: ActiveTurnReady): void {
+    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. */
+  private clearActiveTurn(err?: Error): void {
+    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. */
+  private markTurnTerminalObserved(): void {
+    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
@@ -483,6 +670,35 @@ export class CodexSessionImpl implements AgentSession {
     });
   }
 
+  /** A bounded RPC whose pending-map entry is removed if Codex never replies. */
+  private boundedRpcRequest(
+    method: string,
+    params: Record<string, unknown>,
+    timeoutMs = BACKGROUND_TASK_READ_TIMEOUT_MS,
+  ): Promise<Record<string, unknown>> {
+    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
@@ -618,6 +834,10 @@ export class CodexSessionImpl implements AgentSession {
     // 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();
@@ -659,16 +879,34 @@ export class CodexSessionImpl implements AgentSession {
     // 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: unknown) => {
+        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.
    */
   private armSendDeadline(entry: PendingResult, options?: SendOptions): void {
@@ -711,7 +949,7 @@ export class CodexSessionImpl implements AgentSession {
 
     // 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,
@@ -727,7 +965,7 @@ export class CodexSessionImpl implements AgentSession {
 
   async cancel(_uuid: string): Promise<CancelResult> {
     // 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 };
   }
@@ -780,11 +1018,37 @@ export class CodexSessionImpl implements AgentSession {
   }
 
   async interrupt(): Promise<void> {
-    if (this._state === "idle" || this._state === "closed") return;
+    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", {});
-    } catch { /* best effort */ }
+      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;
+    }
   }
 
   async drain(): Promise<void> {
@@ -804,6 +1068,11 @@ export class CodexSessionImpl implements AgentSession {
   async close(): Promise<void> {
     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();
 
@@ -1003,7 +1272,494 @@ export class CodexSessionImpl implements AgentSession {
     return !!threadId && !!rootThreadId && threadId !== rootThreadId;
   }
 
+  private backgroundTaskParentIdForPath(agentPath: string | null): string | null {
+    if (!agentPath) return null;
+    const separator = agentPath.lastIndexOf("/");
+    if (separator <= 0) return null;
+    return this._backgroundTaskIdsByPath.get(agentPath.slice(0, separator)) ?? null;
+  }
+
+  private agentMessageText(item: Record<string, unknown>): string | null {
+    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 as Record<string, unknown>;
+      const text = str(block, "text");
+      if (text && (str(block, "type") === "output_text" || str(block, "type") === "text")) {
+        return text;
+      }
+    }
+    return null;
+  }
+
+  private backgroundTaskEvent(
+    taskId: string,
+    phase: "started" | "progress" | "completed",
+    status: "running" | "completed" | "failed" | "stopped",
+    options: {
+      description?: string | null;
+      summary?: string | null;
+      parentTaskId?: string | null;
+      turnId?: string | null;
+      eventId?: string | null;
+      raw: Record<string, unknown>;
+    },
+  ): Extract<StreamEvent, { type: "background_task" }> {
+    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,
+    };
+  }
+
+  private reconciledBackgroundTaskRaw(
+    threadId: string,
+    turn: Record<string, unknown> | null,
+  ): Record<string, unknown> {
+    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.
+   */
+  private handleCollabAgentToolCall(
+    item: Record<string, unknown>,
+    raw: Record<string, unknown>,
+    parentTaskId: string | null,
+  ): void {
+    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" as const, 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);
+      }
+    }
+  }
+
+  private waitForBackgroundTaskPoll(pollKey: string): Promise<void> {
+    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 });
+    });
+  }
+
+  private startBackgroundTaskPoller(taskId: string): void {
+    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!: Promise<void>;
+    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 });
+  }
+
+  private async pollBackgroundTask(
+    taskId: string,
+    generation: number,
+    pollKey: string,
+  ): Promise<void> {
+    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. */
+  private observeBackgroundTaskThread(
+    response: Record<string, unknown>,
+    taskId: string,
+    generation: number,
+  ): boolean {
+    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: string | null = 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.
+   */
+  private observeBackgroundTask(event: Extract<StreamEvent, { type: "background_task" }>): boolean {
+    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()`.
+   */
+  private handleForeignNotification(
+    method: string,
+    params: Record<string, unknown>,
+    rawLine: string,
+    childThreadId: string,
+  ): void {
+    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,
+      },
+    });
+  }
+
   private handleNotification(method: string, params: Record<string, unknown>, rawLine: string): void {
+    if (this._state === "closed") return;
     // codex/event — legacy wrapper
     if (method === "codex/event") {
       const innerMsg = str(params, "msg");
@@ -1020,7 +1776,10 @@ export class CodexSessionImpl implements AgentSession {
     // 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)) return;
+    if (this.isForeignThread(notificationThreadId)) {
+      this.handleForeignNotification(method, params, rawLine, notificationThreadId!);
+      return;
+    }
 
     // Map v2 notification methods to processing
     if (method === "thread/started") {
@@ -1030,6 +1789,13 @@ export class CodexSessionImpl implements AgentSession {
       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);
@@ -1039,6 +1805,11 @@ export class CodexSessionImpl implements AgentSession {
     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;
     }
@@ -1049,6 +1820,7 @@ export class CodexSessionImpl implements AgentSession {
     }
 
     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
@@ -1078,6 +1850,7 @@ export class CodexSessionImpl implements AgentSession {
   // -------------------------------------------------------------------------
 
   private handleLegacyEvent(event: Record<string, unknown>, rawLine: string): void {
+    if (this._state === "closed") return;
     const type = str(event, "type");
     const eventThreadId =
       str(event, "thread_id") || str(event, "threadId") || str(event, "session_id") || null;
@@ -1111,6 +1884,7 @@ export class CodexSessionImpl implements AgentSession {
     }
 
     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
@@ -1162,6 +1936,7 @@ export class CodexSessionImpl implements AgentSession {
   }
 
   private handleTurnCompleted(params: Record<string, unknown>): void {
+    this.markTurnTerminalObserved();
     const usage = typeof params["usage"] === "object" && params["usage"] !== null
       ? (params["usage"] as Record<string, unknown>)
       : null;
@@ -1181,7 +1956,9 @@ export class CodexSessionImpl implements AgentSession {
     // 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}`;
@@ -1253,9 +2030,9 @@ export class CodexSessionImpl implements AgentSession {
       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
@@ -1283,8 +2060,10 @@ export class CodexSessionImpl implements AgentSession {
     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.
@@ -1316,6 +2095,7 @@ export class CodexSessionImpl implements AgentSession {
    * throwing handler does not break delivery of subsequent events.
    */
   private dispatchEvent(event: StreamEvent): void {
+    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;