@wjarka/cezarion 0.16.0 → 0.17.0

package/dist/core/codex-app-server-runner.js

@@ -1,9 +1,11 @@
+import { uiAskQuestions } from './ask.js';
 import { summarizeRunnerStderr } from './runner-stderr.js';
 import { randomUUID } from 'node:crypto';
 import { parseEffort } from '../contract/index.js';
 import { isSignalTerminationExit, prependSystemPrompt, trackChildExit } from './agent-runner.js';
+import { codexToolGrantFields } from './runner-tool-grants.js';
 import { signalSession } from './session-process.js';
-import { AUTO_END_DELAY_MS, DEFAULT_RUN_TIMEOUT_MS, KILL_GRACE_MS, } from './runner-runtime.js';
+import { afterExitDrain, AUTO_END_DELAY_MS, DEFAULT_RUN_TIMEOUT_MS, exitDrainBudget, KILL_GRACE_MS, } from './runner-runtime.js';
 import { parseAskRequest } from './ask.js';
 import { readNdjson } from './ndjson.js';
 import { V1TextCoalescer } from './v1-text-coalescer.js';
@@ -11,6 +13,7 @@ import { InputSubmissions } from './input-submissions.js';
 import { codexStreamError } from './codex-stream-error.js';
 import { codexTurnOutcome } from './codex-turn-outcome.js';
 import { codexNetworkIsRestricted, codexPermissionOverrides } from './codex-permissions.js';
+import { codexApproval, isCodexApprovalRequest } from './codex-approvals.js';
 import { cezarToolEnvNames } from '../ci-wait/tools.js';
 import { CodexAppServerRpc, CodexRpcResponseError, codexSpawnError, endCodexAppServer, resolveCodexExecutable, spawnCodexAppServer, waitForCodexAppServerExit, } from './codex-app-server-transport.js';
 import { codexSessionStarted, createCodexUiState, mapCodexNotification, } from './codex-ui-mapper.js';
@@ -19,9 +22,6 @@ import { codexSessionStarted, createCodexUiState, mapCodexNotification, } from '
 const STARTUP_TIMEOUT_MS = 60_000;
 // A retry episode gets one budget, regardless of error/warning frequency.
 const STREAM_RETRY_TIMEOUT_MS = 60_000;
-// After real process exit, allow buffered output to drain before closing pipes
-// a descendant may have inherited. This timer never proves termination.
-const EXIT_DRAIN_MS = 250;
 /**
  * `AgentRunner` over `codex app-server` — the same JSONL transport the VS Code
  * extension and desktop app use (JSON-RPC 2.0, newline-delimited, over
@@ -34,26 +34,24 @@ const EXIT_DRAIN_MS = 250;
  * agent inherits managed permissions; confirmed unmanaged sessions keep cezar's
  * full-access default. Approval policy always belongs to the app-server.
  * Codex has no per-tool allowlist, so
- * `spec.allowedTools` is ignored. `CEZ_CODEX_NETWORK=0` requires a confirmed
+ * `spec.toolGrant` is ignored. `CEZ_CODEX_NETWORK=0` requires a confirmed
  * network restriction without replacing managed filesystem rules.
  */
 /**
  * What the codex app-server receives from each `AgentRunSpec` field (#284).
  * Tool access does not cross this wire: managed permissions belong to Codex;
  * unmanaged sessions use cezar's sandbox choice. The app-server has no per-tool
- * allowlist, so `allowedTools`/`bashAllowlist` are declared dropped
- * rather than mapped (spec 2026-07-17-permission-modes). Held against the
- * recorded JSON-RPC by the harness parity matrix.
+ * allowlist, so `toolGrant` is declared dropped rather than mapped (spec
+ * 2026-07-17-permission-modes). Held against the recorded JSON-RPC by the harness parity matrix.
  */
 export const CODEX_SPEC_SUPPORT = {
-    cezarTools: { honored: true, via: 'thread/start and thread/resume dotted mcp_servers config with env_vars' },
+    cezarTools: { honored: true, via: 'thread/start and thread/resume dotted mcp_servers config with env_vars and default_tools_approval_mode approve' },
     systemPrompt: { honored: true, via: 'prepended to the opening turn/start input through prependSystemPrompt' },
     userPrompt: { honored: true, via: 'turn/start input text' },
     images: { honored: false, reason: 'the adapter sends text input items only; image blocks are dropped' },
     cwd: { honored: true, via: 'spawn cwd, and the thread/start / thread/resume cwd' },
-    allowedTools: { honored: false, reason: 'no per-tool allowlist on the app-server; managed permissions and approval policy belong to Codex' },
+    toolGrant: { honored: false, reason: 'no per-tool allowlist on the app-server, so no command-prefix restriction either; managed permissions and approval policy belong to Codex' },
     restrictNativeDelegation: { honored: true, via: 'thread/start and thread/resume config features.multi_agent=false, features.multi_agent_v2=false (D1)' },
-    bashAllowlist: { honored: false, reason: 'no per-tool allowlist, so no command-prefix restriction either' },
     additionalDirectories: { honored: false, reason: 'no extra-root mapping; managed filesystem permissions belong to Codex' },
     env: { honored: true, via: 'merged over the child env through buildCodexAppServerEnv' },
     model: { honored: true, via: 'thread/start and thread/resume model' },
@@ -134,6 +132,7 @@ class CodexSession {
     agentSubmissionPending = false;
     turnBoundaryVersion = 0;
     pendingUserInput;
+    pendingApprovals = new Map();
     toolCalls = [];
     textChunks = [];
     /** Streamed agentMessage deltas buffered per item — v1 `text` is emitted
@@ -159,13 +158,11 @@ class CodexSession {
     eofKillTimer;
     spawnFailed = null;
     timedOut = false;
-    /** Set the moment WE signal the child (EOF watchdog, cancel, kill switch).
-     *  codex handles the signal and exits 143, so without this the runner reads
-     *  its own teardown as a codex failure (#703). */
+    /** Explicit teardown or automatic cleanup with positive live evidence. */
     terminatedByCezar = false;
-    /** "Has the app-server really terminated?" — the question `child.killed`
-     *  does not answer: it flips on signal delivery, so the SIGTERM this runner
-     *  sends would otherwise veto its own SIGKILL escalation (#844). */
+    explicitEnd = false;
+    automaticCleanupStarted = false;
+    /** Native termination, independent of signal delivery (`child.killed`). */
     hasExited;
     /** Protocol v2 emission — additive alongside v1 (`onEvent` keeps flowing
      *  byte-identical); the channel is `opts.onUiEvent` (RunManager wiring
@@ -191,7 +188,9 @@ class CodexSession {
         // Observe termination BEFORE bootstrap. Pending RPCs cannot own the only
         // path to discovering that their process has already gone (#493).
         const exited = waitForCodexAppServerExit(this.child);
-        let drainTimer;
+        // After real process exit, allow buffered output to drain before closing pipes
+        // a descendant may have inherited. This drain never proves termination.
+        let cancelDrain;
         this.child.on('error', (err) => {
             if (this.child.pid === undefined) {
                 this.spawnFailed = codexSpawnError(err, bin);
@@ -208,9 +207,9 @@ class CodexSession {
             }
             // Do not discard final buffered text on a healthy exit. Revoke RPCs
             // immediately, then bound pipe draining ONLY after physical termination.
+            this.expireApprovals('codex app-server exited', false);
             this.rpc.close('codex app-server exited');
-            drainTimer = setTimeout(() => this.child.stdout.destroy(), EXIT_DRAIN_MS);
-            drainTimer.unref?.();
+            cancelDrain = afterExitDrain(() => this.child.stdout.destroy(), exitDrainBudget(code));
             if (this.stopKillTimer)
                 clearTimeout(this.stopKillTimer);
         });
@@ -242,16 +241,25 @@ class CodexSession {
                     catch {
                         continue;
                     }
-                    // Explicit shutdown suppresses late lifecycle, not passive output.
-                    // Natural exit can overtake the final turn frame: retain its outcome
-                    // without restoring ACK/ask/input authority on the dead connection.
+                    // A method+id is a server REQUEST, even if its method happens to name
+                    // a lifecycle notification. It must never reach the notification mapper.
+                    if (typeof msg.method === 'string' && (typeof msg.id === 'number' || typeof msg.id === 'string')) {
+                        if (this.open)
+                            this.dispatch(msg);
+                        continue;
+                    }
+                    // Drain the final outcome after natural exit without restoring input authority.
                     const finalOutcome = this.stdinOpen && hasExited() &&
                         (msg.method === 'turn/completed' || msg.method === 'turn/failed');
                     if (!this.open && (msg.id !== undefined || (!PASSIVE_OUTPUT_METHODS.has(msg.method ?? '') && !finalOutcome)))
                         continue;
-                    // Child turn lifecycle must reach neither channel (#600).
+                    // Child turns do not reach either channel.
                     if (this.isForeignTurnLifecycle(msg))
                         continue;
+                    // The UI mapper must not retire a live approval on an older turn's tail.
+                    if ((msg.method === 'turn/completed' || msg.method === 'turn/failed') && this.activeTurnId &&
+                        turnIdOf(msg.params ?? {}) && turnIdOf(msg.params ?? {}) !== this.activeTurnId)
+                        continue;
                     // Stale/child retry errors must neither fail nor warn on this turn.
                     if (msg.method === 'error' && !this.isCurrentTurn((msg.params ?? {})))
                         continue;
@@ -263,7 +271,7 @@ class CodexSession {
                     if (!this.startupComplete)
                         this.fail(new Error(`Codex startup stdout closed while waiting for ${this.startupPhase}`));
                     else
-                        this.end();
+                        this.end(false);
                 }
             }
             catch {
@@ -290,8 +298,7 @@ class CodexSession {
             finally {
                 if (deadline)
                     clearTimeout(deadline);
-                if (drainTimer)
-                    clearTimeout(drainTimer);
+                cancelDrain?.();
                 if (this.stopKillTimer)
                     clearTimeout(this.stopKillTimer);
                 if (this.eofTermTimer)
@@ -384,7 +391,7 @@ class CodexSession {
             this.refusedForHuman = true;
             return false;
         }
-        if (!this.open || this.pendingUserInput || this.agentSubmissionPending)
+        if (!this.open || this.pendingUserInput || this.pendingApprovals.size || this.agentSubmissionPending)
             return false;
         this.agentInputReady = false;
         this.agentSubmissionPending = true;
@@ -404,14 +411,14 @@ class CodexSession {
             this.agentSubmissionPending = false;
             if (this.inFlightSubmissionId === submissionId)
                 this.inFlightSubmissionId = undefined;
-            if (this.stdinOpen && this.agentInputReady && !this.pendingUserInput) {
+            if (this.stdinOpen && this.agentInputReady && !this.pendingUserInput && !this.pendingApprovals.size) {
                 this.opts.onAgentInputReady?.();
                 this.scheduleAutoEnd();
             }
         });
     }
     scheduleAutoEnd() {
-        if (!this.opts.autoEndAfterFirstTurn || !this.open || this.autoEndTimer || this.agentSubmissionPending)
+        if (!this.opts.autoEndAfterFirstTurn || !this.open || this.autoEndTimer || this.agentSubmissionPending || this.pendingApprovals.size)
             return;
         this.autoEndTimer = setTimeout(() => {
             this.autoEndTimer = undefined;
@@ -422,7 +429,7 @@ class CodexSession {
     }
     sendMessage(content) {
         this.agentInputReady = false;
-        if (!this.open)
+        if (!this.open || this.pendingApprovals.size)
             return false;
         if (this.autoEndTimer) {
             clearTimeout(this.autoEndTimer);
@@ -524,7 +531,7 @@ class CodexSession {
     notifyHumanInputDrained() {
         // A just-accepted turn/start may not have `activeTurnId` yet; run.ts ignores
         // settle once turn.started clears atTurnBoundary. Do not block on activeTurnId.
-        if (this.humanPromptsPending > 0 || this.humanReadyOnTurnStart || !this.open || this.pendingUserInput || this.agentSubmissionPending)
+        if (this.humanPromptsPending > 0 || this.humanReadyOnTurnStart || !this.open || this.pendingUserInput || this.pendingApprovals.size || this.agentSubmissionPending)
             return;
         if (this.refusedForHuman)
             this.refusedForHuman = false;
@@ -533,7 +540,11 @@ class CodexSession {
     discardQueuedMessages() { }
     holdsHumanInput() { return this.humanPromptsPending > 0 || this.humanReadyOnTurnStart; }
     heldHumanInputCount() { return this.humanPromptsPending + (this.humanReadyOnTurnStart ? 1 : 0); }
-    end() {
+    end(explicit = true) {
+        if (explicit && !this.hasExited()) {
+            this.explicitEnd = true;
+            this.terminatedByCezar ||= this.automaticCleanupStarted;
+        }
         if (!this.stdinOpen)
             return;
         this.closeInput('session ended');
@@ -541,23 +552,23 @@ class CodexSession {
             endCodexAppServer(this.child, (term, kill) => {
                 this.eofTermTimer = term;
                 this.eofKillTimer = kill;
-            }, () => {
-                this.terminatedByCezar = true;
+            }, (state) => {
+                this.automaticCleanupStarted = true;
+                this.terminatedByCezar ||= this.explicitEnd || state === 'live';
             });
         }
-        catch {
-            // already gone
-        }
+        catch { /* already gone */ }
     }
     interrupt() {
         if (this.hardStopStarted || this.hasExited())
             return;
         this.hardStopStarted = true;
-        if (this.eofTermTimer)
-            clearTimeout(this.eofTermTimer);
-        if (this.eofKillTimer)
-            clearTimeout(this.eofKillTimer);
-        // Native cancellation is best effort; never wait for its ACK to stop.
+        if (!this.automaticCleanupStarted) {
+            if (this.eofTermTimer)
+                clearTimeout(this.eofTermTimer);
+            if (this.eofKillTimer)
+                clearTimeout(this.eofKillTimer);
+        }
         if (this.stdinOpen && this.threadId && this.activeTurnId) {
             void this.rpc.request('turn/interrupt', { threadId: this.threadId, turnId: this.activeTurnId }).catch(() => undefined);
         }
@@ -573,6 +584,8 @@ class CodexSession {
     closeInput(reason) {
         this.clearStreamRetry();
         this.stdinOpen = false;
+        // Respond while stdin is still writable, before rpc.close or EOF/TERM.
+        this.expireApprovals(reason);
         this.humanReadyOnTurnStart = false;
         for (const id of [...this.unreadHumanSteers.keys()]) {
             this.unreadHumanSteers.delete(id);
@@ -620,7 +633,7 @@ class CodexSession {
         if (this.refusedBeforeStartup)
             queueMicrotask(() => {
                 this.refusedBeforeStartup = false;
-                if (this.open && !this.pendingUserInput && !this.agentSubmissionPending)
+                if (this.open && !this.pendingUserInput && !this.pendingApprovals.size && !this.agentSubmissionPending)
                     this.opts.onAgentInputReady?.();
             });
     }
@@ -646,13 +659,17 @@ class CodexSession {
         const overrides = {
             model: this.spec.model,
             cwd: this.spec.cwd,
+            ...codexToolGrantFields(this.spec.toolGrant),
             ...codexPermissionOverrides(requirements, restrictNetwork),
             // ThreadStartParams AND ThreadResumeParams accept dotted config overrides.
             // Both feature generations exist in Codex 0.153.4; no global config write.
             ...((restrictNetwork || this.spec.restrictNativeDelegation || this.spec.cezarTools) ? { config: {
                     ...(restrictNetwork ? { 'sandbox_workspace_write.network_access': false } : {}),
                     ...(this.spec.restrictNativeDelegation ? { 'features.multi_agent': false, 'features.multi_agent_v2': false } : {}),
-                    ...(this.spec.cezarTools ? { [`mcp_servers.${this.spec.cezarTools.name}`]: { command: this.spec.cezarTools.command, args: this.spec.cezarTools.args, env_vars: cezarToolEnvNames(this.spec.env ?? {}) } } : {}),
+                    // hearsay-tools/cezarion#1294: Codex asks before every MCP tool call unless the
+                    // server's mode is `approve`, and cezar's own tools must never wait on that.
+                    // approval_policy stays the user's (#381); older Codex ignores the unknown key.
+                    ...(this.spec.cezarTools ? { [`mcp_servers.${this.spec.cezarTools.name}`]: { command: this.spec.cezarTools.command, args: this.spec.cezarTools.args, env_vars: cezarToolEnvNames(this.spec.env ?? {}), default_tools_approval_mode: 'approve' } } : {}),
                 } } : {}),
         };
         let threadResponse;
@@ -775,6 +792,15 @@ class CodexSession {
             this.activeTurnId = turnIdOf(res) ?? this.activeTurnId;
     }
     dispatch(msg) {
+        if (typeof msg.method === 'string' && (typeof msg.id === 'number' || typeof msg.id === 'string')) {
+            if (msg.method === 'item/tool/requestUserInput')
+                this.handleUserInputRequest(msg.id, msg.params ?? {});
+            else if (isCodexApprovalRequest(msg.method, msg.params))
+                this.handleApprovalRequest(msg.method, msg.id, msg.params);
+            else
+                this.rpc.respond({ id: msg.id, error: { code: -32601, message: `unsupported server request: ${msg.method}` } });
+            return;
+        }
         const humanClient = typeof msg.id === 'number' ? this.humanPromptByRpc.get(msg.id) : undefined;
         if (this.rpc.dispatchResponse(msg)) {
             // #486: settle human-prompt bookkeeping in RPC dispatch order, before the next line.
@@ -803,13 +829,67 @@ class CodexSession {
             }
             return;
         }
-        if (msg.method === 'item/tool/requestUserInput' && (typeof msg.id === 'number' || typeof msg.id === 'string')) {
-            this.handleUserInputRequest(msg.id, msg.params ?? {});
-            return;
-        }
         if (typeof msg.method === 'string')
             this.handleNotification(msg.method, msg.params ?? {});
     }
+    handleApprovalRequest(method, rpcId, params) {
+        const duplicate = [...this.pendingApprovals.entries()].find(([, pending]) => pending.rpcId === rpcId);
+        const approval = codexApproval(method, rpcId, params, this.spec.cezarTools?.name);
+        const routing = params;
+        if (!approval || !this.activeTurnId || routing?.threadId !== this.threadId || approval.turnId !== this.activeTurnId ||
+            duplicate) {
+            this.rpc.respond({ id: rpcId, error: { code: -32602, message: 'malformed, stale or unsupported approval routing' } });
+            // One native id cannot identify two requests. Its error settles the wire;
+            // revoke the old UI capability so it cannot produce a second response.
+            if (duplicate)
+                this.expireApproval(duplicate[0], 'duplicate native request id', false);
+            return;
+        }
+        this.clearStreamRetry();
+        this.agentInputReady = false;
+        if (this.autoEndTimer)
+            clearTimeout(this.autoEndTimer);
+        this.autoEndTimer = undefined;
+        this.pendingApprovals.set(approval.event.requestId, approval);
+        try {
+            if (!this.opts.onUiEvent)
+                throw new Error('approval UI unavailable');
+            this.opts.onUiEvent(approval.event);
+        }
+        catch {
+            // A missing/throwing consumer cannot leave a native RPC waiting forever.
+            this.expireApproval(approval.event.requestId, 'approval UI unavailable');
+        }
+    }
+    respondPermission(requestId, optionId) {
+        const approval = this.pendingApprovals.get(requestId);
+        const response = approval?.responses.get(optionId);
+        if (!this.open || !approval || !response || approval.turnId !== this.activeTurnId)
+            return false;
+        this.pendingApprovals.delete(requestId);
+        this.rpc.respond({ id: approval.rpcId, result: response });
+        this.emitPermissionResolved(requestId, this.open ? { optionId } : { reason: 'approval response transport failed' });
+        return this.open;
+    }
+    emitPermissionResolved(requestId, resolution) {
+        try {
+            this.opts.onUiEvent?.({ type: 'permission.resolved', requestId, ...resolution });
+        }
+        catch { /* A failed consumer must not strand other pending RPCs. */ }
+    }
+    expireApproval(requestId, reason, respond = true) {
+        const approval = this.pendingApprovals.get(requestId);
+        if (!approval)
+            return;
+        this.pendingApprovals.delete(requestId);
+        if (respond)
+            this.rpc.respond({ id: approval.rpcId, error: { code: -32000, message: reason } });
+        this.emitPermissionResolved(requestId, { reason });
+    }
+    expireApprovals(reason, respond = true) {
+        for (const requestId of this.pendingApprovals.keys())
+            this.expireApproval(requestId, reason, respond);
+    }
     handleUserInputRequest(rpcId, params) {
         const questions = codexAskQuestions(params.questions);
         if (!questions) {
@@ -821,7 +901,7 @@ class CodexSession {
         if (this.pendingUserInput)
             this.rejectPendingUserInput('superseded by a newer requestUserInput');
         this.pendingUserInput = { rpcId, questions };
-        this.opts.onUiEvent?.({ type: 'ask.requested', requestId: `codex-${String(rpcId)}`, questions });
+        this.opts.onUiEvent?.({ type: 'ask.requested', requestId: `codex-${String(rpcId)}`, questions: uiAskQuestions(questions) });
     }
     rejectPendingUserInput(message) {
         const pending = this.pendingUserInput;
@@ -889,6 +969,15 @@ class CodexSession {
             this.clearStreamRetry();
         }
         switch (method) {
+            case 'serverRequest/resolved': {
+                if (params.threadId !== this.threadId)
+                    break;
+                for (const [requestId, approval] of this.pendingApprovals) {
+                    if (approval.rpcId === params.requestId)
+                        this.expireApproval(requestId, 'resolved by Codex', false);
+                }
+                break;
+            }
             case 'error':
                 this.handleStreamError(params);
                 break;
@@ -905,8 +994,10 @@ class CodexSession {
                     this.firstTurnStarted = true;
                     this.checkStartupComplete();
                 }
-                if (turnIdOf(params) !== this.activeTurnId)
+                if (turnIdOf(params) !== this.activeTurnId) {
                     this.clearStreamRetry();
+                    this.expireApprovals('a new turn started');
+                }
                 this.activeTurnId = turnIdOf(params) ?? this.activeTurnId;
                 if (this.humanReadyOnTurnStart) {
                     this.humanReadyOnTurnStart = false;
@@ -978,8 +1069,11 @@ class CodexSession {
             case 'turn/failed': {
                 if (this.isForeignThreadTurn(params))
                     break; // don't end the parent turn on a child turn (#600)
+                if (this.activeTurnId && turnIdOf(params) && turnIdOf(params) !== this.activeTurnId)
+                    break;
                 if (this.isCurrentTurn(params))
                     this.clearStreamRetry();
+                this.expireApprovals('turn ended');
                 this.turnBoundaryVersion += 1;
                 this.pendingUserInput = undefined;
                 this.activeTurnId = undefined;
@@ -1109,6 +1203,7 @@ const PASSIVE_OUTPUT_METHODS = new Set([
     'item/started', 'item/updated', 'item/completed', 'item/agentMessage/delta',
     'item/reasoning/textDelta', 'item/reasoning/summaryDelta', 'item/reasoning/summaryTextDelta',
     'item/commandExecution/outputDelta', 'thread/tokenUsage/updated', 'turn/plan/updated',
+    'hook/started', 'hook/completed',
 ]);
 const REASONING_SUMMARIES = new Set(['auto', 'concise', 'detailed', 'none']);
 /**