@parall/codex-agent 1.45.0 → 1.47.0

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"}

package/dist/jsonrpc-client.js

@@ -1,3 +1,21 @@
+/** JSON-RPC 2.0 spec code for "Method not found". */
+export 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 class JsonRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message || 'JSON-RPC error');
+        this.code = code;
+        this.data = data;
+        this.name = 'JsonRpcError';
+    }
+}
 /** Maximum time to wait for a JSON-RPC response before rejecting. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 /**
@@ -16,6 +34,7 @@ export class JsonRpcStdioClient {
     pending = new Map();
     buffer = '';
     onNotification = null;
+    onServerRequest = null;
     disposed = false;
     constructor(proc, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, killProcess) {
         this.proc = proc;
@@ -30,10 +49,23 @@ export class JsonRpcStdioClient {
     setNotificationHandler(handler) {
         this.onNotification = handler;
     }
-    sendRequest(method, params) {
+    setServerRequestHandler(handler) {
+        this.onServerRequest = handler;
+    }
+    /**
+     * `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, params, options) {
         if (this.disposed) {
             return Promise.reject(new Error('JSON-RPC client disposed'));
         }
+        const timeoutMs = options?.timeoutMs ?? this.requestTimeoutMs;
+        const lethalTimeout = options?.lethalTimeout ?? true;
         const id = this.nextId++;
         const request = { jsonrpc: '2.0', id, method, params };
         const promise = new Promise((resolve, reject) => {
@@ -42,9 +74,11 @@ export class JsonRpcStdioClient {
                 if (!pending)
                     return;
                 this.pending.delete(id);
-                reject(new Error(`JSON-RPC request "${method}" timed out after ${this.requestTimeoutMs}ms`));
-                this.killUnhealthy(new Error(`request "${method}" timed out; subprocess assumed hung`));
-            }, this.requestTimeoutMs);
+                reject(new Error(`JSON-RPC request "${method}" timed out after ${timeoutMs}ms`));
+                if (lethalTimeout) {
+                    this.killUnhealthy(new Error(`request "${method}" timed out; subprocess assumed hung`));
+                }
+            }, timeoutMs);
             this.pending.set(id, { resolve, reject, timer });
         });
         this.writeFrame(request);
@@ -114,21 +148,59 @@ export class JsonRpcStdioClient {
             this.pending.delete(message.id);
             clearTimeout(pending.timer);
             if (message.error) {
-                pending.reject(new Error(message.error.message || 'JSON-RPC error'));
+                pending.reject(new JsonRpcError(message.error.code, message.error.message, message.error.data));
             }
             else {
                 pending.resolve(message.result);
             }
             return;
         }
+        if (isServerRequest(message)) {
+            this.answerServerRequest(message);
+            return;
+        }
         if (isNotification(message)) {
             this.onNotification?.(message.method, message.params);
         }
     }
+    answerServerRequest(request) {
+        let answer;
+        try {
+            answer = this.onServerRequest?.(request.method, request.params);
+        }
+        catch (err) {
+            this.writeFrame({
+                jsonrpc: '2.0',
+                id: request.id,
+                error: { code: -32603, message: `server request handler failed: ${String(err)}` },
+            });
+            return;
+        }
+        if (answer !== undefined) {
+            // undefined → null: a dropped `result` member would produce a frame
+            // that is neither a success nor an error response.
+            this.writeFrame({
+                jsonrpc: '2.0',
+                id: request.id,
+                result: answer.result === undefined ? null : answer.result,
+            });
+            return;
+        }
+        this.writeFrame({
+            jsonrpc: '2.0',
+            id: request.id,
+            error: { code: -32601, message: `unsupported server request: ${request.method}` },
+        });
+    }
 }
 function isResponse(m) {
     return !!m && typeof m === 'object' && 'id' in m && ('result' in m || 'error' in m);
 }
+// A server→client request carries BOTH `method` and `id` (and no
+// result/error). It must be answered — see ServerRequestHandler.
+function isServerRequest(m) {
+    return !!m && typeof m === 'object' && 'method' in m && 'id' in m;
+}
 function isNotification(m) {
     return !!m && typeof m === 'object' && 'method' in m && !('id' in m);
 }

package/dist/server-requests.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the response payload for a server request, or `undefined` when the
+ * method is not one we can meaningfully answer (the JSON-RPC client then
+ * replies -32601, which also unblocks the app-server). Own-property lookup
+ * only — a method named like an Object.prototype member (`toString`,
+ * `constructor`) must fall through to -32601, not return an inherited
+ * function that would serialize into a result-less frame.
+ */
+export declare function answerServerRequest(method: string): unknown | undefined;
+//# sourceMappingURL=server-requests.d.ts.map

package/dist/server-requests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-requests.d.ts","sourceRoot":"","sources":["../src/server-requests.ts"],"names":[],"mappings":"AA6BA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEvE"}

package/dist/server-requests.js

@@ -0,0 +1,39 @@
+/**
+ * Answers for codex app-server server→client requests.
+ *
+ * The bridge runs headless with `approvalPolicy: "never"`, so approval-shaped
+ * requests should not occur — but the protocol allows the app-server to send
+ * them (e.g. a thread that fell back to `on-request`), and an unanswered
+ * request parks its turn until the dispatch deadline. Every known
+ * approval-shaped method is answered with an explicit denial; unknown methods
+ * get a method-not-found error from the JSON-RPC layer (`undefined` here).
+ *
+ * Wire shapes verified against codex-rs 0.144.1
+ * (`app-server-protocol/src/protocol/common.rs` server_request_definitions):
+ * - v2 `item/commandExecution/requestApproval` / `item/fileChange/requestApproval`
+ *   respond `{ decision }` with camelCase variants — `decline` denies but lets
+ *   the turn continue (vs `cancel`, which also interrupts the turn).
+ * - legacy v1 `execCommandApproval` / `applyPatchApproval` (SendUserTurn-era,
+ *   unused by this bridge) respond `{ decision }` with snake_case
+ *   ReviewDecision values.
+ */
+const APPROVAL_DENIALS = {
+    'item/commandExecution/requestApproval': { decision: 'decline' },
+    'item/fileChange/requestApproval': { decision: 'decline' },
+    // NOT listed: `item/permissions/requestApproval` — its response shape is a
+    // permission GRANT (no deny variant), so denial is correctly expressed by
+    // the -32601 error fallback.
+    execCommandApproval: { decision: 'denied' },
+    applyPatchApproval: { decision: 'denied' },
+};
+/**
+ * Returns the response payload for a server request, or `undefined` when the
+ * method is not one we can meaningfully answer (the JSON-RPC client then
+ * replies -32601, which also unblocks the app-server). Own-property lookup
+ * only — a method named like an Object.prototype member (`toString`,
+ * `constructor`) must fall through to -32601, not return an inherited
+ * function that would serialize into a result-less frame.
+ */
+export function answerServerRequest(method) {
+    return Object.hasOwn(APPROVAL_DENIALS, method) ? APPROVAL_DENIALS[method] : undefined;
+}