@parall/codex-agent 1.44.0 → 1.46.0

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import * as os from 'node:os';
-import { ParallAgentGateway, capabilityBinDir, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } from '@parall/agent-core';
+import { ParallAgentGateway, capabilityBinDir, configureHttpKeepAlive, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } 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';
 import { CodexSessionManager } from './session-manager.js';
-import { ensureCodexWorkspace, ensureParallProvider, ensureWorkspaceTrusted, isParallProxyMode, writeCodexSystemPrompt, } from './workspace.js';
+import { ensureCodexWorkspace, ensureParallProvider, isParallProxyMode, writeCodexSystemPrompt, } from './workspace.js';
 const log = createLogger('codex-agent');
 let activeLog = log;
 async function getAgentMeWithLegacyFallback(client, orgId) {
@@ -38,6 +38,8 @@ 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');
     activeLog = createOtelLogger('agent', 'codex-agent');
     try {
@@ -52,7 +54,6 @@ async function main() {
         const agentUserId = me.id;
         const agentLog = childLogger(activeLog, agentUserId);
         activeLog = agentLog;
-        ensureWorkspaceTrusted(config.codexHome, config.workspaceDir, agentLog);
         const useParallProvider = isParallProxyMode();
         if (useParallProvider) {
             ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
@@ -89,11 +90,14 @@ async function main() {
             materializeChannelCapabilities(config.stateDir, caps, agentLog);
             return caps.map((c) => c.fragment);
         };
-        // Assemble the workspace AFTER the first config fetch so
-        // developer_instructions carries the capability declarations from boot.
+        // Assemble the workspace AFTER the first config fetch so the platform
+        // prompt carries the capability declarations from boot.
         const bootCapabilityFragments = applyChannelCapabilities();
         let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
-        ensureCodexWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
+        // Platform instructions are delivered per-thread via the app-server's
+        // developerInstructions param — no workspace config file, no dependence
+        // on codex's workspace-trust state, no writes to the operator's config.
+        const developerInstructions = ensureCodexWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
         // Model precedence: operator PIN (override) > env > server FLOOR. The server
         // now says which it is via model_is_pin (deriveModelIsPin presence-gates the
         // dual-read: old servers omit it → fall back to model_management). A PIN beats
@@ -120,6 +124,7 @@ async function main() {
             contextDirPath: dispatchContextDirPath(config.stateDir),
             useParallProvider,
             capabilityBinDir: capabilityBinDir(config.stateDir),
+            developerInstructions,
         });
         // Shared by onConfigUpdate + onSessionReady. /agents/me is only consumed as
         // deriveModelIsPin's legacy fallback when the server omits model_is_pin
@@ -145,15 +150,26 @@ async function main() {
                 model: resolveRuntimeModel(isPin, updated.model, config.model) ?? null,
                 reasoningEffort: updated.thinkingEffort ?? config.reasoningEffort ?? null,
             });
-            // Capability heat-update: re-materialize shims + rewrite the prompt
-            // surfaces. The write is refresh-tolerant (warn + retry next refresh);
-            // only a SUCCESSFUL write with a changed fragment set schedules the
-            // lazy app-server restart (developer_instructions loads at spawn).
+            // Capability heat-update: re-materialize shims + rebuild the prompt.
+            // The write is refresh-tolerant (warn + retry next refresh); only a
+            // SUCCESSFUL rebuild with a changed fragment set schedules the lazy
+            // app-server restart.
+            //
+            // What each half of the refresh actually reaches: the shim dir on PATH
+            // makes the granted TOOL work on the agent's next shell command, live,
+            // no restart needed. The refreshed PROMPT reaches (a) every thread
+            // started from here on (thread/start bakes it in), and (b) the
+            // persisted main thread on its next safe dispatch: the restart below
+            // makes the next open a fresh-process thread/resume, which applies the
+            // new value to the thread's canonical configuration, and the adapter
+            // then compacts the thread so the model-visible context is rebuilt from
+            // it (two-plane semantics: src/instructions-refresh.ts).
             const fragments = applyChannelCapabilities();
             const joinedFragments = fragments.join('\n\n');
             let promptWritten = true;
             try {
-                writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+                const refreshedPrompt = writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+                adapter.updateConfig({ developerInstructions: refreshedPrompt });
             }
             catch (err) {
                 promptWritten = false;

package/dist/instructions-refresh.d.ts

@@ -0,0 +1,136 @@
+import type { GatewayLogger } from '@parall/agent-core';
+import { type JsonRpcStdioClient } from './jsonrpc-client.js';
+import type { CodexSessionManager } from './session-manager.js';
+/**
+ * Convergence of platform `developerInstructions` onto the persisted main
+ * thread. codex 0.144.1 keeps the instructions on two planes (verified by
+ * source reading of rust-v0.144.1 plus a raw-request probe against the
+ * pinned CLI with a mock Responses API):
+ *
+ *  - CANONICAL — the session configuration. A `thread/resume` in a process
+ *    where the thread is not already running DOES apply the
+ *    `developerInstructions` param to the reconstructed session (a resume of
+ *    a still-running thread ignores every override and logs a mismatch).
+ *  - EFFECTIVE — what the model actually sees: the initial-context developer
+ *    message living in conversation history. An ordinary post-resume turn
+ *    does NOT re-emit it (`TurnContextItem` does not carry instructions and
+ *    the settings-update diff does not cover them), so after a resume with
+ *    new instructions the model keeps seeing the old text.
+ *
+ * Compaction (`thread/compact/start`, also the auto-compaction path) is the
+ * official convergence point: it rebuilds the initial context from the
+ * CANONICAL configuration into the replacement history — after which every
+ * turn, restart, resume, and further compaction carries the new instructions,
+ * and exactly one instruction block exists (rebuild, not append).
+ *
+ * So the refresh recipe is: get canonical right (the existing lazy-restart →
+ * fresh-process `thread/resume` chain already sends the current instructions),
+ * then trigger one explicit compaction when the thread's last-known EFFECTIVE
+ * instructions differ. The session state file remembers the sha256 of the
+ * effective instructions: recorded when a thread is STARTED (baking makes
+ * them effective immediately) and after a compaction completes — never on
+ * resume alone, which is precisely the plane it does not touch.
+ *
+ * Failure posture (at-least-once, never exactly-once): a refresh that did not
+ * complete is never recorded, so the next dispatch retries. A cleanly FAILED
+ * compaction (turn closed: error, interrupt honored, subprocess died) does
+ * not block the current turn — canonical is already current after the
+ * resume, so it degrades to "old text until the next retry or organic
+ * compaction". The ONE exception is 'stalled': the compaction turn ignored
+ * the interrupt past the grace and may still be running, so dispatch() must
+ * not race turn/start into the busy thread (a rejection there would look
+ * like a stale thread and rotate it) — it keeps the persisted thread,
+ * bounces the subprocess, and errors THIS dispatch for ledger redrive onto a
+ * clean process. Continuity outranks single-dispatch availability. A CLI
+ * without `thread/compact/start` (JSON-RPC -32601) disables further attempts
+ * for the subprocess lifetime (a CLI upgrade implies a respawn) and keeps
+ * the sha unrecorded so a capable CLI converges later.
+ */
+export type NotificationTap = (method: string, params: unknown) => void;
+export interface NotificationTapSource {
+    /** Register a listener for every server notification; returns unregister. */
+    addNotificationTap(tap: NotificationTap): () => void;
+}
+export declare function sha256Hex(text: string): string;
+export type RefreshOutcome = 'noop' | 'adopted-baseline' | 'refreshed' | 'unsupported' | 'failed' | 'stalled';
+export declare class MainThreadInstructionsRefresher {
+    private readonly opts;
+    /**
+     * Set when this subprocess rejected thread/compact/start with
+     * method-not-found (an older CLI). Reset on every spawn via
+     * resetForNewSubprocess() — a CLI upgrade implies a respawn, so each
+     * subprocess gets exactly one probe.
+     */
+    private compactUnsupported;
+    constructor(opts: {
+        sessionManager: Pick<CodexSessionManager, 'getEffectiveInstructionsSha' | 'recordEffectiveInstructionsSha' | 'recordStartedThread'>;
+        log?: GatewayLogger;
+        compactTimeoutMs?: number;
+        /** Test knob for the post-interrupt grace (default 10s). */
+        interruptGraceMs?: number;
+    });
+    /**
+     * Instructions each thread was opened WITH in this process — its live
+     * CANONICAL configuration (same-tick capture of the thread/start /
+     * thread/resume param). Process-local: the adapter clears it whenever the
+     * subprocess goes away (clearThreadState), because a canonical fact only
+     * describes a thread loaded in the CURRENT app-server.
+     */
+    private readonly canonicalByThread;
+    resetForNewSubprocess(): void;
+    /** Canonical facts die with the subprocess that held the threads. */
+    clearThreadState(): void;
+    /**
+     * Thread opened via thread/start: instructions are baked into the initial
+     * context, so canonical AND effective converge the moment the start
+     * succeeds — no compaction involved. Thread id and effective sha persist in
+     * ONE state-file write: a crash between two separate writes would be
+     * indistinguishable from a legacy file, and legacy state is deliberately
+     * adopted without compaction.
+     */
+    recordBaked(sessionKey: string, threadId: string, instructions: string | undefined): void;
+    /**
+     * Thread opened via thread/resume: a fresh-process resume applies the
+     * param to the CANONICAL configuration only — the effective plane is
+     * reconciled separately, never recorded here.
+     */
+    recordResumed(threadId: string, instructions: string | undefined): void;
+    /** What the thread's live canonical configuration carries, if opened here. */
+    canonicalFor(threadId: string): string | undefined;
+    /**
+     * Converge the EFFECTIVE plane after the thread is open in this process.
+     * Compares against the thread's recorded canonical value — the dispatch
+     * guard has already bounced the subprocess if the desired instructions
+     * changed after the open, so canonical is current by the time this runs.
+     */
+    reconcileAfterOpen(args: {
+        client: JsonRpcStdioClient;
+        taps: NotificationTapSource;
+        sessionKey: string;
+        threadId: string;
+        log?: GatewayLogger;
+    }): Promise<RefreshOutcome>;
+    /**
+     * Compaction runs as its own turn on the thread:
+     *   turn/started → item/started{contextCompaction} →
+     *   item/completed{contextCompaction} → turn/completed{status}
+     * (wire sequence captured against the pinned 0.144.1 CLI). Success = the
+     * contextCompaction item completed AND the turn closed; a turn that closes
+     * without the item having completed is a failure. Waiting for turn close —
+     * not just the item — keeps the next turn/start from racing into a thread
+     * that is still finishing the compaction turn.
+     *
+     * Timeout does NOT simply return: past the budget the compaction turn may
+     * still be RUNNING, and handing control back would let dispatch() issue
+     * turn/start against a busy thread — a rejection there is treated as a
+     * stale thread and would ROTATE the persisted main thread (continuity
+     * loss). Instead the watcher interrupts the compaction turn best-effort
+     * and holds a short grace for it to close. A compaction that completes
+     * during the grace still counts as success (late, but the effective plane
+     * DID converge). Residual: a server that has not even emitted
+     * turn/started by the deadline leaves nothing to interrupt — pathological,
+     * and the grace still absorbs a late-materializing close.
+     */
+    private watchForCompaction;
+}
+//# sourceMappingURL=instructions-refresh.d.ts.map

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

@@ -0,0 +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"}

package/dist/instructions-refresh.js

@@ -0,0 +1,244 @@
+import { createHash } from 'node:crypto';
+import { extractThreadIdFromNotification } from './app-server-protocol.js';
+import { JSON_RPC_METHOD_NOT_FOUND, JsonRpcError, } from './jsonrpc-client.js';
+export function sha256Hex(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+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 MainThreadInstructionsRefresher {
+    opts;
+    /**
+     * Set when this subprocess rejected thread/compact/start with
+     * method-not-found (an older CLI). Reset on every spawn via
+     * resetForNewSubprocess() — a CLI upgrade implies a respawn, so each
+     * subprocess gets exactly one probe.
+     */
+    compactUnsupported = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Instructions each thread was opened WITH in this process — its live
+     * CANONICAL configuration (same-tick capture of the thread/start /
+     * thread/resume param). Process-local: the adapter clears it whenever the
+     * subprocess goes away (clearThreadState), because a canonical fact only
+     * describes a thread loaded in the CURRENT app-server.
+     */
+    canonicalByThread = new Map();
+    resetForNewSubprocess() {
+        this.compactUnsupported = false;
+    }
+    /** Canonical facts die with the subprocess that held the threads. */
+    clearThreadState() {
+        this.canonicalByThread.clear();
+    }
+    /**
+     * Thread opened via thread/start: instructions are baked into the initial
+     * context, so canonical AND effective converge the moment the start
+     * succeeds — no compaction involved. Thread id and effective sha persist in
+     * ONE state-file write: a crash between two separate writes would be
+     * indistinguishable from a legacy file, and legacy state is deliberately
+     * adopted without compaction.
+     */
+    recordBaked(sessionKey, threadId, instructions) {
+        this.canonicalByThread.set(threadId, instructions);
+        this.opts.sessionManager.recordStartedThread(sessionKey, threadId, instructions ? sha256Hex(instructions) : undefined);
+    }
+    /**
+     * Thread opened via thread/resume: a fresh-process resume applies the
+     * param to the CANONICAL configuration only — the effective plane is
+     * reconciled separately, never recorded here.
+     */
+    recordResumed(threadId, instructions) {
+        this.canonicalByThread.set(threadId, instructions);
+    }
+    /** What the thread's live canonical configuration carries, if opened here. */
+    canonicalFor(threadId) {
+        return this.canonicalByThread.get(threadId);
+    }
+    /**
+     * Converge the EFFECTIVE plane after the thread is open in this process.
+     * Compares against the thread's recorded canonical value — the dispatch
+     * guard has already bounced the subprocess if the desired instructions
+     * changed after the open, so canonical is current by the time this runs.
+     */
+    async reconcileAfterOpen(args) {
+        const { client, taps, sessionKey, threadId } = args;
+        const log = args.log ?? this.opts.log;
+        const sentInstructions = this.canonicalByThread.get(threadId);
+        if (!sentInstructions)
+            return 'noop';
+        const canonicalSha = sha256Hex(sentInstructions);
+        const effectiveSha = this.opts.sessionManager.getEffectiveInstructionsSha(sessionKey);
+        if (effectiveSha === canonicalSha)
+            return 'noop';
+        if (effectiveSha === undefined) {
+            // State file predates effective-plane tracking (recordBaked persists
+            // thread id + sha in one atomic write, so a crash cannot manufacture
+            // this state for a tracked thread). Adopt the current value as the
+            // baseline WITHOUT forcing a compaction: rolling this feature out
+            // must not compress every existing thread. A staleness inherited from
+            // the pre-tracking era converges at the next instructions change or at
+            // the next organic compaction (canonical is already current by then).
+            this.opts.sessionManager.recordEffectiveInstructionsSha(sessionKey, canonicalSha);
+            log?.info?.(`adopted current platform instructions as effective baseline for thread ${threadId} (no prior record)`);
+            return 'adopted-baseline';
+        }
+        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;
+            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';
+            }
+            log?.warn?.(`platform instructions refresh did not complete (will retry next dispatch; the resumed configuration already carries the new value): ${errToString(err)}`);
+            return 'failed';
+        }
+    }
+    /**
+     * Compaction runs as its own turn on the thread:
+     *   turn/started → item/started{contextCompaction} →
+     *   item/completed{contextCompaction} → turn/completed{status}
+     * (wire sequence captured against the pinned 0.144.1 CLI). Success = the
+     * contextCompaction item completed AND the turn closed; a turn that closes
+     * without the item having completed is a failure. Waiting for turn close —
+     * not just the item — keeps the next turn/start from racing into a thread
+     * that is still finishing the compaction turn.
+     *
+     * Timeout does NOT simply return: past the budget the compaction turn may
+     * still be RUNNING, and handing control back would let dispatch() issue
+     * turn/start against a busy thread — a rejection there is treated as a
+     * stale thread and would ROTATE the persisted main thread (continuity
+     * loss). Instead the watcher interrupts the compaction turn best-effort
+     * and holds a short grace for it to close. A compaction that completes
+     * during the grace still counts as success (late, but the effective plane
+     * DID converge). Residual: a server that has not even emitted
+     * turn/started by the deadline leaves nothing to interrupt — pathological,
+     * and the grace still absorbs a late-materializing close.
+     */
+    watchForCompaction(client, taps, threadId) {
+        const timeoutMs = this.opts.compactTimeoutMs ?? DEFAULT_COMPACT_TIMEOUT_MS;
+        const graceMs = this.opts.interruptGraceMs ?? COMPACT_INTERRUPT_GRACE_MS;
+        let cancel = () => { };
+        const done = new Promise((resolve, reject) => {
+            let itemCompleted = false;
+            let compactionTurnId;
+            let interrupted = false;
+            let settled = false;
+            let unregister = () => { };
+            let graceTimer;
+            const finish = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (graceTimer)
+                    clearTimeout(graceTimer);
+                unregister();
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            const timer = setTimeout(() => {
+                interrupted = true;
+                if (compactionTurnId) {
+                    // Best-effort and non-lethal: an unanswered interrupt must expire
+                    // with the grace window, not arm the client's default assume-hung
+                    // timeout into killing the subprocess minutes later mid-something.
+                    client
+                        .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);
+            // Cancellation resolves (never rejects): the caller cancels only when
+            // the request itself already failed, and that error is what it reports.
+            cancel = () => finish();
+            unregister = taps.addNotificationTap((method, params) => {
+                const notificationThreadId = extractThreadIdFromNotification(params);
+                if (method === 'error') {
+                    // A thread-less error is a global one — including the adapter's
+                    // synthetic subprocess-disposal broadcast. No further compaction
+                    // 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')}`));
+                    }
+                    return;
+                }
+                if (notificationThreadId !== threadId)
+                    return;
+                if (method === 'turn/started') {
+                    compactionTurnId = turnIdOf(params) ?? compactionTurnId;
+                    return;
+                }
+                if (method === 'item/completed' && itemType(params) === 'contextCompaction') {
+                    itemCompleted = true;
+                    return;
+                }
+                if (method === 'turn/completed') {
+                    const status = turnStatus(params);
+                    if (itemCompleted && status !== 'failed')
+                        finish();
+                    else
+                        finish(new Error(interrupted
+                            ? `compaction did not complete within ${timeoutMs}ms (turn closed after interrupt)`
+                            : `compaction turn ended without completing (status=${status ?? 'unknown'})`));
+                }
+            });
+        });
+        // Detached-consumer guard: if the subprocess dies while the
+        // thread/compact/start REQUEST is still in flight, the disposal
+        // broadcast rejects this waiter before reconcileAfterOpen ever awaits
+        // it — and its catch path only cancels, it never consumes `done`. An
+        // unconsumed rejection would crash the bridge (Node's default
+        // unhandled-rejection behavior) on the exact path that is supposed to
+        // degrade and retry. The extra consumer does not affect the success
+        // path's own await.
+        done.catch(() => { });
+        return { done, cancel };
+    }
+}
+function itemType(params) {
+    const item = params?.item;
+    return typeof item?.type === 'string' ? item.type : undefined;
+}
+function turnStatus(params) {
+    const turn = params?.turn;
+    return typeof turn?.status === 'string' ? turn.status : undefined;
+}
+function turnIdOf(params) {
+    const turn = params?.turn;
+    return typeof turn?.id === 'string' ? turn.id : undefined;
+}
+function errToString(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}

package/dist/jsonrpc-client.d.ts

@@ -22,6 +22,40 @@ export type JsonRpcResponse = {
     };
 };
 export type NotificationHandler = (method: string, params: unknown) => void;
+/**
+ * A handled server request's response payload. The wrapper (rather than a
+ * bare `unknown`) makes the "undefined = unhandled" sentinel explicit in the
+ * type — `unknown | undefined` would collapse and hide the contract.
+ *
+ * A `result` of `undefined` is normalized to `null` on the wire: JSON.stringify
+ * DROPS an undefined member, which would emit a frame carrying neither
+ * `result` nor `error` — the app-server may ignore such a frame and keep
+ * waiting, parking the turn (the exact failure this handler exists to
+ * prevent). `null` is a valid JSON-RPC success result.
+ */
+export type ServerRequestAnswer = {
+    result: unknown;
+} | undefined;
+/**
+ * Answers a server→client request. Return `{ result }` to respond, or
+ * `undefined` to have the client reply with a method-not-found error. A
+ * request must never go unanswered — the app-server blocks its turn until a
+ * response arrives, so a dropped request parks that turn forever.
+ */
+export type ServerRequestHandler = (method: string, params: unknown) => ServerRequestAnswer;
+/** JSON-RPC 2.0 spec code for "Method not found". */
+export declare const JSON_RPC_METHOD_NOT_FOUND = -32601;
+/**
+ * Rejection error that preserves the JSON-RPC error object's code (and data),
+ * so callers can branch on protocol-level conditions — e.g. method-not-found
+ * on an older CLI — without matching on server message text, whose wording
+ * shifts between codex versions.
+ */
+export declare class JsonRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
 /**
  * Minimal JSON-RPC 2.0 stdio client used to drive a long-running
  * `codex app-server --listen stdio://` subprocess. Frames are newline
@@ -38,10 +72,23 @@ export declare class JsonRpcStdioClient {
     private readonly pending;
     private buffer;
     private onNotification;
+    private onServerRequest;
     private disposed;
     constructor(proc: ChildProcessWithoutNullStreams, requestTimeoutMs?: number, killProcess?: ((proc: ChildProcessWithoutNullStreams) => void) | undefined);
     setNotificationHandler(handler: NotificationHandler): void;
-    sendRequest(method: string, params?: unknown): Promise<unknown>;
+    setServerRequestHandler(handler: ServerRequestHandler): void;
+    /**
+     * `options.timeoutMs` overrides the client-wide budget for this request.
+     * `options.lethalTimeout: false` makes a timeout reject WITHOUT killing the
+     * subprocess — for best-effort side requests (e.g. the compaction watcher's
+     * turn/interrupt) where "no answer" must not translate into a delayed
+     * subprocess kill landing on an unrelated later dispatch. Default (true)
+     * keeps the existing assume-hung semantics.
+     */
+    sendRequest(method: string, params?: unknown, options?: {
+        timeoutMs?: number;
+        lethalTimeout?: boolean;
+    }): Promise<unknown>;
     sendNotification(method: string, params?: unknown): void;
     isDisposed(): boolean;
     dispose(err: Error): void;
@@ -49,6 +96,7 @@ export declare class JsonRpcStdioClient {
     private killUnhealthy;
     private ingest;
     private handleLine;
+    private answerServerRequest;
 }
 export {};
 //# sourceMappingURL=jsonrpc-client.d.ts.map

package/dist/jsonrpc-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsonrpc-client.d.ts","sourceRoot":"","sources":["../src/jsonrpc-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAEzE,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjC,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAW5E;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAQ3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAT/B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAS;gBAGN,IAAI,EAAE,8BAA8B,EACpC,gBAAgB,GAAE,MAAmC,EACrD,WAAW,CAAC,GAAE,CAAC,IAAI,EAAE,8BAA8B,KAAK,IAAI,aAAA;IAS/E,sBAAsB,CAAC,OAAO,EAAE,mBAAmB;IAInD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB/D,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAMjD,UAAU,IAAI,OAAO;IAIrB,OAAO,CAAC,GAAG,EAAE,KAAK;IAUlB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,MAAM;IAWd,OAAO,CAAC,UAAU;CAyBnB"}
+{"version":3,"file":"jsonrpc-client.d.ts","sourceRoot":"","sources":["../src/jsonrpc-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAEzE,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjC,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,mBAAmB,CAAC;AAE5F,qDAAqD;AACrD,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAEhD;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAEnC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO;gBAFd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,OAAO,YAAA;CAK1B;AAWD;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAS3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAV/B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAS;gBAGN,IAAI,EAAE,8BAA8B,EACpC,gBAAgB,GAAE,MAAmC,EACrD,WAAW,CAAC,GAAE,CAAC,IAAI,EAAE,8BAA8B,KAAK,IAAI,aAAA;IAS/E,sBAAsB,CAAC,OAAO,EAAE,mBAAmB;IAInD,uBAAuB,CAAC,OAAO,EAAE,oBAAoB;IAIrD;;;;;;;OAOG;IACH,WAAW,CACT,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GACxD,OAAO,CAAC,OAAO,CAAC;IAwBnB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAMjD,UAAU,IAAI,OAAO;IAIrB,OAAO,CAAC,GAAG,EAAE,KAAK;IAUlB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,MAAM;IAWd,OAAO,CAAC,UAAU;IAiClB,OAAO,CAAC,mBAAmB;CA4B5B"}