@parall/codex-agent 1.45.0 → 1.47.0

package/src/index.ts

@@ -4,6 +4,7 @@ import * as os from 'node:os';
 import {
   ParallAgentGateway,
   capabilityBinDir,
+  configureHttpKeepAlive,
   createPlatformConfigManager,
   createLogger,
   createOtelLogger,
@@ -68,6 +69,8 @@ function resolveProviderEnv(): void {
 }
 
 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 {
@@ -205,13 +208,13 @@ async function main() {
       //
       // 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 the next thread that
-      // gets STARTED — codex bakes developerInstructions into a thread at
-      // thread/start and neither resume nor fork replaces them (live-probed on
-      // 0.144.1; the retired workspace-config channel had the same limitation).
-      // So an agent with a long-lived persisted thread keeps the older fragment
-      // text in its prompt until that thread is replaced —
-      // docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
+      // 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;

package/src/instructions-refresh.ts

@@ -0,0 +1,367 @@
+import { createHash } from 'node:crypto';
+import type { GatewayLogger } from '@parall/agent-core';
+import { extractThreadIdFromNotification } from './app-server-protocol.js';
+import {
+  JSON_RPC_METHOD_NOT_FOUND,
+  JsonRpcError,
+  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 function sha256Hex(text: string): string {
+  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;
+
+export type RefreshOutcome =
+  | 'noop'
+  | 'adopted-baseline'
+  | 'refreshed'
+  | 'unsupported'
+  | 'failed'
+  // The compaction turn never closed inside budget + interrupt grace — it
+  // may STILL be running on the thread. dispatch() must not let a busy-thread
+  // turn/start rejection rotate the persisted main thread in this state.
+  | 'stalled';
+
+class CompactionStalledError extends Error {}
+
+export class MainThreadInstructionsRefresher {
+  /**
+   * 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 = false;
+
+  constructor(
+    private readonly 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 = new Map<string, string | undefined>();
+
+  resetForNewSubprocess(): void {
+    this.compactUnsupported = false;
+  }
+
+  /** Canonical facts die with the subprocess that held the threads. */
+  clearThreadState(): void {
+    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: string, threadId: string, instructions: string | undefined): void {
+    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: string, instructions: string | undefined): void {
+    this.canonicalByThread.set(threadId, instructions);
+  }
+
+  /** What the thread's live canonical configuration carries, if opened here. */
+  canonicalFor(threadId: string): string | undefined {
+    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: {
+    client: JsonRpcStdioClient;
+    taps: NotificationTapSource;
+    sessionKey: string;
+    threadId: string;
+    log?: GatewayLogger;
+  }): Promise<RefreshOutcome> {
+    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.
+   */
+  private watchForCompaction(
+    client: JsonRpcStdioClient,
+    taps: NotificationTapSource,
+    threadId: string,
+  ): { done: Promise<void>; cancel: () => void } {
+    const timeoutMs = this.opts.compactTimeoutMs ?? DEFAULT_COMPACT_TIMEOUT_MS;
+    const graceMs = this.opts.interruptGraceMs ?? COMPACT_INTERRUPT_GRACE_MS;
+    let cancel = () => {};
+    const done = new Promise<void>((resolve, reject) => {
+      let itemCompleted = false;
+      let compactionTurnId: string | undefined;
+      let interrupted = false;
+      let settled = false;
+      let unregister = () => {};
+      let graceTimer: NodeJS.Timeout | undefined;
+      const finish = (err?: Error) => {
+        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 as { message?: unknown })?.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: unknown): string | undefined {
+  const item = (params as { item?: { type?: unknown } })?.item;
+  return typeof item?.type === 'string' ? item.type : undefined;
+}
+
+function turnStatus(params: unknown): string | undefined {
+  const turn = (params as { turn?: { status?: unknown } })?.turn;
+  return typeof turn?.status === 'string' ? turn.status : undefined;
+}
+
+function turnIdOf(params: unknown): string | undefined {
+  const turn = (params as { turn?: { id?: unknown } })?.turn;
+  return typeof turn?.id === 'string' ? turn.id : undefined;
+}
+
+function errToString(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/jsonrpc-client.ts

@@ -24,6 +24,47 @@ 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 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 {
+  constructor(
+    readonly code: number,
+    message: string,
+    readonly data?: unknown,
+  ) {
+    super(message || 'JSON-RPC error');
+    this.name = 'JsonRpcError';
+  }
+}
+
 type Pending = {
   resolve: (result: unknown) => void;
   reject: (err: Error) => void;
@@ -46,6 +87,7 @@ export class JsonRpcStdioClient {
   private readonly pending = new Map<JsonRpcId, Pending>();
   private buffer = '';
   private onNotification: NotificationHandler | null = null;
+  private onServerRequest: ServerRequestHandler | null = null;
   private disposed = false;
 
   constructor(
@@ -64,10 +106,28 @@ export class JsonRpcStdioClient {
     this.onNotification = handler;
   }
 
-  sendRequest(method: string, params?: unknown): Promise<unknown> {
+  setServerRequestHandler(handler: ServerRequestHandler) {
+    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: string,
+    params?: unknown,
+    options?: { timeoutMs?: number; lethalTimeout?: boolean },
+  ): Promise<unknown> {
     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: JsonRpcRequest = { jsonrpc: '2.0', id, method, params };
     const promise = new Promise<unknown>((resolve, reject) => {
@@ -75,11 +135,11 @@ export class JsonRpcStdioClient {
         const pending = this.pending.get(id);
         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);
@@ -150,23 +210,65 @@ 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);
     }
   }
+
+  private answerServerRequest(request: JsonRpcRequest) {
+    let answer: ServerRequestAnswer;
+    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: unknown): m is JsonRpcResponse {
   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: unknown): m is JsonRpcRequest {
+  return !!m && typeof m === 'object' && 'method' in m && 'id' in m;
+}
+
 function isNotification(m: unknown): m is JsonRpcNotification {
   return !!m && typeof m === 'object' && 'method' in m && !('id' in m);
 }

package/src/server-requests.ts

@@ -0,0 +1,40 @@
+/**
+ * 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: Record<string, unknown> = {
+  '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: string): unknown | undefined {
+  return Object.hasOwn(APPROVAL_DENIALS, method) ? APPROVAL_DENIALS[method] : undefined;
+}