mcp-codex-worker 0.1.11 → 0.1.13

package/dist/src/task/task-store.js

@@ -0,0 +1,104 @@
+import { isTerminalStatus } from './task-state.js';
+import { isValidTransition } from './fsm-transitions.js';
+/**
+ * In-memory task store with FSM-validated state transitions.
+ *
+ * This is the single source of truth for task state. It enforces the FSM at
+ * the data layer — illegal transitions are rejected before any mutation occurs.
+ *
+ * Terminal tasks can be evicted by age to prevent unbounded memory growth.
+ */
+export class TaskStore {
+    tasks = new Map();
+    /** Store a new task. Overwrites if the ID already exists. */
+    create(task) {
+        this.tasks.set(task.id, task);
+    }
+    /** Retrieve a task by its unique ID. */
+    get(id) {
+        return this.tasks.get(id);
+    }
+    /** Linear scan for a task matching the given session ID. */
+    getBySessionId(sessionId) {
+        for (const task of this.tasks.values()) {
+            if (task.sessionId === sessionId)
+                return task;
+        }
+        return undefined;
+    }
+    /** Return all tasks as an array. */
+    getAll() {
+        return [...this.tasks.values()];
+    }
+    /**
+     * Transition a task to a new status.
+     *
+     * Returns `true` if the transition was valid and applied, `false` if the
+     * task was not found or the transition is illegal per the FSM.
+     */
+    updateStatus(id, next) {
+        const task = this.tasks.get(id);
+        if (!task)
+            return false;
+        if (!isValidTransition(task.status, next))
+            return false;
+        const now = new Date().toISOString();
+        task.status = next;
+        task.updatedAt = now;
+        if (isTerminalStatus(next)) {
+            task.completedAt = now;
+        }
+        return true;
+    }
+    /**
+     * Apply a partial update to a task. If the update includes a `status`
+     * change, the FSM is validated first — an illegal transition causes the
+     * entire update to be rejected (returns `undefined`).
+     */
+    update(id, updates) {
+        const task = this.tasks.get(id);
+        if (!task)
+            return undefined;
+        // Validate status transition if status is being changed
+        if (updates.status !== undefined && updates.status !== task.status) {
+            if (!isValidTransition(task.status, updates.status))
+                return undefined;
+        }
+        const now = new Date().toISOString();
+        Object.assign(task, updates, { updatedAt: now });
+        if (updates.status !== undefined && isTerminalStatus(updates.status)) {
+            task.completedAt = now;
+        }
+        return task;
+    }
+    /** Remove a task by ID. Returns `true` if it existed. */
+    delete(id) {
+        return this.tasks.delete(id);
+    }
+    /**
+     * Remove terminal tasks whose `updatedAt` timestamp is older than
+     * `maxAgeMs` milliseconds from now.
+     *
+     * Returns the number of tasks evicted.
+     */
+    evict(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        let count = 0;
+        for (const [id, task] of this.tasks) {
+            if (isTerminalStatus(task.status) && new Date(task.updatedAt).getTime() < cutoff) {
+                this.tasks.delete(id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Remove all tasks. */
+    clear() {
+        this.tasks.clear();
+    }
+    /** Return the number of stored tasks. */
+    size() {
+        return this.tasks.size;
+    }
+}
+//# sourceMappingURL=task-store.js.map

package/dist/src/task/task-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-store.js","sourceRoot":"","sources":["../../../src/task/task-store.ts"],"names":[],"mappings":"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"}

package/dist/src/task/wire-state-mapper.d.ts

@@ -0,0 +1,21 @@
+import { TaskStatus } from './task-state.js';
+/**
+ * SEP-1686 wire states — the 7 status values visible to MCP clients.
+ * Spec reference: §4.2
+ */
+export type WireState = 'submitted' | 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled' | 'unknown';
+/**
+ * Maps an internal 10-state TaskStatus to a SEP-1686 wire state.
+ *
+ * Uses an exhaustive switch (no default) so TypeScript raises a compile error
+ * if a new TaskStatus variant is added without updating this mapping.
+ */
+export declare function mapToWireState(status: TaskStatus): WireState;
+/**
+ * Maps an internal 10-state TaskStatus to a short bracketed display badge
+ * for resource renders and UI.
+ *
+ * Uses an exhaustive switch (no default) so TypeScript raises a compile error
+ * if a new TaskStatus variant is added without updating this mapping.
+ */
+export declare function mapToDisplay(status: TaskStatus): string;

package/dist/src/task/wire-state-mapper.js

@@ -0,0 +1,63 @@
+import { TaskStatus } from './task-state.js';
+/**
+ * Maps an internal 10-state TaskStatus to a SEP-1686 wire state.
+ *
+ * Uses an exhaustive switch (no default) so TypeScript raises a compile error
+ * if a new TaskStatus variant is added without updating this mapping.
+ */
+export function mapToWireState(status) {
+    switch (status) {
+        case TaskStatus.WAITING:
+            return 'submitted';
+        case TaskStatus.PENDING:
+            return 'submitted';
+        case TaskStatus.RUNNING:
+            return 'working';
+        case TaskStatus.RATE_LIMITED:
+            return 'working';
+        case TaskStatus.WAITING_ANSWER:
+            return 'input_required';
+        case TaskStatus.COMPLETED:
+            return 'completed';
+        case TaskStatus.FAILED:
+            return 'failed';
+        case TaskStatus.TIMED_OUT:
+            return 'failed';
+        case TaskStatus.CANCELLED:
+            return 'cancelled';
+        case TaskStatus.UNKNOWN:
+            return 'unknown';
+    }
+}
+/**
+ * Maps an internal 10-state TaskStatus to a short bracketed display badge
+ * for resource renders and UI.
+ *
+ * Uses an exhaustive switch (no default) so TypeScript raises a compile error
+ * if a new TaskStatus variant is added without updating this mapping.
+ */
+export function mapToDisplay(status) {
+    switch (status) {
+        case TaskStatus.WAITING:
+            return '[wait]';
+        case TaskStatus.PENDING:
+            return '[wait]';
+        case TaskStatus.RUNNING:
+            return '[busy]';
+        case TaskStatus.RATE_LIMITED:
+            return '[rate]';
+        case TaskStatus.WAITING_ANSWER:
+            return '[input]';
+        case TaskStatus.COMPLETED:
+            return '[done]';
+        case TaskStatus.FAILED:
+            return '[fail]';
+        case TaskStatus.TIMED_OUT:
+            return '[time]';
+        case TaskStatus.CANCELLED:
+            return '[cncl]';
+        case TaskStatus.UNKNOWN:
+            return '[???]';
+    }
+}
+//# sourceMappingURL=wire-state-mapper.js.map

package/dist/src/task/wire-state-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-state-mapper.js","sourceRoot":"","sources":["../../../src/task/wire-state-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAe7C;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,WAAW,CAAC;QACrB,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,WAAW,CAAC;QACrB,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,SAAS,CAAC;QACnB,KAAK,UAAU,CAAC,YAAY;YAC1B,OAAO,SAAS,CAAC;QACnB,KAAK,UAAU,CAAC,cAAc;YAC5B,OAAO,gBAAgB,CAAC;QAC1B,KAAK,UAAU,CAAC,SAAS;YACvB,OAAO,WAAW,CAAC;QACrB,KAAK,UAAU,CAAC,MAAM;YACpB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,SAAS;YACvB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,SAAS;YACvB,OAAO,WAAW,CAAC;QACrB,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB;IAC7C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,YAAY;YAC1B,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,cAAc;YAC5B,OAAO,SAAS,CAAC;QACnB,KAAK,UAAU,CAAC,SAAS;YACvB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,MAAM;YACpB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,SAAS;YACvB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,SAAS;YACvB,OAAO,QAAQ,CAAC;QAClB,KAAK,UAAU,CAAC,OAAO;YACrB,OAAO,OAAO,CAAC;IACnB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-codex-worker",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "MCP server bridge for Codex app-server",
   "type": "module",
   "main": "dist/src/index.js",
@@ -43,6 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "tsx": "^4.20.6",
+    "unique-names-generator": "^4.7.1",
     "zod": "^3.24.4"
   },
   "devDependencies": {

package/src/execution/base-adapter.ts

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// BaseProviderAdapter — Template Method pattern for provider lifecycle
+// Spec reference: §3.4
+// ---------------------------------------------------------------------------
+
+import type { TaskHandle } from '../task/task-handle.js';
+import type { Provider } from '../task/task-state.js';
+import type { ProviderCapabilities } from './provider-capabilities.js';
+
+// ---------------------------------------------------------------------------
+// Supporting types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options passed to `BaseProviderAdapter.spawn()` to start a provider session.
+ */
+export interface ProviderSpawnOptions {
+  taskId: string;
+  prompt: string;
+  cwd: string;
+  timeout: number;
+  model?: string;
+}
+
+/**
+ * Result of an availability check on a provider adapter.
+ */
+export type AvailabilityResult =
+  | { available: true }
+  | { available: false; reason: string };
+
+// ---------------------------------------------------------------------------
+// Abstract class
+// ---------------------------------------------------------------------------
+
+/**
+ * Base class for all provider adapters.
+ *
+ * Implements the Template Method pattern: `spawn()` provides the common
+ * lifecycle skeleton (abort controller, timeout, error handling) and
+ * delegates the actual provider interaction to `executeSession()`.
+ */
+export abstract class BaseProviderAdapter {
+  /** Unique provider identifier. */
+  abstract readonly id: Provider;
+
+  /** Human-readable display name. */
+  abstract readonly displayName: string;
+
+  // -- Abstract methods (subclasses must implement) --------------------------
+
+  /** Check whether the provider is currently available. */
+  abstract checkAvailability(): AvailabilityResult;
+
+  /** Return the capability matrix for this provider. */
+  abstract getCapabilities(): ProviderCapabilities;
+
+  /** Return runtime statistics for observability. */
+  abstract getStats(): Record<string, unknown>;
+
+  /**
+   * Template Method hook — the actual provider session logic.
+   * Subclasses implement this to drive the provider (spawn process, call API, etc.).
+   */
+  protected abstract executeSession(
+    handle: TaskHandle,
+    prompt: string,
+    signal: AbortSignal,
+    options: ProviderSpawnOptions,
+  ): Promise<void>;
+
+  // -- Public lifecycle methods ---------------------------------------------
+
+  /**
+   * Spawn a provider session for the given task.
+   *
+   * Template method: checks terminal state, sets up AbortController + timeout,
+   * calls `executeSession`, and handles errors.
+   */
+  async spawn(options: ProviderSpawnOptions, handle: TaskHandle): Promise<void> {
+    // Guard: do nothing if already in a terminal state
+    if (handle.isTerminal()) {
+      return;
+    }
+
+    const controller = new AbortController();
+    handle.registerAbort(controller);
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    if (options.timeout > 0) {
+      timer = setTimeout(() => {
+        controller.abort();
+      }, options.timeout);
+      // Allow the Node.js process to exit even if this timer is pending
+      if (timer && typeof timer === 'object' && 'unref' in timer) {
+        timer.unref();
+      }
+    }
+
+    try {
+      await this.executeSession(handle, options.prompt, controller.signal, options);
+    } catch (err: unknown) {
+      if (controller.signal.aborted) {
+        handle.markCancelled('Session timed out');
+      } else {
+        const message = err instanceof Error ? err.message : String(err);
+        handle.markFailed(message);
+      }
+    } finally {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      handle.unregisterAbort();
+    }
+  }
+
+  /**
+   * Attempt to abort a running task by ID.
+   * Default implementation returns false (not supported).
+   */
+  async abort(_taskId: string): Promise<boolean> {
+    return false;
+  }
+
+  /**
+   * Graceful shutdown hook. Called when the server is stopping.
+   * Default implementation is a no-op.
+   */
+  async shutdown(): Promise<void> {
+    // no-op by default
+  }
+}

package/src/execution/claude-adapter.ts

@@ -0,0 +1,40 @@
+// ---------------------------------------------------------------------------
+// ClaudeAdapter — Phase 2 stub
+// Spec reference: §3.4
+// ---------------------------------------------------------------------------
+
+import type { Provider } from '../task/task-state.js';
+import type { TaskHandle } from '../task/task-handle.js';
+import type { ProviderCapabilities } from './provider-capabilities.js';
+import { CLAUDE_CAPABILITIES } from './provider-capabilities.js';
+import {
+  BaseProviderAdapter,
+  type ProviderSpawnOptions,
+  type AvailabilityResult,
+} from './base-adapter.js';
+
+export class ClaudeAdapter extends BaseProviderAdapter {
+  readonly id: Provider = 'claude-cli';
+  readonly displayName = 'Claude';
+
+  checkAvailability(): AvailabilityResult {
+    return { available: false, reason: 'Phase 2 — not yet implemented' };
+  }
+
+  getCapabilities(): ProviderCapabilities {
+    return CLAUDE_CAPABILITIES;
+  }
+
+  getStats(): Record<string, unknown> {
+    return {};
+  }
+
+  protected async executeSession(
+    _handle: TaskHandle,
+    _prompt: string,
+    _signal: AbortSignal,
+    _options: ProviderSpawnOptions,
+  ): Promise<void> {
+    throw new Error('Not implemented — Phase 2');
+  }
+}

package/src/execution/codex-adapter.ts

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// CodexAdapter — wraps CodexRuntime behind the BaseProviderAdapter contract
+// Spec reference: §3.4
+// ---------------------------------------------------------------------------
+
+import type { Provider } from '../task/task-state.js';
+import type { TaskHandle } from '../task/task-handle.js';
+import type { ProviderCapabilities } from './provider-capabilities.js';
+import { CODEX_CAPABILITIES } from './provider-capabilities.js';
+import {
+  BaseProviderAdapter,
+  type ProviderSpawnOptions,
+  type AvailabilityResult,
+} from './base-adapter.js';
+import type { CodexRuntime } from '../services/codex-runtime.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface CodexAdapterOptions {
+  command?: string;
+  args?: string[];
+  env?: NodeJS.ProcessEnv;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+export class CodexAdapter extends BaseProviderAdapter {
+  readonly id: Provider = 'codex';
+  readonly displayName = 'Codex';
+
+  private readonly options: CodexAdapterOptions;
+  private runtime?: CodexRuntime;
+
+  constructor(options: CodexAdapterOptions) {
+    super();
+    this.options = options;
+  }
+
+  checkAvailability(): AvailabilityResult {
+    return { available: true };
+  }
+
+  getCapabilities(): ProviderCapabilities {
+    return CODEX_CAPABILITIES;
+  }
+
+  getStats(): Record<string, unknown> {
+    return {};
+  }
+
+  protected async executeSession(
+    _handle: TaskHandle,
+    _prompt: string,
+    _signal: AbortSignal,
+    _options: ProviderSpawnOptions,
+  ): Promise<void> {
+    throw new Error('CodexAdapter.executeSession is not yet implemented');
+  }
+
+  async shutdown(): Promise<void> {
+    await this.runtime?.shutdown();
+  }
+}

package/src/execution/codex-pause-flow.ts

@@ -0,0 +1,225 @@
+import type { AppServerClient } from '../services/app-server-client.js';
+import type { TaskHandle } from '../task/task-handle.js';
+import type { PendingQuestion } from '../task/task-state.js';
+import type { JsonLineRequest, PendingServerRequest } from '../types/codex.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+function asArray(value: unknown): unknown[] | undefined {
+  return Array.isArray(value) ? value : undefined;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Translation: Codex server-request → PendingQuestion
+// ---------------------------------------------------------------------------
+
+/**
+ * Translate a raw Codex JSON-RPC server request into a provider-blind
+ * PendingQuestion variant.
+ *
+ * Returns `null` for:
+ * - Guardian Subagent auto-approval events (method contains `autoApprovalReview`)
+ * - Unrecognised / unmapped methods
+ *
+ * Spec reference: §6.1, §6.2
+ */
+export function translateCodexRequestToPendingQuestion(
+  req: JsonLineRequest,
+): PendingQuestion | null {
+  // Guardian Subagent bypass (PR #13860) — never surface as a pause
+  if (req.method.includes('autoApprovalReview')) {
+    return null;
+  }
+
+  const params = asObject(req.params);
+  const requestId = String(req.id);
+
+  switch (req.method) {
+    // -- user_input --------------------------------------------------------
+    case 'tool/requestUserInput':
+    case 'item/tool/requestUserInput': {
+      const rawQuestions = asArray(params?.questions) ?? [];
+      const questions = rawQuestions.map((raw) => {
+        const q = asObject(raw) ?? {};
+        return {
+          id: asString(q.id) ?? '',
+          text: asString(q.text) ?? asString(q.question) ?? '',
+          ...(asArray(q.options)
+            ? { options: (q.options as unknown[]).map(String) }
+            : {}),
+          ...(q.isOther !== undefined || q.allowEmpty !== undefined
+            ? { allowFreeform: Boolean(q.isOther ?? q.allowEmpty) }
+            : {}),
+        };
+      });
+      return { type: 'user_input', requestId, questions };
+    }
+
+    // -- command_approval --------------------------------------------------
+    case 'item/commandExecution/requestApproval':
+    case 'execCommandApproval': {
+      const command = asString(params?.command) ?? '';
+      const sandboxPolicy = asString(params?.sandbox_policy) ?? asString(params?.sandboxPolicy);
+      return {
+        type: 'command_approval',
+        requestId,
+        command,
+        ...(sandboxPolicy !== undefined ? { sandboxPolicy } : {}),
+      };
+    }
+
+    // -- file_approval -----------------------------------------------------
+    case 'item/fileChange/requestApproval':
+    case 'applyPatchApproval': {
+      const rawChanges = asArray(params?.file_changes) ?? asArray(params?.fileChanges) ?? [];
+      const fileChanges = rawChanges.map((raw) => {
+        const fc = asObject(raw) ?? {};
+        return {
+          path: asString(fc.path) ?? '',
+          patch: asString(fc.patch) ?? '',
+        };
+      });
+      return { type: 'file_approval', requestId, fileChanges };
+    }
+
+    // -- elicitation -------------------------------------------------------
+    case 'mcpServer/elicitation/request': {
+      const serverName = asString(params?.server_name) ?? asString(params?.serverName);
+      const message = asString(params?.message) ?? '';
+      const schema = params?.schema;
+      return {
+        type: 'elicitation',
+        requestId,
+        ...(serverName !== undefined ? { serverName } : {}),
+        message,
+        ...(schema !== undefined ? { schema } : {}),
+      };
+    }
+
+    // -- dynamic_tool ------------------------------------------------------
+    case 'item/tool/call': {
+      const toolName = asString(params?.tool_name) ?? asString(params?.toolName) ?? '';
+      const rawArgs = params?.arguments;
+      const args =
+        typeof rawArgs === 'string'
+          ? rawArgs
+          : rawArgs !== undefined
+            ? JSON.stringify(rawArgs)
+            : '{}';
+      return { type: 'dynamic_tool', requestId, toolName, arguments: args };
+    }
+
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Elicitation auto-decline (Issue #11816 workaround)
+// ---------------------------------------------------------------------------
+
+const ELICITATION_AUTO_DECLINE_MS = 30_000;
+
+function scheduleElicitationAutoDecline(
+  client: AppServerClient,
+  handle: TaskHandle,
+  question: Extract<PendingQuestion, { type: 'elicitation' }>,
+  timeoutMs: number = ELICITATION_AUTO_DECLINE_MS,
+): void {
+  const timer = setTimeout(() => {
+    const still = handle
+      .getPendingQuestions()
+      .find((q) => q.requestId === question.requestId);
+    if (!still) return;
+
+    client
+      .respondToServerRequest(question.requestId, {
+        action: 'decline',
+        content: {},
+      })
+      .catch(() => {});
+
+    const head = handle.getPendingQuestions()[0];
+    if (head?.requestId === question.requestId) {
+      handle.dequeuePendingQuestion();
+    }
+
+    handle.writeOutput(
+      `[elicitation] auto-declined after ${timeoutMs}ms (issue #11816 workaround)`,
+    );
+  }, timeoutMs);
+  timer.unref();
+}
+
+// ---------------------------------------------------------------------------
+// Attachment: wire pause-flow onto an AppServerClient + TaskHandle
+// ---------------------------------------------------------------------------
+
+function extractThreadIdFromParams(params: unknown): string | undefined {
+  const obj = asObject(params);
+  const threadId = obj?.threadId;
+  if (typeof threadId === 'string') return threadId;
+  const thread = asObject(obj?.thread);
+  if (typeof thread?.id === 'string') return thread.id;
+  return undefined;
+}
+
+/**
+ * Listen for `server-request` events on the AppServerClient, translate each
+ * to a PendingQuestion, queue it on the handle, and transition to
+ * WAITING_ANSWER. Returns an unsubscribe function.
+ *
+ * Spec reference: §6.2, §6.3
+ */
+export function attachPauseFlow(
+  client: AppServerClient,
+  handle: TaskHandle,
+  threadId: string,
+): () => void {
+  const onServerRequest = (pending: PendingServerRequest) => {
+    const reqThreadId = extractThreadIdFromParams(pending.params);
+    if (reqThreadId !== threadId) return;
+
+    // Guardian Subagent bypass — log but don't surface
+    if (pending.method.includes('autoApprovalReview')) {
+      handle.writeOutputFileOnly(`[guardian] ${pending.method}`);
+      return;
+    }
+
+    const req: JsonLineRequest = {
+      method: pending.method,
+      id: pending.id,
+      params: pending.params,
+    };
+
+    const question = translateCodexRequestToPendingQuestion(req);
+    if (!question) return;
+
+    handle.queuePendingQuestion(question);
+    if (!handle.isTerminal()) {
+      handle.markInputRequired();
+    }
+
+    if (question.type === 'elicitation') {
+      scheduleElicitationAutoDecline(client, handle, question);
+    }
+  };
+
+  client.on('server-request', onServerRequest);
+  return () => {
+    client.off('server-request', onServerRequest);
+  };
+}