@parall/codex-agent 1.59.0 → 1.60.0

package/dist/foreign-threads.js

@@ -0,0 +1,143 @@
+import { extractThreadInfo } from './app-server-protocol.js';
+import { CodexRuntimeTurn } from './runtime-turn.js';
+export class ForeignThreadRegistry {
+    host;
+    threads = new Map();
+    constructor(host) {
+        this.host = host;
+    }
+    /** Live (registered, not closed) subagent threads. */
+    get size() {
+        return this.threads.size;
+    }
+    openTurns() {
+        let count = 0;
+        for (const thread of this.threads.values())
+            if (thread.turn)
+                count += 1;
+        return count;
+    }
+    /**
+     * Notifications for a thread no dispatch owns. Returns false when the
+     * caller should keep treating the frame as unroutable.
+     */
+    route(method, params, threadId) {
+        if (method === 'thread/started') {
+            if (this.host.sessionManager.getSessionKey(threadId) || this.threads.has(threadId)) {
+                return true;
+            }
+            const info = extractThreadInfo(params);
+            // Only subagent spawns become child sessions; our own thread/start and
+            // thread/fork echoes (source appServer) are bound by their responses.
+            if (!info || info.source !== 'subAgent')
+                return true;
+            this.register(info);
+            return true;
+        }
+        let thread = this.threads.get(threadId);
+        if (method === 'thread/closed' || method === 'thread/archived' || method === 'thread/deleted') {
+            if (!thread)
+                return false;
+            this.close(thread, method.slice('thread/'.length));
+            return true;
+        }
+        if (!thread) {
+            // A turn on a thread we never saw start: our own thread without a
+            // sink is a genuine orphan (keep the warn); anything else is adopted
+            // under the main session (bridge restarted mid-subagent).
+            if (this.host.sessionManager.getSessionKey(threadId))
+                return false;
+            if (method !== 'turn/started' && method !== 'turn/completed' && !method.startsWith('item/')) {
+                return false;
+            }
+            thread = this.register({ id: threadId });
+        }
+        if (method === 'turn/started') {
+            if (thread.turn)
+                thread.turn.touch();
+            else
+                this.openTurn(thread);
+            return true;
+        }
+        if (!thread.turn) {
+            if (method !== 'turn/completed' && !method.startsWith('item/'))
+                return true;
+            this.openTurn(thread);
+        }
+        const turn = thread.turn;
+        turn.sink.touchActivity();
+        for (const event of turn.sink.mapper.map(method, params)) {
+            turn.sink.push({ kind: 'runtime', event });
+        }
+        if (method === 'turn/completed') {
+            this.endTurn(thread, { kind: 'turn_end', threadId });
+            this.host.log?.info?.(`runtime-initiated turn ${turn.groupKey} on subagent thread ${threadId} completed`);
+        }
+        return true;
+    }
+    /** Subagent threads die with the app-server: end open turns, close child sessions. */
+    dropAll(reason) {
+        for (const thread of [...this.threads.values()]) {
+            this.close(thread, reason);
+        }
+    }
+    register(info) {
+        // A subagent may itself spawn subagents: resolve the parent against the
+        // live foreign threads first, then main / fork threads, else main.
+        const parentSessionKey = (info.parentThreadId
+            ? (this.threads.get(info.parentThreadId)?.sessionKey ??
+                this.host.sessionManager.getSessionKey(info.parentThreadId))
+            : undefined) ?? this.host.sessionManager.mainSessionKey;
+        const thread = {
+            threadId: info.id,
+            sessionKey: `codex-sub:${info.id}`,
+            parentThreadId: info.parentThreadId,
+            parentSessionKey,
+            nickname: info.nickname,
+            role: info.role,
+        };
+        this.threads.set(info.id, thread);
+        this.host.log?.info?.(`subagent thread ${info.id} registered (parent ${info.parentThreadId ?? 'unknown'} → ${parentSessionKey}${info.nickname ? `, ${info.nickname}` : ''}${info.role ? ` / ${info.role}` : ''}); ${this.threads.size} live`);
+        return thread;
+    }
+    openTurn(thread) {
+        const turn = new CodexRuntimeTurn(thread.sessionKey, {
+            kind: 'subagent',
+            threadId: thread.threadId,
+            ...(thread.parentThreadId ? { parentThreadId: thread.parentThreadId } : {}),
+            ...(thread.nickname ? { nickname: thread.nickname } : {}),
+            ...(thread.role ? { role: thread.role } : {}),
+        }, {
+            parentSessionKey: thread.parentSessionKey,
+            onDetach: (reason) => {
+                if (thread.turn !== turn)
+                    return;
+                this.endTurn(thread, { kind: 'error', message: `subagent turn detached: ${reason}` });
+            },
+        });
+        thread.turn = turn;
+        this.host.log?.info?.(`runtime-initiated turn ${turn.groupKey} opened on subagent thread ${thread.threadId}`);
+        this.host.activity.surfaceTurn(turn);
+    }
+    /** The thread's open turn is over: last envelope, sink closed, restart re-driven. */
+    endTurn(thread, last) {
+        const turn = thread.turn;
+        if (!turn)
+            return;
+        thread.turn = undefined;
+        turn.sink.push(last);
+        turn.sink.close();
+        this.host.afterTurnClosed();
+    }
+    close(thread, reason) {
+        if (this.threads.get(thread.threadId) !== thread)
+            return;
+        this.threads.delete(thread.threadId);
+        this.endTurn(thread, {
+            kind: 'error',
+            message: `subagent thread ${thread.threadId} ${reason}`,
+        });
+        this.host.log?.info?.(`subagent thread ${thread.threadId} ${reason}; ${this.threads.size} live`);
+        this.host.activity.emit({ kind: 'session_closed', sessionKey: thread.sessionKey, reason });
+    }
+}

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import * as os from 'node:os';
-import { ParallAgentGateway, capabilityBinDir, configureHttpKeepAlive, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, identityFromMe, initAgentTelemetry, } from '@parall/agent-core';
+import { ParallAgentGateway, capabilityBinDir, configureHttpKeepAlive, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, identityFromMe, initAgentTelemetry, resolveServiceVersion, } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import { buildCodexRuntimeKey, contextFilePathForSession, dispatchContextDirPath, resolveCodexAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from './config.js';
 import { CodexAppServerAdapter } from './dispatch.js';
@@ -40,7 +40,11 @@ function resolveProviderEnv() {
 async function main() {
     // Before any fetch: long-lived HTTP connections for every bridge→api call.
     configureHttpKeepAlive();
-    const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex');
+    const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex', {
+        apiUrl: process.env.PRLL_API_URL,
+        apiKey: process.env.PRLL_API_KEY,
+        serviceVersion: resolveServiceVersion(import.meta.url),
+    });
     activeLog = createOtelLogger('agent', 'codex-agent');
     try {
         resolveProviderEnv();
@@ -231,6 +235,12 @@ async function main() {
             onSessionStale: () => {
                 sessionManager.clearMainThread();
             },
+            // The app-server outlives one dispatch (subagent threads keep running
+            // after the parent turn): stop it INSIDE the gateway's shutdown so the
+            // runtime turns it ends still land their steps and idle/close writes
+            // before the step and lifecycle flushes — the finally below runs after
+            // those windows have closed.
+            onBeforeDisconnect: () => adapter.stop(),
         });
         const abortController = new AbortController();
         const abort = () => abortController.abort();

package/dist/instructions-refresh.d.ts

@@ -53,6 +53,8 @@ export interface NotificationTapSource {
 }
 export declare function sha256Hex(text: string): string;
 export type RefreshOutcome = 'noop' | 'adopted-baseline' | 'refreshed' | 'unsupported' | 'failed' | 'stalled';
+export declare class CompactionStalledError extends Error {
+}
 export declare class MainThreadInstructionsRefresher {
     private readonly opts;
     /**
@@ -110,6 +112,29 @@ export declare class MainThreadInstructionsRefresher {
         threadId: string;
         log?: GatewayLogger;
     }): Promise<RefreshOutcome>;
+    /** True once this subprocess rejected thread/compact/start with -32601. */
+    isCompactUnsupported(): boolean;
+    /**
+     * The unconditional compaction primitive — one `thread/compact/start`
+     * awaited to its turn close — shared by the instructions refresh (which
+     * decides WHETHER to run it by sha) and the idle auto-compact (which runs
+     * it whenever the server asks). Throws like the refresh's inner path:
+     * CompactionStalledError past budget/abort + interrupt grace, JsonRpcError
+     * -32601 (also latches compactUnsupported for this subprocess), or a plain
+     * Error for a turn that closed without compacting.
+     */
+    runCompaction(args: {
+        client: JsonRpcStdioClient;
+        taps: NotificationTapSource;
+        threadId: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * A compaction that completed outside the refresh path (idle auto-compact)
+     * rebuilt the model-visible context from the canonical configuration: the
+     * effective plane now equals whatever this process opened the thread with.
+     */
+    recordCompacted(sessionKey: string, threadId: string): void;
     /**
      * Compaction runs as its own turn on the thread:
      *   turn/started → item/started{contextCompaction} →

package/dist/instructions-refresh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions-refresh.d.ts","sourceRoot":"","sources":["../src/instructions-refresh.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,IAAI,CAAC;CACtD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAMD,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,kBAAkB,GAClB,WAAW,GACX,aAAa,GACb,QAAQ,GAIR,SAAS,CAAC;AAId,qBAAa,+BAA+B;IAUxC,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAAS;gBAGhB,IAAI,EAAE;QACrB,cAAc,EAAE,IAAI,CAClB,mBAAmB,EACnB,6BAA6B,GAAG,gCAAgC,GAAG,qBAAqB,CACzF,CAAC;QACF,GAAG,CAAC,EAAE,aAAa,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,4DAA4D;QAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B;IAGH;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyC;IAE3E,qBAAqB,IAAI,IAAI;IAI7B,qEAAqE;IACrE,gBAAgB,IAAI,IAAI;IAIxB;;;;;;;OAOG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IASzF;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIvE,8EAA8E;IAC9E,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIlD;;;;;OAKG;IACG,kBAAkB,CAAC,IAAI,EAAE;QAC7B,MAAM,EAAE,kBAAkB,CAAC;QAC3B,IAAI,EAAE,qBAAqB,CAAC;QAC5B,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,aAAa,CAAC;KACrB,GAAG,OAAO,CAAC,cAAc,CAAC;IA4D3B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,kBAAkB;CAkG3B"}
+{"version":3,"file":"instructions-refresh.d.ts","sourceRoot":"","sources":["../src/instructions-refresh.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,IAAI,CAAC;CACtD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAMD,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,kBAAkB,GAClB,WAAW,GACX,aAAa,GACb,QAAQ,GAIR,SAAS,CAAC;AAEd,qBAAa,sBAAuB,SAAQ,KAAK;CAAG;AAEpD,qBAAa,+BAA+B;IAUxC,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAAS;gBAGhB,IAAI,EAAE;QACrB,cAAc,EAAE,IAAI,CAClB,mBAAmB,EACnB,6BAA6B,GAAG,gCAAgC,GAAG,qBAAqB,CACzF,CAAC;QACF,GAAG,CAAC,EAAE,aAAa,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,4DAA4D;QAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B;IAGH;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyC;IAE3E,qBAAqB,IAAI,IAAI;IAI7B,qEAAqE;IACrE,gBAAgB,IAAI,IAAI;IAIxB;;;;;;;OAOG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IASzF;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIvE,8EAA8E;IAC9E,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIlD;;;;;OAKG;IACG,kBAAkB,CAAC,IAAI,EAAE;QAC7B,MAAM,EAAE,kBAAkB,CAAC;QAC3B,IAAI,EAAE,qBAAqB,CAAC;QAC5B,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,aAAa,CAAC;KACrB,GAAG,OAAO,CAAC,cAAc,CAAC;IAkD3B,2EAA2E;IAC3E,oBAAoB,IAAI,OAAO;IAI/B;;;;;;;;OAQG;IACG,aAAa,CAAC,IAAI,EAAE;QACxB,MAAM,EAAE,kBAAkB,CAAC;QAC3B,IAAI,EAAE,qBAAqB,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBjB;;;;OAIG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAM3D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,kBAAkB;CAiI3B"}

package/dist/instructions-refresh.js

@@ -7,7 +7,7 @@ export function sha256Hex(text) {
 const DEFAULT_COMPACT_TIMEOUT_MS = 120_000;
 /** After an over-budget compaction is interrupted, how long to wait for its turn to close. */
 const COMPACT_INTERRUPT_GRACE_MS = 10_000;
-class CompactionStalledError extends Error {
+export class CompactionStalledError extends Error {
 }
 export class MainThreadInstructionsRefresher {
     opts;
@@ -90,28 +90,18 @@ export class MainThreadInstructionsRefresher {
         }
         if (this.compactUnsupported)
             return 'unsupported';
-        // The waiter registers its notification tap BEFORE the request goes out:
-        // the response and the compaction-turn notifications can arrive in one
-        // stdout chunk, and the client's line loop dispatches notifications
-        // synchronously — a tap registered only after `await sendRequest` resolves
-        // (a queued microtask) would miss every one of them and hang on the
-        // timeout.
-        const compaction = this.watchForCompaction(client, taps, threadId);
         try {
-            await client.sendRequest('thread/compact/start', { threadId });
-            await compaction.done;
+            await this.runCompaction({ client, taps, threadId });
             this.opts.sessionManager.recordEffectiveInstructionsSha(sessionKey, canonicalSha);
             log?.info?.(`platform instructions refreshed on persisted thread ${threadId} (compaction rebuilt initial context from the resumed configuration)`);
             return 'refreshed';
         }
         catch (err) {
-            compaction.cancel();
             if (err instanceof CompactionStalledError) {
                 log?.warn?.(`platform instructions refresh stalled (${errToString(err)}); bouncing the subprocess before the next turn`);
                 return 'stalled';
             }
             if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
-                this.compactUnsupported = true;
                 log?.warn?.('thread/compact/start not supported by this codex CLI; the persisted thread keeps its previous platform instructions until it is replaced or the CLI is upgraded (tools still refresh live via the capability shim dir)');
                 return 'unsupported';
             }
@@ -119,6 +109,51 @@ export class MainThreadInstructionsRefresher {
             return 'failed';
         }
     }
+    /** True once this subprocess rejected thread/compact/start with -32601. */
+    isCompactUnsupported() {
+        return this.compactUnsupported;
+    }
+    /**
+     * The unconditional compaction primitive — one `thread/compact/start`
+     * awaited to its turn close — shared by the instructions refresh (which
+     * decides WHETHER to run it by sha) and the idle auto-compact (which runs
+     * it whenever the server asks). Throws like the refresh's inner path:
+     * CompactionStalledError past budget/abort + interrupt grace, JsonRpcError
+     * -32601 (also latches compactUnsupported for this subprocess), or a plain
+     * Error for a turn that closed without compacting.
+     */
+    async runCompaction(args) {
+        const { client, taps, threadId, signal } = args;
+        // The waiter registers its notification tap BEFORE the request goes out:
+        // the response and the compaction-turn notifications can arrive in one
+        // stdout chunk, and the client's line loop dispatches notifications
+        // synchronously — a tap registered only after `await sendRequest` resolves
+        // (a queued microtask) would miss every one of them and hang on the
+        // timeout.
+        const compaction = this.watchForCompaction(client, taps, threadId, signal);
+        try {
+            await client.sendRequest('thread/compact/start', { threadId });
+            await compaction.done;
+        }
+        catch (err) {
+            compaction.cancel();
+            if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
+                this.compactUnsupported = true;
+            }
+            throw err;
+        }
+    }
+    /**
+     * A compaction that completed outside the refresh path (idle auto-compact)
+     * rebuilt the model-visible context from the canonical configuration: the
+     * effective plane now equals whatever this process opened the thread with.
+     */
+    recordCompacted(sessionKey, threadId) {
+        const canonical = this.canonicalByThread.get(threadId);
+        if (canonical === undefined)
+            return;
+        this.opts.sessionManager.recordEffectiveInstructionsSha(sessionKey, sha256Hex(canonical));
+    }
     /**
      * Compaction runs as its own turn on the thread:
      *   turn/started → item/started{contextCompaction} →
@@ -140,7 +175,7 @@ export class MainThreadInstructionsRefresher {
      * turn/started by the deadline leaves nothing to interrupt — pathological,
      * and the grace still absorbs a late-materializing close.
      */
-    watchForCompaction(client, taps, threadId) {
+    watchForCompaction(client, taps, threadId, signal) {
         const timeoutMs = this.opts.compactTimeoutMs ?? DEFAULT_COMPACT_TIMEOUT_MS;
         const graceMs = this.opts.interruptGraceMs ?? COMPACT_INTERRUPT_GRACE_MS;
         let cancel = () => { };
@@ -151,6 +186,7 @@ export class MainThreadInstructionsRefresher {
             let settled = false;
             let unregister = () => { };
             let graceTimer;
+            const onAbort = () => expire('aborted by the caller');
             const finish = (err) => {
                 if (settled)
                     return;
@@ -158,14 +194,21 @@ export class MainThreadInstructionsRefresher {
                 clearTimeout(timer);
                 if (graceTimer)
                     clearTimeout(graceTimer);
+                signal?.removeEventListener('abort', onAbort);
                 unregister();
                 if (err)
                     reject(err);
                 else
                     resolve();
             };
-            const timer = setTimeout(() => {
+            // Budget exhausted (timer) or the caller aborted (idle auto-compact
+            // budget): interrupt best-effort and hold the grace for the turn to
+            // close; past it the turn may still be running → stalled.
+            const expire = (why) => {
+                if (settled || interrupted)
+                    return;
                 interrupted = true;
+                clearTimeout(timer);
                 if (compactionTurnId) {
                     // Best-effort and non-lethal: an unanswered interrupt must expire
                     // with the grace window, not arm the client's default assume-hung
@@ -174,8 +217,13 @@ export class MainThreadInstructionsRefresher {
                         .sendRequest('turn/interrupt', { threadId, turnId: compactionTurnId }, { timeoutMs: graceMs, lethalTimeout: false })
                         .catch(() => { });
                 }
-                graceTimer = setTimeout(() => finish(new CompactionStalledError(`compaction did not complete within ${timeoutMs}ms (interrupt grace elapsed; the compaction turn may still be running)`)), graceMs);
-            }, timeoutMs);
+                graceTimer = setTimeout(() => finish(new CompactionStalledError(`compaction did not complete (${why}; interrupt grace elapsed; the compaction turn may still be running)`)), graceMs);
+            };
+            const timer = setTimeout(() => expire(`within ${timeoutMs}ms`), timeoutMs);
+            if (signal?.aborted)
+                onAbort();
+            else
+                signal?.addEventListener('abort', onAbort, { once: true });
             // Cancellation resolves (never rejects): the caller cancels only when
             // the request itself already failed, and that error is what it reports.
             cancel = () => finish();
@@ -187,8 +235,20 @@ export class MainThreadInstructionsRefresher {
                     // notifications can arrive after that; waiting out the timeout
                     // would stall the dispatch for the full budget on a dead client.
                     if (notificationThreadId === undefined || notificationThreadId === threadId) {
-                        const msg = params?.message;
-                        finish(new Error(`app-server error during compaction: ${String(msg ?? 'unknown')}`));
+                        // v2 ErrorNotification: { threadId?, turnId?, error: { message,
+                        // codexErrorInfo? }, willRetry }. The adapter's synthetic
+                        // disposal broadcast still carries a top-level `message`.
+                        const p = params;
+                        // A retryable error keeps the turn alive — codex retries the
+                        // model call itself and the compaction still completes or fails
+                        // through turn/completed; bailing here would report a failure
+                        // for a compaction that is still running.
+                        if (p?.willRetry === true)
+                            return;
+                        const msg = p?.error?.message ?? p?.message;
+                        const info = p?.error?.codexErrorInfo;
+                        const infoText = info == null ? '' : ` (${typeof info === 'string' ? info : JSON.stringify(info)})`;
+                        finish(new Error(`app-server error during compaction: ${String(msg ?? 'unknown')}${infoText}`));
                     }
                     return;
                 }
@@ -208,7 +268,7 @@ export class MainThreadInstructionsRefresher {
                         finish();
                     else
                         finish(new Error(interrupted
-                            ? `compaction did not complete within ${timeoutMs}ms (turn closed after interrupt)`
+                            ? 'compaction did not complete within budget (turn closed after interrupt)'
                             : `compaction turn ended without completing (status=${status ?? 'unknown'})`));
                 }
             });

package/dist/runtime-turn.d.ts

@@ -0,0 +1,23 @@
+import { type RuntimeEvent, RuntimeTurnBase, type RuntimeTurnTrigger } from '@parall/agent-core';
+import { TurnSink } from './turn-sink.js';
+/**
+ * One turn of a thread the app-server runs that no dispatch started — a
+ * `spawn_agent` subagent thread. Its notifications are routed into `sink`
+ * by the adapter; the gateway drains `events` as a turn of the subagent's
+ * child session (the first event announces that session with its parent).
+ */
+export declare class CodexRuntimeTurn extends RuntimeTurnBase {
+    readonly trigger: Extract<RuntimeTurnTrigger, {
+        kind: 'subagent';
+    }>;
+    private readonly opts;
+    readonly sink: TurnSink;
+    constructor(sessionKey: string, trigger: Extract<RuntimeTurnTrigger, {
+        kind: 'subagent';
+    }>, opts: {
+        parentSessionKey?: string;
+        onDetach: (reason: string) => void;
+    });
+    protected drain(): AsyncGenerator<RuntimeEvent>;
+}
+//# sourceMappingURL=runtime-turn.d.ts.map

package/dist/runtime-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-turn.d.ts","sourceRoot":"","sources":["../src/runtime-turn.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,eAAe;IAKjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,kBAAkB,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC;IACnE,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;gBAGtB,UAAU,EAAE,MAAM,EACT,OAAO,EAAE,OAAO,CAAC,kBAAkB,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC,EAClD,IAAI,EAAE;QACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;KACpC;cAMc,KAAK,IAAI,cAAc,CAAC,YAAY,CAAC;CAkCvD"}

package/dist/runtime-turn.js

@@ -0,0 +1,56 @@
+import { projectRuntimeEvent, RuntimeTurnBase, } from '@parall/agent-core';
+import { TurnSink } from './turn-sink.js';
+/**
+ * One turn of a thread the app-server runs that no dispatch started — a
+ * `spawn_agent` subagent thread. Its notifications are routed into `sink`
+ * by the adapter; the gateway drains `events` as a turn of the subagent's
+ * child session (the first event announces that session with its parent).
+ */
+export class CodexRuntimeTurn extends RuntimeTurnBase {
+    trigger;
+    opts;
+    sink;
+    constructor(sessionKey, trigger, opts) {
+        super(sessionKey, trigger, opts.onDetach);
+        this.trigger = trigger;
+        this.opts = opts;
+        this.sink = new TurnSink(() => this.touch());
+    }
+    async *drain() {
+        yield {
+            type: 'runtime_session',
+            runtimeSessionId: this.trigger.threadId,
+            runtimeLaneKey: this.sessionKey,
+            ...(this.opts.parentSessionKey ? { parentSessionKey: this.opts.parentSessionKey } : {}),
+        };
+        let sawError = false;
+        let sawOutcome = false;
+        while (true) {
+            const envelope = await this.sink.next();
+            if (envelope.kind === 'turn_end') {
+                // A real turn/completed carries its threadId; the sink's close()
+                // sentinel does not — the thread died or the bridge stopped.
+                if (envelope.threadId)
+                    return;
+                if (!sawError) {
+                    yield {
+                        type: 'error',
+                        message: 'subagent turn ended without turn/completed',
+                        groupKey: this.groupKey,
+                    };
+                }
+                if (!sawOutcome)
+                    yield { type: 'turn_outcome', outcome: 'runtime_crash' };
+                return;
+            }
+            const event = envelope.kind === 'error'
+                ? { type: 'error', message: envelope.message }
+                : envelope.event;
+            if (event.type === 'error')
+                sawError = true;
+            if (event.type === 'turn_outcome')
+                sawOutcome = true;
+            yield projectRuntimeEvent(event, this.groupKey);
+        }
+    }
+}

package/dist/session-manager.d.ts

@@ -17,6 +17,8 @@ export declare class CodexSessionManager {
     constructor(mainSessionKey: string, stateFilePath: string, logger?: Logger | undefined);
     isMain(sessionKey: string): boolean;
     getThreadId(sessionKey: string): string | undefined;
+    /** The session (main or fork) that owns a thread the bridge opened. */
+    getSessionKey(threadId: string): string | undefined;
     recordThreadId(sessionKey: string, threadId: string): void;
     /**
      * Record a freshly-STARTED thread together with the sha of the

package/dist/session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAuB5D,KAAK,MAAM,GAAG;IAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,mBAAmB;IAK5B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAN1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAA6B;gBAG5D,cAAc,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,YAAA;IAKlC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAcnD;;;;;;;OAOG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS;IAY1F,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInE,8BAA8B,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAO9D,oBAAoB,IAAI,iBAAiB;IAOzC,WAAW,CAAC,UAAU,EAAE,MAAM;IAK9B,6EAA6E;IAC7E,eAAe;IAYf,OAAO,CAAC,OAAO;IA6Bf,OAAO,CAAC,OAAO;CAuBhB"}
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAuB5D,KAAK,MAAM,GAAG;IAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,mBAAmB;IAK5B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAN1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAA6B;gBAG5D,cAAc,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,YAAA;IAKlC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD,uEAAuE;IACvE,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKnD,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAcnD;;;;;;;OAOG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS;IAY1F,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInE,8BAA8B,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAO9D,oBAAoB,IAAI,iBAAiB;IAOzC,WAAW,CAAC,UAAU,EAAE,MAAM;IAK9B,6EAA6E;IAC7E,eAAe;IAYf,OAAO,CAAC,OAAO;IA6Bf,OAAO,CAAC,OAAO;CAuBhB"}

package/dist/session-manager.js

@@ -24,6 +24,13 @@ export class CodexSessionManager {
     getThreadId(sessionKey) {
         return this.threadIds.get(sessionKey);
     }
+    /** The session (main or fork) that owns a thread the bridge opened. */
+    getSessionKey(threadId) {
+        for (const [sessionKey, id] of this.threadIds)
+            if (id === threadId)
+                return sessionKey;
+        return undefined;
+    }
     recordThreadId(sessionKey, threadId) {
         // An effective-instructions sha is a fact about one specific thread.
         // Recording a DIFFERENT thread id under the same session invalidates it;

package/dist/turn-sink.d.ts

@@ -10,13 +10,15 @@ export type TurnEventEnvelope = {
     kind: 'error';
     message: string;
 };
-/** Per-turn buffered sink backed by an unbounded promise queue. */
+/**
+ * Per-turn buffered sink between notification routing and the turn's
+ * drain. Envelopes queued before close() still drain (a final error pushed
+ * by handleSubprocessClose must reach the consumer before turn_end).
+ */
 export declare class TurnSink {
     private readonly noteActivity?;
     readonly mapper: EventMapper;
     private readonly queue;
-    private resolver;
-    private closed;
     constructor(noteActivity?: (() => void) | undefined);
     touchActivity(): void;
     push(envelope: TurnEventEnvelope): void;

package/dist/turn-sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-sink.d.ts","sourceRoot":"","sources":["../src/turn-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,mEAAmE;AACnE,qBAAa,QAAQ;IAMP,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAL1C,QAAQ,CAAC,MAAM,cAAqB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAqD;IACrE,OAAO,CAAC,MAAM,CAAS;gBAEM,YAAY,CAAC,GAAE,MAAM,IAAI,aAAA;IAEtD,aAAa;IAIb,IAAI,CAAC,QAAQ,EAAE,iBAAiB;IAWhC,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAelC,KAAK;IAOL;kCAC8B;IAC9B,IAAI,QAAQ,IAAI,OAAO,CAEtB;CACF"}
+{"version":3,"file":"turn-sink.d.ts","sourceRoot":"","sources":["../src/turn-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;;GAIG;AACH,qBAAa,QAAQ;IAIP,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAH1C,QAAQ,CAAC,MAAM,cAAqB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;gBAEhC,YAAY,CAAC,GAAE,MAAM,IAAI,aAAA;IAEtD,aAAa;IAIb,IAAI,CAAC,QAAQ,EAAE,iBAAiB;IAI1B,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAKxC,KAAK;IAIL;kCAC8B;IAC9B,IAAI,QAAQ,IAAI,OAAO,CAEtB;CACF"}

package/dist/turn-sink.js

@@ -1,11 +1,14 @@
+import { AsyncQueue } from '@parall/agent-core/internal/async-queue';
 import { EventMapper } from './event-mapping.js';
-/** Per-turn buffered sink backed by an unbounded promise queue. */
+/**
+ * Per-turn buffered sink between notification routing and the turn's
+ * drain. Envelopes queued before close() still drain (a final error pushed
+ * by handleSubprocessClose must reach the consumer before turn_end).
+ */
 export class TurnSink {
     noteActivity;
     mapper = new EventMapper();
-    queue = [];
-    resolver = null;
-    closed = false;
+    queue = new AsyncQueue();
     constructor(noteActivity) {
         this.noteActivity = noteActivity;
     }
@@ -13,40 +16,18 @@ export class TurnSink {
         this.noteActivity?.();
     }
     push(envelope) {
-        if (this.closed)
-            return;
-        if (this.resolver) {
-            const r = this.resolver;
-            this.resolver = null;
-            r(envelope);
-            return;
-        }
         this.queue.push(envelope);
     }
-    next() {
-        // Drain any queued envelopes first, even after close(). Otherwise a final
-        // error envelope enqueued right before close() (e.g. by
-        // handleSubprocessClose) is silently dropped because the consumer would
-        // see turn_end before it.
-        const pending = this.queue.shift();
-        if (pending)
-            return Promise.resolve(pending);
-        if (this.closed) {
-            return Promise.resolve({ kind: 'turn_end' });
-        }
-        return new Promise((resolve) => {
-            this.resolver = resolve;
-        });
+    async next() {
+        const result = await this.queue.next();
+        return result.done ? { kind: 'turn_end' } : result.value;
     }
     close() {
-        this.closed = true;
-        const r = this.resolver;
-        this.resolver = null;
-        r?.({ kind: 'turn_end' });
+        this.queue.close();
     }
     /** True once close() ran — the sink's terminal state (queued envelopes may
      * still drain via next()). */
     get isClosed() {
-        return this.closed;
+        return this.queue.isClosed;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.59.0",
+  "version": "1.60.0",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "src"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.59.0",
-    "@parall/cli": "1.59.0",
-    "@parall/sdk": "1.59.0"
+    "@parall/cli": "1.60.0",
+    "@parall/agent-core": "1.60.0",
+    "@parall/sdk": "1.60.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",