@niwa-labs/harness-codex 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/control.ts ADDED
@@ -0,0 +1,1596 @@
1
+ /**
2
+ * The control side for Codex: how niwa starts, steers and stops sessions over
3
+ * `codex app-server` JSON-RPC.
4
+ *
5
+ * Each session owns one child in its own process group. The native session id is Codex's own
6
+ * thread id. A message to a busy session is queued by default and becomes a turn of its own
7
+ * when the current turn ends; only a caller that asks for it is steered into the running turn.
8
+ * Every receipt reports what happened: `queued` after the current turn, `delivered` when
9
+ * `turn/steer` was accepted, `started` when `turn/start` was accepted, and a turn that did not
10
+ * complete is an error, never a success.
11
+ */
12
+
13
+ import { existsSync } from "node:fs";
14
+
15
+ import { z } from "zod";
16
+
17
+ import { assertNever, stableJson, timestamp } from "@niwa-labs/core";
18
+ import type { Answer, Question } from "@niwa-labs/core";
19
+ import type {
20
+ AskAnswer,
21
+ AskOptions,
22
+ DeliveryReceipt,
23
+ LifeEvent,
24
+ McpServerSpec,
25
+ Prompt,
26
+ ResumeOptions,
27
+ SendOptions,
28
+ SessionControl,
29
+ SessionState,
30
+ StartOptions,
31
+ StartedSession,
32
+ VisibleActions,
33
+ LaunchCapabilities,
34
+ SessionMode,
35
+ HarnessId,
36
+ SessionId,
37
+ ReverseHandler,
38
+ ToolsMode,
39
+ TurnOutcome,
40
+ Dispatch,
41
+ } from "@niwa-labs/harness";
42
+ import {
43
+ InputNotSent,
44
+ InputPossiblySent,
45
+ inputFailure,
46
+ DEFAULT_TURN_TIMEOUT_MS,
47
+ describeToolsMode,
48
+ modelName,
49
+ unknownVariantSigns,
50
+ modeOf,
51
+ requireLaunch,
52
+ Unavailable,
53
+ Unsupported,
54
+ HarnessIdSchema,
55
+ sessionId as makeSessionId,
56
+ } from "@niwa-labs/harness";
57
+ import { LIVE_PROCESS_REFUSAL, sandboxOf, spawnAgent } from "@niwa-labs/sandbox";
58
+ import type { AgentProcess } from "@niwa-labs/sandbox";
59
+
60
+ import { incomingOf, incomingOfDrifted } from "./incoming.ts";
61
+ import type { EndedTurn, Incoming } from "./incoming.ts";
62
+ import { CODEX_PROTOCOL, readFrame } from "./protocol/index.ts";
63
+ import type { UnknownFrame } from "./protocol/index.ts";
64
+ import type { RequestId, ServerRequest } from "./protocol/generated/app-server.ts";
65
+ import { refusalOf } from "./refusals.ts";
66
+ import type { Reply } from "./refusals.ts";
67
+ import { approvalOf, elicitationOf, userAnswerOf, userQuestionsOf } from "./reverse.ts";
68
+ import type { ReversedRequest } from "./reverse.ts";
69
+
70
+ /** macOS ships a public CA bundle that a read-closed nono box can use without the Keychain. */
71
+ function boxedCertificate(plan: Pick<StartOptions, "env" | "box">): Record<string, string> {
72
+ if (process.platform !== "darwin" || !plan.box || sandboxOf(plan.box.sandbox).name !== "nono") return {};
73
+ const env = { ...plan.box.spec.env, ...plan.env };
74
+ if (env["CODEX_CA_CERTIFICATE"] !== undefined || env["SSL_CERT_FILE"] !== undefined) return {};
75
+ const certificate = "/etc/ssl/cert.pem";
76
+ return existsSync(certificate) ? { CODEX_CA_CERTIFICATE: certificate } : {};
77
+ }
78
+
79
+ /** What a Codex session takes at launch: a model, an effort that is sent with every turn, and a working mode. */
80
+ export const CODEX_LAUNCH: LaunchCapabilities = {
81
+ model: true,
82
+ effort: ["low", "medium", "high", "xhigh"],
83
+ modes: ["ask", "auto", "full"],
84
+ };
85
+
86
+ /**
87
+ * What a working mode is to Codex, at `thread/start` and `thread/resume`: `ask` may read and asks
88
+ * to do anything else, `auto` writes in the workspace (the working directory) and asks to leave
89
+ * it, `full` has the machine and asks nothing.
90
+ */
91
+ const THREAD_MODES = {
92
+ ask: { approvalPolicy: "on-request", sandbox: "read-only" },
93
+ auto: { approvalPolicy: "on-request", sandbox: "workspace-write" },
94
+ full: { approvalPolicy: "never", sandbox: "danger-full-access" },
95
+ } as const satisfies Record<SessionMode, { approvalPolicy: string; sandbox: string }>;
96
+
97
+ /** The network is open inside the workspace-write sandbox of `auto`; Codex closes it by default. */
98
+ const AUTO_NETWORK = { "sandbox_workspace_write.network_access": true } as const;
99
+
100
+ export interface CodexControlOptions {
101
+ /** The harness instance id: half of a session's identity. */
102
+ readonly harness: string;
103
+ /** The `codex` binary, resolved through PATH when it is a bare name. */
104
+ readonly binary?: string;
105
+ /**
106
+ * The home of the installation its sessions belong to: every process is started with it as
107
+ * `CODEX_HOME`. A kind sets it from the home it reads, so a session started here is one that is
108
+ * listed and read there, and its profile gives a box that home. Without it the process keeps the
109
+ * environment it inherits.
110
+ */
111
+ readonly home?: string;
112
+ /** The model sessions talk to, when the caller does not choose one per start. */
113
+ readonly model?: string;
114
+ /** The effort sessions think with, when the caller does not choose one per start. */
115
+ readonly effort?: string;
116
+ /** The working mode of sessions, when the caller does not choose one per start. Default: `auto`. */
117
+ readonly mode?: SessionMode;
118
+ /** How long one JSON-RPC call waits for its answer, in milliseconds. */
119
+ readonly callTimeoutMs?: number;
120
+ /** How long a turn waits for its end, in milliseconds. */
121
+ readonly turnTimeoutMs?: number;
122
+ /** How long a graceful stop waits before the hard kill, in milliseconds. */
123
+ readonly stopGraceMs?: number;
124
+ }
125
+
126
+ /** A `SessionControl` that also owns the processes it started. */
127
+ export interface CodexSessionControl extends SessionControl {
128
+ /** Stops a session and the process group it owns. */
129
+ stop(id: SessionId): Promise<void>;
130
+
131
+ /** Stops every session this control side owns, including ones still starting. */
132
+ dispose(): Promise<void>;
133
+ }
134
+
135
+ const DEFAULT_CALL_TIMEOUT_MS = 120_000;
136
+ const DEFAULT_STOP_GRACE_MS = 200;
137
+ const MAX_FRAME_BYTES = 16 * 1024 * 1024;
138
+ const STDERR_TAIL_CHARS = 2000;
139
+
140
+ /** The result of one JSON-RPC call. A refusal is an outcome, not a rejection. */
141
+ interface RpcOutcome {
142
+ readonly ok: boolean;
143
+ readonly result?: unknown;
144
+ readonly error?: string;
145
+ /** How far a call that failed got: never written, refused by Codex, or written and never answered. */
146
+ readonly dispatch?: Dispatch;
147
+ }
148
+
149
+ /** A watcher gets events, then `undefined` once when the child is gone. */
150
+ type Watcher = (event: LifeEvent | undefined) => void;
151
+
152
+ /** A turn's end: the turn Codex reported and the answer it gave. */
153
+ interface TurnEnd {
154
+ readonly turn: EndedTurn | undefined;
155
+ readonly text: string;
156
+ }
157
+
158
+ /** A turn's end: the turn Codex reported, or `undefined` when it timed out or the child died. */
159
+ interface TurnWait {
160
+ readonly done: Promise<TurnEnd | undefined>;
161
+ /** Names the turn this wait is for, by Codex's id of it, once that is known: another turn's end then leaves it waiting. */
162
+ bind(turnId: string | undefined): void;
163
+ cancel(): void;
164
+ }
165
+
166
+ /** A wait for the end of a turn, and the id of the turn it waits for once Codex named it. */
167
+ interface TurnWaiter {
168
+ turnId: string | undefined;
169
+ readonly settle: (end: TurnEnd | undefined) => void;
170
+ }
171
+
172
+ function asRecord(value: unknown): Record<string, unknown> {
173
+ return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
174
+ }
175
+
176
+ /** How a turn ended, in the words every harness shares: a turn Codex stopped or failed did not complete, and a status this build does not know proves nothing. */
177
+ function outcomeOfTurn(turn: EndedTurn): TurnOutcome {
178
+ switch (turn.status) {
179
+ case "completed":
180
+ return "completed";
181
+ case "failed":
182
+ case "interrupted":
183
+ return "failed";
184
+ default:
185
+ return "unknown";
186
+ }
187
+ }
188
+
189
+ function idOf(value: unknown): string | undefined {
190
+ const id = asRecord(value).id;
191
+ return typeof id === "string" && id !== "" ? id : undefined;
192
+ }
193
+
194
+ /** A turn that waits for the running one; an ask also waits for its answer. */
195
+ interface QueuedTurn {
196
+ readonly text: string;
197
+ readonly outputSchema?: Record<string, unknown>;
198
+ readonly ask?: { resolve: (answer: string) => void; reject: (error: unknown) => void };
199
+ }
200
+
201
+ /** How many turn signs are kept for the first watcher of a session. */
202
+ const UNWATCHED_LIMIT = 64;
203
+
204
+ /** How many file-change items are remembered, to tell what an approval of one is about. */
205
+ const FILE_CHANGES_KEPT = 64;
206
+
207
+ class LiveSession {
208
+ nativeId = "";
209
+ /** The turns niwa has started; the running one, if any, has this number. */
210
+ turn = 0;
211
+ /** The id Codex gave the running turn. */
212
+ activeTurnId: string | undefined;
213
+ busy = false;
214
+ stopping = false;
215
+ ended = false;
216
+ failure: string | undefined;
217
+ stderrTail = "";
218
+ /** The last final answer of the running turn, or of the last turn that ended. */
219
+ text = "";
220
+ /** The turns that wait for the turn after the running one, in the order they came. */
221
+ readonly queue: QueuedTurn[] = [];
222
+ /** The effort the session was started with: it goes with every turn, and never changes. */
223
+ effort: string | undefined;
224
+ /** The config the thread was started with; a held thread cannot take another one. */
225
+ config: Record<string, unknown> | undefined;
226
+ nextId = 1;
227
+ /** Where this session's reverse requests go, when it has been given a place for them. */
228
+ reverse: ReverseHandler | undefined;
229
+ /** The paths of the file changes Codex announced, by item id: what an approval of one is about. */
230
+ readonly fileChanges = new Map<string, readonly string[]>();
231
+ /** The reverse requests waiting for an answer, each with the request id of Codex: aborted when Codex stops waiting. */
232
+ private readonly asking = new Map<AbortController, number | string>();
233
+
234
+ readonly watchers = new Set<Watcher>();
235
+ /**
236
+ * The turn signs before anyone watched: a turn can run inside `start`, before the caller has
237
+ * the session to watch. The first watcher is given them; after it nothing is kept.
238
+ */
239
+ private unwatched: LifeEvent[] | undefined = [];
240
+ readonly pending = new Map<number, (outcome: RpcOutcome) => void>();
241
+ private readonly turnWaiters: TurnWaiter[] = [];
242
+
243
+ constructor(readonly child: AgentProcess) {}
244
+
245
+ /** Watch the signs of life; the first watcher also gets the turn signs that came before it. */
246
+ watch(watcher: Watcher): void {
247
+ const missed = this.unwatched ?? [];
248
+ this.unwatched = undefined;
249
+ for (const event of missed) watcher(event);
250
+ this.watchers.add(watcher);
251
+ }
252
+
253
+ rememberFileChange(itemId: string, paths: readonly string[]): void {
254
+ this.fileChanges.set(itemId, paths);
255
+ if (this.fileChanges.size > FILE_CHANGES_KEPT) {
256
+ const oldest = this.fileChanges.keys().next().value;
257
+ if (oldest !== undefined) this.fileChanges.delete(oldest);
258
+ }
259
+ }
260
+
261
+ /** A reverse request begins to wait: the signal is aborted when Codex stops waiting for it. */
262
+ startAsking(requestId: number | string): { readonly signal: AbortSignal; readonly done: () => void } {
263
+ const controller = new AbortController();
264
+ this.asking.set(controller, requestId);
265
+ return { signal: controller.signal, done: () => this.asking.delete(controller) };
266
+ }
267
+
268
+ /** Codex no longer waits for one request, or for any of them. */
269
+ cancelAsking(requestId?: number | string): void {
270
+ for (const [controller, asked] of [...this.asking]) {
271
+ if (requestId !== undefined && asked !== requestId) continue;
272
+ this.asking.delete(controller);
273
+ controller.abort();
274
+ }
275
+ }
276
+
277
+ /** Fail every queued ask, and drop the queue; returns how many turns were dropped. */
278
+ dropQueue(reason: string): number {
279
+ const dropped = this.queue.splice(0);
280
+ for (const turn of dropped) turn.ask?.reject(new Error(reason));
281
+ return dropped.length;
282
+ }
283
+
284
+ emit(event: LifeEvent): void {
285
+ if (this.unwatched !== undefined && event.kind !== "activity") {
286
+ this.unwatched.push(event);
287
+ if (this.unwatched.length > UNWATCHED_LIMIT) this.unwatched.shift();
288
+ }
289
+ for (const watcher of [...this.watchers]) {
290
+ try {
291
+ watcher(event);
292
+ } catch {
293
+ // A broken watcher must not break the session.
294
+ }
295
+ }
296
+ }
297
+
298
+ expectTurn(timeoutMs: number): TurnWait {
299
+ if (this.ended) return { done: Promise.resolve(undefined), bind: () => {}, cancel: () => {} };
300
+ let timer: ReturnType<typeof setTimeout> | undefined;
301
+ let waiter: TurnWaiter | undefined;
302
+ const drop = (): void => {
303
+ clearTimeout(timer);
304
+ const at = waiter === undefined ? -1 : this.turnWaiters.indexOf(waiter);
305
+ if (at !== -1) this.turnWaiters.splice(at, 1);
306
+ };
307
+ const done = new Promise<TurnEnd | undefined>((resolve) => {
308
+ waiter = {
309
+ turnId: undefined,
310
+ settle: (end) => {
311
+ clearTimeout(timer);
312
+ resolve(end);
313
+ },
314
+ };
315
+ this.turnWaiters.push(waiter);
316
+ timer = setTimeout(() => {
317
+ drop();
318
+ resolve(undefined);
319
+ }, timeoutMs);
320
+ });
321
+ return {
322
+ done,
323
+ bind: (turnId) => {
324
+ if (waiter !== undefined && waiter.turnId === undefined) waiter.turnId = turnId;
325
+ },
326
+ cancel: drop,
327
+ };
328
+ }
329
+
330
+ /** Codex named the turn that began: the oldest wait that has no turn yet is the wait for it. */
331
+ bindTurn(turnId: string): void {
332
+ const waiting = this.turnWaiters.find((waiter) => waiter.turnId === undefined);
333
+ if (waiting !== undefined) waiting.turnId = turnId;
334
+ }
335
+
336
+ /**
337
+ * A turn ended: the waits for it are settled. A wait for another turn, one Codex named already,
338
+ * keeps waiting; a wait that has no turn yet, and an end that names none, cannot be told apart.
339
+ * The child going away (`undefined`) ends every wait. With `named`, only the waits Codex named
340
+ * for exactly this turn end: the end of a turn that is not the running one touches no other.
341
+ */
342
+ settleTurn(turn: EndedTurn | undefined, named = false): void {
343
+ // The answer of the turn that ends is the text as it stands now; the next turn clears it.
344
+ const end: TurnEnd = { turn, text: this.text };
345
+ const waiting = this.turnWaiters.splice(0);
346
+ for (const waiter of waiting) {
347
+ const other = turn?.id !== undefined && waiter.turnId !== undefined && waiter.turnId !== turn.id;
348
+ const unnamed = named && waiter.turnId === undefined;
349
+ if (other || unnamed) this.turnWaiters.push(waiter);
350
+ else waiter.settle(end);
351
+ }
352
+ }
353
+
354
+ /** The child is gone: every call in flight and every waiter is released, every watcher told. */
355
+ end(failure?: string): void {
356
+ if (this.ended) return;
357
+ this.ended = true;
358
+ this.busy = false;
359
+ this.activeTurnId = undefined;
360
+ this.cancelAsking();
361
+ const lost = this.dropQueue(failure ?? "the session ended");
362
+ if (failure !== undefined) {
363
+ this.failure = failure;
364
+ this.emit({ kind: "activity", at: Date.now(), detail: failure });
365
+ }
366
+ if (lost > 0) {
367
+ this.emit({ kind: "activity", at: Date.now(), detail: `${lost} queued message(s) were never delivered: the session ended` });
368
+ }
369
+ const reason = this.failure ?? "the session process closed";
370
+ const pending = [...this.pending.values()];
371
+ this.pending.clear();
372
+ for (const settle of pending) settle({ ok: false, error: reason, dispatch: "uncertain" });
373
+ this.settleTurn(undefined);
374
+ for (const watcher of [...this.watchers]) watcher(undefined);
375
+ }
376
+ }
377
+
378
+ /** The control side for Codex. It owns every process it starts and terminates them itself. */
379
+ export function codexControl(options: CodexControlOptions): CodexSessionControl {
380
+ const binary = options.binary ?? "codex";
381
+ const callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
382
+ const turnTimeoutMs = options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
383
+ const stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS;
384
+ const defaultModel = options.model;
385
+ const defaultEffort = options.effort;
386
+ const harnessId = HarnessIdSchema.parse(options.harness);
387
+
388
+ /** The sessions by thread id; `owned` also holds those still starting. */
389
+ const sessions = new Map<string, LiveSession>();
390
+ const owned = new Set<LiveSession>();
391
+ /** The processes being created: one that is not yet a session is still the control side's to stop. */
392
+ const spawning = new Set<Promise<AgentProcess>>();
393
+ /** The launch of each thread that is being brought up: a thread has one writer, so a second launch waits for the first. */
394
+ const launching = new Map<string, Promise<void>>();
395
+ let disposed = false;
396
+
397
+ function unavailable(ability: string, detail: string): Unavailable {
398
+ return new Unavailable(harnessId, "control", ability, detail);
399
+ }
400
+
401
+ // -- the JSON-RPC client --------------------------------------------------
402
+
403
+ function writeLine(session: LiveSession, line: string): void {
404
+ const stdin = session.child.stdin;
405
+ if (stdin === null || stdin.destroyed || session.stopping || session.ended) {
406
+ throw unavailable("send", session.failure ?? "the session is not running");
407
+ }
408
+ stdin.write(`${line}\n`);
409
+ }
410
+
411
+ /** One call, matched to its answer by id. It never rejects. */
412
+ function call(
413
+ session: LiveSession,
414
+ method: string,
415
+ params: Record<string, unknown>,
416
+ ): Promise<RpcOutcome> {
417
+ const id = session.nextId;
418
+ session.nextId += 1;
419
+ return new Promise<RpcOutcome>((resolve) => {
420
+ const timer = setTimeout(() => {
421
+ if (session.pending.delete(id)) resolve({ ok: false, error: `the call ${method} timed out`, dispatch: "uncertain" });
422
+ }, callTimeoutMs);
423
+ session.pending.set(id, (outcome) => {
424
+ clearTimeout(timer);
425
+ resolve(outcome);
426
+ });
427
+ try {
428
+ writeLine(session, JSON.stringify({ jsonrpc: "2.0", id, method, params }));
429
+ } catch (error) {
430
+ clearTimeout(timer);
431
+ session.pending.delete(id);
432
+ resolve({ ok: false, error: error instanceof Error ? error.message : String(error), dispatch: "unsent" });
433
+ }
434
+ });
435
+ }
436
+
437
+ // -- the demux ------------------------------------------------------------
438
+
439
+ function handleLine(session: LiveSession, line: string): void {
440
+ if (line.length === 0) return;
441
+ const frame = readFrame(line);
442
+ const at = Date.now();
443
+ switch (frame.kind) {
444
+ case "response":
445
+ settleCall(session, frame.id, { ok: true, result: frame.result });
446
+ return;
447
+ case "failure":
448
+ settleCall(session, frame.id, { ok: false, error: frame.error.message, dispatch: "refused" });
449
+ return;
450
+ case "notification":
451
+ apply(session, incomingOf(frame.notification), at);
452
+ return;
453
+ case "request":
454
+ answerServerRequest(session, frame.id, frame.request);
455
+ return;
456
+ case "unknown":
457
+ handleUnknown(session, frame, at);
458
+ return;
459
+ case "unreadable":
460
+ session.emit({ kind: "activity", at, detail: frame.reason });
461
+ return;
462
+ default:
463
+ assertNever(frame, "codex frame");
464
+ }
465
+ }
466
+
467
+ /** The answer to a call of ours; one for a call nobody waits for any more is dropped. */
468
+ function settleCall(session: LiveSession, id: RequestId, outcome: RpcOutcome): void {
469
+ if (typeof id !== "number") return;
470
+ const settle = session.pending.get(id);
471
+ if (settle === undefined) return;
472
+ session.pending.delete(id);
473
+ settle(outcome);
474
+ }
475
+
476
+ /**
477
+ * A message that is not in the snapshot: Codex got newer. It is reported, and the session goes on:
478
+ * a request is still answered, and a turn that began or ended is still known to have.
479
+ */
480
+ function handleUnknown(session: LiveSession, frame: UnknownFrame, at: number): void {
481
+ for (const sign of unknownVariantSigns(at, CODEX_PROTOCOL, frame.variant, frame.raw, frame.method)) session.emit(sign);
482
+ if (frame.id !== undefined) {
483
+ writeReply(session, frame.id, refusalOf(frame.method));
484
+ return;
485
+ }
486
+ const drifted = incomingOfDrifted(frame.method, frame.params);
487
+ if (drifted !== undefined) apply(session, drifted, at);
488
+ }
489
+
490
+ /**
491
+ * Answer a request Codex makes of the client; unanswered, the turn waits forever. A session that
492
+ * has a place for its reverse requests sends approvals and questions there. Any other has nobody
493
+ * to ask, so nothing is escalated: the request is refused (`./refusals.ts`).
494
+ */
495
+ function answerServerRequest(session: LiveSession, id: RequestId, request: ServerRequest): void {
496
+ switch (request.method) {
497
+ case "item/commandExecution/requestApproval":
498
+ case "item/fileChange/requestApproval":
499
+ case "item/permissions/requestApproval":
500
+ if (session.reverse !== undefined) {
501
+ void askReverse(session, session.reverse, id, request);
502
+ return;
503
+ }
504
+ break;
505
+ case "item/tool/requestUserInput":
506
+ // An answer to a secret question would be kept in clear text with every other answer, and
507
+ // nothing yet asks for input that is hidden: such a request is refused, never asked.
508
+ if (session.reverse !== undefined && !request.params.questions.some((asked) => asked.isSecret)) {
509
+ void askReverse(session, session.reverse, id, request);
510
+ return;
511
+ }
512
+ break;
513
+ case "mcpServer/elicitation/request":
514
+ // A form niwa cannot ask a person (a link, a form of OpenAI's own kind) is refused like the rest.
515
+ if (session.reverse !== undefined && elicitationOf(request) !== undefined) {
516
+ void askReverse(session, session.reverse, id, request);
517
+ return;
518
+ }
519
+ break;
520
+ // Nobody is asked about these: they are refused. The words of each refusal, and why, are in `./refusals.ts`.
521
+ case "item/tool/call":
522
+ case "applyPatchApproval":
523
+ case "execCommandApproval":
524
+ case "account/chatgptAuthTokens/refresh":
525
+ case "attestation/generate":
526
+ break;
527
+ default:
528
+ assertNever(request, "codex server request");
529
+ }
530
+ writeReply(session, id, refusalOf(request.method));
531
+ }
532
+
533
+ /**
534
+ * A request of Codex that waits for a person, sent to where the session's reverse requests go.
535
+ * Codex is always answered, so a turn never hangs.
536
+ */
537
+ async function askReverse(
538
+ session: LiveSession,
539
+ handler: ReverseHandler,
540
+ id: RequestId,
541
+ request: ReversedRequest,
542
+ ): Promise<void> {
543
+ const raw = { method: request.method, params: request.params };
544
+ const ask = async (question: Question): Promise<Answer> => {
545
+ const asking = session.startAsking(id);
546
+ try {
547
+ return await handler(makeSessionId(harnessId, session.nativeId), { question, raw, signal: asking.signal });
548
+ } catch {
549
+ return { cancelled: true };
550
+ } finally {
551
+ asking.done();
552
+ }
553
+ };
554
+
555
+ let reply: Reply;
556
+ if (request.method === "item/tool/requestUserInput") {
557
+ // One question after the other; one left unanswered ends the call with no answers.
558
+ const asked = userQuestionsOf(request.params);
559
+ const answers: Record<string, { answers: string[] }> = {};
560
+ for (const { id: questionId, question } of asked) {
561
+ const given = userAnswerOf(question, await ask(question));
562
+ if (given === undefined) break;
563
+ answers[questionId] = { answers: given };
564
+ }
565
+ reply = { result: { answers: Object.keys(answers).length === asked.length ? answers : {} } };
566
+ } else if (request.method === "mcpServer/elicitation/request") {
567
+ const elicitation = elicitationOf(request);
568
+ reply = elicitation === undefined ? refusalOf(request.method) : { result: elicitation.reply(await ask(elicitation.question)) };
569
+ } else {
570
+ const approval = approvalOf(request, session.fileChanges.get(request.params.itemId));
571
+ reply = { result: approval.reply(await ask(approval.question)) };
572
+ }
573
+ writeReply(session, id, reply);
574
+ }
575
+
576
+ /** A frame that nobody waits to see written: a reply, or the `initialized` notice. */
577
+ function writeFrame(session: LiveSession, frame: Record<string, unknown>): void {
578
+ try {
579
+ writeLine(session, JSON.stringify({ jsonrpc: "2.0", ...frame }));
580
+ } catch {
581
+ // The child is going away; there is no one to answer.
582
+ }
583
+ }
584
+
585
+ function writeReply(session: LiveSession, id: RequestId, reply: Reply): void {
586
+ writeFrame(session, { id, ...reply });
587
+ }
588
+
589
+ /** What a notification means to the session, done. */
590
+ function apply(session: LiveSession, incoming: Incoming, at: number): void {
591
+ switch (incoming.kind) {
592
+ case "turn-started":
593
+ session.activeTurnId = incoming.turnId;
594
+ session.bindTurn(incoming.turnId);
595
+ session.busy = true;
596
+ session.emit({ kind: "turn-started", turn: session.turn, at });
597
+ return;
598
+ case "turn-ended":
599
+ // The end of a turn that is not the running one (a late end of an interrupted turn, say) is not the end of this one.
600
+ if (incoming.turn.id !== undefined && session.activeTurnId !== undefined && incoming.turn.id !== session.activeTurnId) {
601
+ session.settleTurn(incoming.turn, true);
602
+ session.emit({ kind: "activity", at, detail: `turn ${incoming.turn.id} ended (the running turn is ${session.activeTurnId})` });
603
+ return;
604
+ }
605
+ session.activeTurnId = undefined;
606
+ session.busy = false;
607
+ session.cancelAsking();
608
+ session.emit({ kind: "turn-ended", turn: session.turn, at, outcome: outcomeOfTurn(incoming.turn) });
609
+ session.settleTurn(incoming.turn);
610
+ // A message that waited for this turn becomes a turn of its own.
611
+ drainQueue(session);
612
+ return;
613
+ case "file-change":
614
+ session.rememberFileChange(incoming.itemId, incoming.paths);
615
+ break;
616
+ case "answer":
617
+ session.text = incoming.text;
618
+ break;
619
+ case "rerouted":
620
+ // Codex moved the turn to another model: that is the model the session runs from now on.
621
+ if (incoming.toModel !== "") session.emit({ kind: "model", model: modelName(incoming.toModel) });
622
+ break;
623
+ case "request-resolved":
624
+ // Codex answered the request itself (the turn was interrupted, a policy decided): nobody waits.
625
+ session.cancelAsking(incoming.requestId);
626
+ break;
627
+ case "sign":
628
+ break;
629
+ case "ignored":
630
+ return;
631
+ default:
632
+ assertNever(incoming, "codex incoming");
633
+ }
634
+ session.emit({ kind: "activity", at, detail: incoming.detail });
635
+ }
636
+
637
+ // -- the child ------------------------------------------------------------
638
+
639
+ /** Spawns a child and runs the handshake. A child that fails the handshake is stopped. */
640
+ async function spawnSession(
641
+ cwd: string | undefined,
642
+ plan: Pick<StartOptions, "env" | "tools" | "box">,
643
+ ability: "start" | "resume" = "start",
644
+ ): Promise<LiveSession> {
645
+ if (disposed) throw unavailable("start", "the control side is disposed");
646
+ // A tool mode Codex cannot hold is refused before the child exists.
647
+ requireCodexTools(harnessId, ability, plan.tools);
648
+ const creating = spawnAgent({
649
+ harness: harnessId,
650
+ program: binary,
651
+ args: ["app-server", "--stdio"],
652
+ cwd,
653
+ // Its own process group, so a stop reaches everything Codex started and nothing else.
654
+ detached: true,
655
+ env: {
656
+ ...boxedCertificate(plan),
657
+ ...plan.env,
658
+ ...(options.home === undefined ? {} : { CODEX_HOME: options.home }),
659
+ DISABLE_AUTOUPDATER: "1",
660
+ DISABLE_TELEMETRY: "1",
661
+ DISABLE_ERROR_REPORTING: "1",
662
+ DO_NOT_TRACK: "1",
663
+ },
664
+ box: plan.box,
665
+ });
666
+ spawning.add(creating);
667
+ let child: AgentProcess;
668
+ try {
669
+ child = await creating;
670
+ } finally {
671
+ spawning.delete(creating);
672
+ }
673
+ const session = new LiveSession(child);
674
+ owned.add(session);
675
+
676
+ let buffer = "";
677
+ child.stdout.setEncoding("utf8");
678
+ child.stdout.on("data", (chunk: string) => {
679
+ buffer += chunk;
680
+ for (let newline = buffer.indexOf("\n"); newline !== -1; newline = buffer.indexOf("\n")) {
681
+ const line = buffer.slice(0, newline).trim();
682
+ buffer = buffer.slice(newline + 1);
683
+ try {
684
+ handleLine(session, line);
685
+ } catch (error) {
686
+ session.emit({ kind: "activity", at: Date.now(), detail: `a frame failed: ${String(error)}` });
687
+ }
688
+ }
689
+ if (buffer.length > MAX_FRAME_BYTES) {
690
+ buffer = "";
691
+ session.end("a line of the output stream was longer than the frame budget");
692
+ void stopSession(session);
693
+ }
694
+ });
695
+
696
+ child.stderr.setEncoding("utf8");
697
+ child.stderr.on("data", (chunk: string) => {
698
+ session.stderrTail = (session.stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
699
+ });
700
+
701
+ // A write to a dead child is reported by the closing child, not thrown as an unhandled event.
702
+ child.stdin.on("error", () => {});
703
+
704
+ child.on("error", (error) => {
705
+ owned.delete(session);
706
+ session.end(`the session process failed: ${error.message}`);
707
+ });
708
+ child.on("close", (code, signal) => {
709
+ owned.delete(session);
710
+ // Whatever Codex started may outlive it; the group is the unit of cleanup.
711
+ if (child.pid !== undefined) signalGroup(session, child.pid, "SIGKILL");
712
+ session.end(
713
+ session.stopping
714
+ ? "the session was stopped"
715
+ : `the session process exited (${code ?? signal}): ${session.stderrTail.trim()}`,
716
+ );
717
+ });
718
+
719
+ // A control side disposed while the process was being created owns it all the same.
720
+ if (disposed) {
721
+ await stopSession(session);
722
+ throw unavailable(ability, "the control side is disposed");
723
+ }
724
+ const initialized = await call(session, "initialize", {
725
+ clientInfo: { name: "niwa", title: "niwa", version: "0.1.0" },
726
+ });
727
+ if (!initialized.ok) {
728
+ await stopSession(session);
729
+ throw unavailable("start", initialized.error ?? "the CLI did not answer the handshake");
730
+ }
731
+ writeFrame(session, { method: "initialized", params: {} });
732
+ return session;
733
+ }
734
+
735
+ // -- stopping -------------------------------------------------------------
736
+
737
+ function hasExited(session: LiveSession): boolean {
738
+ return session.child.exitCode !== null || session.child.signalCode !== null;
739
+ }
740
+
741
+ /** SIGTERM to the process group, then SIGKILL. Returns once the child is gone. */
742
+ async function stopSession(session: LiveSession): Promise<void> {
743
+ const pid = session.child.pid;
744
+ session.stopping = true;
745
+ if (pid === undefined) {
746
+ session.end();
747
+ return;
748
+ }
749
+ if (!hasExited(session)) {
750
+ session.child.stdin?.end();
751
+ signalGroup(session, pid, "SIGTERM");
752
+ if (!(await waitForExit(session, stopGraceMs))) {
753
+ signalGroup(session, pid, "SIGKILL");
754
+ await waitForExit(session, stopGraceMs);
755
+ }
756
+ }
757
+ // Codex's own children may outlive the leader.
758
+ signalGroup(session, pid, "SIGKILL");
759
+ session.end();
760
+ }
761
+
762
+ function signalGroup(session: LiveSession, pid: number, signal: NodeJS.Signals): void {
763
+ try {
764
+ process.kill(-pid, signal);
765
+ } catch {
766
+ try {
767
+ session.child.kill(signal);
768
+ } catch {
769
+ // Already gone.
770
+ }
771
+ }
772
+ }
773
+
774
+ function waitForExit(session: LiveSession, timeoutMs: number): Promise<boolean> {
775
+ if (hasExited(session)) return Promise.resolve(true);
776
+ return new Promise<boolean>((resolve) => {
777
+ const onClose = (): void => {
778
+ clearTimeout(timer);
779
+ resolve(true);
780
+ };
781
+ const timer = setTimeout(() => {
782
+ session.child.off("close", onClose);
783
+ resolve(false);
784
+ }, timeoutMs);
785
+ session.child.once("close", onClose);
786
+ });
787
+ }
788
+
789
+ // -- the turns ------------------------------------------------------------
790
+
791
+ function promptText(prompt: Prompt): string {
792
+ return prompt.sections.map((section) => section.text).join("\n\n");
793
+ }
794
+
795
+ /**
796
+ * Ask Codex to start a turn. The wait for the turn's end is registered before the request is
797
+ * written, so a turn that ends in the same read as its start response is not missed.
798
+ */
799
+ async function startTurn(
800
+ session: LiveSession,
801
+ threadId: string,
802
+ text: string,
803
+ outputSchema?: Record<string, unknown>,
804
+ ): Promise<{ turn: number; wait: TurnWait }> {
805
+ if (session.busy) throw new InputNotSent(harnessId, "send", "a turn is already running");
806
+ session.turn += 1;
807
+ session.busy = true;
808
+ session.text = "";
809
+ const turn = session.turn;
810
+ const wait = session.expectTurn(turnTimeoutMs);
811
+
812
+ const params: Record<string, unknown> = { threadId, input: [{ type: "text", text }] };
813
+ if (outputSchema !== undefined) params.outputSchema = outputSchema;
814
+ if (session.effort !== undefined) params.effort = session.effort;
815
+ const started = await call(session, "turn/start", params);
816
+ if (!started.ok) {
817
+ wait.cancel();
818
+ const dispatch = started.dispatch ?? "uncertain";
819
+ const failure = inputFailure(harnessId, "send", dispatch, started.error ?? "the CLI refused the turn");
820
+ if (dispatch !== "uncertain" || session.ended) {
821
+ // Codex did not take the turn: nothing runs, and what queued behind it goes on in its order.
822
+ session.busy = false;
823
+ drainQueue(session);
824
+ } else if (session.activeTurnId === undefined) {
825
+ // Codex neither answered nor announced the turn, so nobody knows whether one runs. Another
826
+ // turn on top of it would be a second writer, and what waits could wait forever: the
827
+ // session is closed, and a later resume starts from what Codex has on disk.
828
+ session.end(`${started.error ?? "the CLI did not answer the turn"}: the session was closed because the turn may be running`);
829
+ await stopSession(session);
830
+ }
831
+ // Otherwise Codex announced the turn before the answer was lost: it runs, it ends by its
832
+ // own notification, and the session stays busy until then.
833
+ throw failure;
834
+ }
835
+ // The end may already have been processed, and a newer turn may already have taken over:
836
+ // only a turn that is still the running one gets its id.
837
+ const nativeTurn = idOf(asRecord(started.result).turn);
838
+ wait.bind(nativeTurn);
839
+ if (session.busy && session.turn === turn) session.activeTurnId = nativeTurn;
840
+ return { turn, wait };
841
+ }
842
+
843
+ /** Wait for a started turn; anything but a completed turn is an error. Returns its answer. */
844
+ async function finishTurn(session: LiveSession, wait: TurnWait): Promise<string> {
845
+ const end = await wait.done;
846
+ if (end === undefined) {
847
+ throw unavailable("send", session.failure ?? "the turn did not end");
848
+ }
849
+ if (end.turn === undefined || end.turn.status !== "completed") {
850
+ const status = end.turn?.status ?? "did not complete";
851
+ throw unavailable("send", `the turn ${status}: ${end.turn?.message ?? "no reason given"}`);
852
+ }
853
+ return end.text;
854
+ }
855
+
856
+ async function runTurn(
857
+ session: LiveSession,
858
+ threadId: string,
859
+ text: string,
860
+ outputSchema?: Record<string, unknown>,
861
+ ): Promise<string> {
862
+ const { wait } = await startTurn(session, threadId, text, outputSchema);
863
+ return finishTurn(session, wait);
864
+ }
865
+
866
+ /**
867
+ * Starts the turns that waited for the turn that just ended, in the order the messages came.
868
+ *
869
+ * The turn is started after the end of the previous one was reported, so the signs of life
870
+ * show one turn after the other and never two at the same time.
871
+ */
872
+ function drainQueue(session: LiveSession): void {
873
+ if (session.ended || session.stopping) return;
874
+ const next = session.queue.shift();
875
+ if (next === undefined) return;
876
+ // The caller of a message does not wait for its turn; its end is a sign of life. The
877
+ // caller of an ask waits for the answer.
878
+ void startTurn(session, session.nativeId, next.text, next.outputSchema)
879
+ .then(({ wait }) => {
880
+ if (next.ask === undefined) {
881
+ wait.cancel();
882
+ return undefined;
883
+ }
884
+ return finishTurn(session, wait).then(next.ask.resolve, next.ask.reject);
885
+ })
886
+ .catch((error: unknown) => {
887
+ next.ask?.reject(error);
888
+ session.emit({
889
+ kind: "activity",
890
+ at: Date.now(),
891
+ detail: `a queued message could not be started: ${String(error)}`,
892
+ });
893
+ });
894
+ }
895
+
896
+ /**
897
+ * Deliver a message the way a send does, and say what became of it: queued behind a running
898
+ * turn, or the start of a turn. Nothing waits for the turn to end; the signs of life report it.
899
+ */
900
+ async function deliver(session: LiveSession, message: string): Promise<DeliveryReceipt> {
901
+ const at = Date.now();
902
+ if (session.busy) {
903
+ // The default: the message waits for the turn after the running one.
904
+ session.queue.push({ text: message });
905
+ return { status: "queued", turn: session.turn + session.queue.length, at };
906
+ }
907
+ const { turn, wait } = await startTurn(session, session.nativeId, message);
908
+ wait.cancel();
909
+ return { status: "started", turn, at };
910
+ }
911
+
912
+ /** Runs `launch` once the earlier launches of the same thread are over, whether they worked or not. */
913
+ async function launchAlone<T>(native: string, launch: () => Promise<T>): Promise<T> {
914
+ const earlier = launching.get(native);
915
+ const run = (async (): Promise<T> => {
916
+ await earlier;
917
+ return launch();
918
+ })();
919
+ const over = run.then(
920
+ () => undefined,
921
+ () => undefined,
922
+ );
923
+ launching.set(native, over);
924
+ try {
925
+ return await run;
926
+ } finally {
927
+ if (launching.get(native) === over) launching.delete(native);
928
+ }
929
+ }
930
+
931
+ function requireSession(id: SessionId, ability: string): LiveSession {
932
+ const session = sessions.get(id.native);
933
+ if (session === undefined) {
934
+ throw unavailable(ability, `the session ${id.native} is not held by this control side`);
935
+ }
936
+ return session;
937
+ }
938
+
939
+ function threadParams(
940
+ model: string | undefined,
941
+ config: Record<string, unknown> | undefined,
942
+ mode: SessionMode,
943
+ ): Record<string, unknown> {
944
+ const params: Record<string, unknown> = { ...THREAD_MODES[mode] };
945
+ if (model !== undefined && model !== "") params.model = model;
946
+ // Nothing to set means no config at all.
947
+ const given = mode === "auto" ? { ...config, ...AUTO_NETWORK } : config;
948
+ if (given !== undefined) params.config = given;
949
+ return params;
950
+ }
951
+
952
+ /** The model Codex names in its answer to `thread/start` or `thread/resume`, as a sign of life. */
953
+ function reportModel(session: LiveSession, answer: unknown): void {
954
+ const reported = asRecord(answer).model;
955
+ if (typeof reported === "string" && reported !== "") session.emit({ kind: "model", model: modelName(reported) });
956
+ }
957
+
958
+ // -- the contract ---------------------------------------------------------
959
+
960
+ return {
961
+ async start(startOptions: StartOptions): Promise<StartedSession> {
962
+ // The config is built before the child is spawned: a tool Codex cannot switch off is
963
+ // refused before anything is attempted.
964
+ const model = startOptions.model ?? defaultModel;
965
+ const effort = startOptions.effort ?? defaultEffort;
966
+ const mode = modeOf(startOptions.mode, options.mode, CODEX_LAUNCH);
967
+ requireLaunch(harnessId, CODEX_LAUNCH, { model, effort, mode });
968
+ const config = codexConfig(
969
+ harnessId,
970
+ "start",
971
+ startOptions.servers,
972
+ startOptions.visible,
973
+ );
974
+ const session = await spawnSession(startOptions.cwd, startOptions);
975
+ session.reverse = startOptions.reverse;
976
+ try {
977
+ const started = await call(session, "thread/start", {
978
+ ...threadParams(model, config, mode),
979
+ cwd: startOptions.cwd ?? process.cwd(),
980
+ });
981
+ if (!started.ok) throw unavailable("start", started.error ?? "the CLI did not start a thread");
982
+ const threadId = idOf(asRecord(started.result).thread);
983
+ if (threadId === undefined) throw unavailable("start", "the CLI started a thread without naming it");
984
+
985
+ if (disposed || session.ended) throw unavailable("start", session.failure ?? "the session did not outlive its start");
986
+ reportModel(session, started.result);
987
+ session.nativeId = threadId;
988
+ session.config = config;
989
+ session.effort = effort === "" ? undefined : effort;
990
+ sessions.set(threadId, session);
991
+ } catch (error) {
992
+ sessions.delete(session.nativeId);
993
+ await stopSession(session);
994
+ throw error;
995
+ }
996
+ const id = makeSessionId(harnessId, session.nativeId);
997
+ // The thread exists once Codex has named it, and the caller knows it before the prompt goes:
998
+ // a start cut off while its first turn is on the way still finds its thread.
999
+ try {
1000
+ await startOptions.named?.(id);
1001
+ } catch (error) {
1002
+ // A thread whose name could not be kept is one nobody could find again: it is given no work.
1003
+ sessions.delete(session.nativeId);
1004
+ await stopSession(session);
1005
+ throw error;
1006
+ }
1007
+ // The prompt is its first turn, delivered like a send: the start waits for Codex to accept
1008
+ // the turn, never for the turn to end.
1009
+ const text = promptText(startOptions.prompt);
1010
+ if (text === "") return { session: id, mode };
1011
+ try {
1012
+ return { session: id, first: await deliver(session, text), mode };
1013
+ } catch (error) {
1014
+ // The first message may have been taken: the thread is named and its turn may run, so the
1015
+ // start answers with the session and no receipt. The caller keeps the id; a start that
1016
+ // threw would be tried again, and that would make a second thread and say the prompt twice.
1017
+ if (error instanceof InputPossiblySent) return { session: id, mode };
1018
+ // The first message was refused: the thread was never given its work, and a session
1019
+ // nobody holds the id of could not be stopped later.
1020
+ sessions.delete(session.nativeId);
1021
+ await stopSession(session);
1022
+ throw error;
1023
+ }
1024
+ },
1025
+
1026
+ async resume(id: SessionId, resumeOptions?: ResumeOptions): Promise<void> {
1027
+ const text = resumeOptions?.prompt === undefined ? "" : promptText(resumeOptions.prompt);
1028
+ const config = codexConfig(
1029
+ harnessId,
1030
+ "resume",
1031
+ resumeOptions?.servers,
1032
+ resumeOptions?.visible,
1033
+ );
1034
+
1035
+ // A held session continues in its own child: a second child would be a second writer. The
1036
+ // launches of one thread follow one another, so the second sees what the first made.
1037
+ const session = await launchAlone(id.native, async (): Promise<LiveSession> => {
1038
+ const held = sessions.get(id.native);
1039
+ if (held !== undefined && !held.ended && !held.stopping) {
1040
+ if (resumeOptions?.tools !== undefined || resumeOptions?.box !== undefined) {
1041
+ throw new Unsupported(harnessId, "control", "resume", LIVE_PROCESS_REFUSAL);
1042
+ }
1043
+ // The thread was given its config when it started, and it cannot take another one.
1044
+ // The same config is no change at all; a different one is refused, never dropped.
1045
+ if (config !== undefined && !sameConfig(config, held.config)) {
1046
+ throw new Unsupported(
1047
+ harnessId,
1048
+ "control",
1049
+ "resume",
1050
+ "a running session cannot take another server or tool set",
1051
+ );
1052
+ }
1053
+ // The one who resumes names where its reverse requests go from now on.
1054
+ if (resumeOptions?.reverse !== undefined) held.reverse = resumeOptions.reverse;
1055
+ return held;
1056
+ }
1057
+
1058
+ const spawned = await spawnSession(undefined, resumeOptions ?? {}, "resume");
1059
+ spawned.reverse = resumeOptions?.reverse;
1060
+ try {
1061
+ const resumed = await call(spawned, "thread/resume", {
1062
+ ...threadParams(resumeOptions?.model ?? defaultModel, config, modeOf(resumeOptions?.mode, options.mode, CODEX_LAUNCH)),
1063
+ threadId: id.native,
1064
+ });
1065
+ if (!resumed.ok) throw unavailable("resume", resumed.error ?? "the CLI did not resume the thread");
1066
+ if (idOf(asRecord(resumed.result).thread) !== id.native) {
1067
+ throw unavailable("resume", "the CLI did not resume the thread that was asked for");
1068
+ }
1069
+ if (disposed || spawned.ended) throw unavailable("resume", spawned.failure ?? "the session did not outlive its resume");
1070
+ reportModel(spawned, resumed.result);
1071
+ } catch (error) {
1072
+ await stopSession(spawned);
1073
+ throw error;
1074
+ }
1075
+
1076
+ spawned.nativeId = id.native;
1077
+ spawned.config = config;
1078
+ spawned.effort = defaultEffort === "" ? undefined : defaultEffort;
1079
+ sessions.set(id.native, spawned);
1080
+ return spawned;
1081
+ });
1082
+ // The turn of the prompt is not part of the launch: it runs after the next resume may start.
1083
+ if (text !== "") await runTurn(session, id.native, text);
1084
+ },
1085
+
1086
+ async send(id: SessionId, message: string, sendOptions?: SendOptions): Promise<DeliveryReceipt> {
1087
+ const session = sessions.get(id.native);
1088
+ if (session === undefined) {
1089
+ throw new InputNotSent(harnessId, "send", `the session ${id.native} is not held by this control side`);
1090
+ }
1091
+ const at = Date.now();
1092
+ const input = [{ type: "text", text: message }];
1093
+
1094
+ if (session.busy) {
1095
+ // Only a caller that asks for it gets its message into the running turn.
1096
+ if (sendOptions?.into === "turn") {
1097
+ if (session.activeTurnId === undefined) {
1098
+ throw new InputNotSent(harnessId, "send", "the running turn has not been named by Codex yet");
1099
+ }
1100
+ const steered = await call(session, "turn/steer", {
1101
+ threadId: id.native,
1102
+ expectedTurnId: session.activeTurnId,
1103
+ input,
1104
+ });
1105
+ if (!steered.ok) throw inputFailure(harnessId, "send", steered.dispatch ?? "uncertain", steered.error ?? "the CLI refused the message");
1106
+ return { status: "delivered", turn: session.turn, at };
1107
+ }
1108
+ }
1109
+ return deliver(session, message);
1110
+ },
1111
+
1112
+ async interrupt(id: SessionId): Promise<void> {
1113
+ const session = requireSession(id, "interrupt");
1114
+ if (session.activeTurnId === undefined) throw unavailable("interrupt", "no turn is running");
1115
+ // An explicit stop clears the queue: the messages that waited behind a turn the caller
1116
+ // just stopped must not fire as a surprise.
1117
+ session.dropQueue("the turn was interrupted");
1118
+ const interrupted = await call(session, "turn/interrupt", {
1119
+ threadId: id.native,
1120
+ turnId: session.activeTurnId,
1121
+ });
1122
+ if (!interrupted.ok) {
1123
+ throw unavailable("interrupt", interrupted.error ?? "the CLI refused the interrupt");
1124
+ }
1125
+ // Codex stops waiting for whatever the turn asked.
1126
+ session.cancelAsking();
1127
+ },
1128
+
1129
+ async close(id: SessionId): Promise<void> {
1130
+ const session = sessions.get(id.native);
1131
+ if (session === undefined) return;
1132
+ sessions.delete(id.native);
1133
+ session.dropQueue("the session was closed");
1134
+ await stopSession(session);
1135
+ },
1136
+
1137
+ async ask<T>(id: SessionId, askOptions: AskOptions<T>): Promise<AskAnswer<T>> {
1138
+ const session = requireSession(id, "ask");
1139
+ const text = promptText(askOptions.prompt);
1140
+ const plan = codexAsk(askOptions.schema, text);
1141
+ const outputSchema = plan.outputSchema;
1142
+ // An ask into a busy session waits for its turn, behind what is already queued.
1143
+ const answer = session.busy
1144
+ ? await new Promise<string>((resolve, reject) => {
1145
+ session.queue.push({ text: plan.text, outputSchema, ask: { resolve, reject } });
1146
+ })
1147
+ : await runTurn(session, id.native, plan.text, outputSchema);
1148
+ // An answer written in the text may hold more than one piece of JSON (braces in the words
1149
+ // around it): the first that the caller's schema takes is the answer.
1150
+ let failure: unknown;
1151
+ for (const reading of jsonReadings(answer)) {
1152
+ try {
1153
+ const value = parseAnswer(askOptions.schema, plan.wrapped ? valueOf(reading) : reading);
1154
+ return { session: id, value, at: timestamp(Date.now()) };
1155
+ } catch (error) {
1156
+ failure ??= error;
1157
+ }
1158
+ }
1159
+ throw failure;
1160
+ },
1161
+
1162
+ life(id: SessionId): AsyncIterable<LifeEvent> {
1163
+ const session = requireSession(id, "life");
1164
+ return {
1165
+ async *[Symbol.asyncIterator](): AsyncGenerator<LifeEvent> {
1166
+ const queue: LifeEvent[] = [];
1167
+ let finished = session.ended;
1168
+ let wake: (() => void) | undefined;
1169
+ const watcher: Watcher = (event) => {
1170
+ if (event === undefined) finished = true;
1171
+ else queue.push(event);
1172
+ wake?.();
1173
+ };
1174
+ session.watch(watcher);
1175
+ try {
1176
+ for (;;) {
1177
+ const event = queue.shift();
1178
+ if (event !== undefined) {
1179
+ yield event;
1180
+ } else if (finished) {
1181
+ return;
1182
+ } else {
1183
+ await new Promise<void>((resolve) => {
1184
+ wake = resolve;
1185
+ });
1186
+ wake = undefined;
1187
+ }
1188
+ }
1189
+ } finally {
1190
+ session.watchers.delete(watcher);
1191
+ }
1192
+ },
1193
+ };
1194
+ },
1195
+
1196
+ async state(id: SessionId): Promise<SessionState> {
1197
+ const session = sessions.get(id.native);
1198
+ // A session not held, or whose child is gone, proves nothing about now.
1199
+ if (session === undefined || session.ended || session.stopping) return "unknown";
1200
+ return session.busy ? "running" : "idle";
1201
+ },
1202
+
1203
+ async stop(id: SessionId): Promise<void> {
1204
+ const session = sessions.get(id.native);
1205
+ if (session === undefined) return;
1206
+ sessions.delete(id.native);
1207
+ await stopSession(session);
1208
+ },
1209
+
1210
+ async dispose(): Promise<void> {
1211
+ disposed = true;
1212
+ sessions.clear();
1213
+ // A process still being created becomes a session of this side before the stop reaches it.
1214
+ await Promise.allSettled([...spawning]);
1215
+ await Promise.all([...owned].map((session) => stopSession(session)));
1216
+ sessions.clear();
1217
+ },
1218
+ };
1219
+ }
1220
+
1221
+ /**
1222
+ * app-server can disable individual features, but a feature can register several
1223
+ * tools and installed MCP servers contribute their own. Its thread API supplies
1224
+ * no exact filter over the effective catalog.
1225
+ */
1226
+ function requireCodexTools(harness: HarnessId, ability: "start" | "resume", tools: ToolsMode | undefined): void {
1227
+ if (tools === undefined || tools === "all") return;
1228
+ throw new Unsupported(harness, "control", ability,
1229
+ `${describeToolsMode(tools)}: Codex app-server cannot enforce an exact tool list`);
1230
+ }
1231
+
1232
+ /** Whether two Codex configs say the same thing; the same config is no change at all. */
1233
+ function sameConfig(
1234
+ a: Record<string, unknown> | undefined,
1235
+ b: Record<string, unknown> | undefined,
1236
+ ): boolean {
1237
+ if (a === undefined || b === undefined) return a === b;
1238
+ return stableJson(a) === stableJson(b);
1239
+ }
1240
+
1241
+ /**
1242
+ * The Codex config of a thread, in the dialect Codex speaks.
1243
+ *
1244
+ * Codex merges the JSON overrides as if they were given with `-c`. Server names are keys
1245
+ * of a table: a name that contains a dot must stay a single key.
1246
+ */
1247
+ function codexConfig(
1248
+ harness: HarnessId,
1249
+ ability: "start" | "resume",
1250
+ servers: readonly McpServerSpec[] | undefined,
1251
+ visible: VisibleActions | undefined,
1252
+ ): Record<string, unknown> | undefined {
1253
+ const config: Record<string, unknown> = {};
1254
+
1255
+ if (servers !== undefined && servers.length > 0) {
1256
+ config.mcp_servers = Object.fromEntries(servers.map((server) => [server.name, {
1257
+ command: server.command,
1258
+ args: [...server.args],
1259
+ ...(Object.keys(server.env).length === 0 ? {} : { env: { ...server.env } }),
1260
+ ...(server.tools === undefined ? {} : { enabled_tools: [...new Set(server.tools)].sort() }),
1261
+ }]));
1262
+ }
1263
+
1264
+ for (const tool of visible?.disabledTools ?? []) {
1265
+ switch (tool) {
1266
+ case "shell":
1267
+ config["features.shell_tool"] = false;
1268
+ break;
1269
+ case "web_search":
1270
+ config["web_search"] = "disabled";
1271
+ break;
1272
+ default:
1273
+ // Codex has no switch for any other tool, so the request is refused by name.
1274
+ throw new Unsupported(
1275
+ harness,
1276
+ "control",
1277
+ ability,
1278
+ `codex cannot switch off the tool "${tool}"`,
1279
+ );
1280
+ }
1281
+ }
1282
+
1283
+ return Object.keys(config).length === 0 ? undefined : config;
1284
+ }
1285
+
1286
+ /** How a question goes to Codex: the turn's text, the schema it is decoded under, and its shape. */
1287
+ interface CodexAsk {
1288
+ readonly text: string;
1289
+ /** The schema the turn is decoded under; none when strict mode cannot say the caller's schema. */
1290
+ readonly outputSchema?: Record<string, unknown>;
1291
+ /** Whether the answer comes wrapped as `{ value }`, for a schema whose root is not an object. */
1292
+ readonly wrapped: boolean;
1293
+ }
1294
+
1295
+ /**
1296
+ * The way a question goes to Codex (OpenAI structured output in strict mode).
1297
+ *
1298
+ * Strict mode takes a narrower JSON Schema than zod writes, so the schema sent is a projection of
1299
+ * the caller's, and the caller's own schema checks the answer whatever was sent:
1300
+ * - a root that is not an object is wrapped as `{ value }`, and the answer unwrapped;
1301
+ * - a `format` strict mode does not know and `propertyNames` are left out;
1302
+ * - objects are closed and optional properties made required and nullable (`closedObjects`);
1303
+ * - what strict mode cannot say at all (a free map, a tuple) is not decoded under a schema: the
1304
+ * schema is put in the text of the question, and the answer is read as the JSON it writes.
1305
+ */
1306
+ function codexAsk(schema: z.ZodType, text: string): CodexAsk {
1307
+ const caller = callerJsonSchema(schema);
1308
+ const wrapped = caller["type"] !== "object";
1309
+ const root = wrapped ? wrapRoot(caller) : caller;
1310
+ const fit = root === undefined ? undefined : strictFit(root);
1311
+ // What strict mode can say is judged before the objects are closed: closing a free map would
1312
+ // turn it into an object that may hold nothing.
1313
+ if (fit !== undefined && strictCanSay(fit)) {
1314
+ return { text, outputSchema: closedObjects(fit) as Record<string, unknown>, wrapped };
1315
+ }
1316
+ return {
1317
+ text: `${text}\n\nAnswer with JSON only, with no other text, that passes this JSON Schema:\n${JSON.stringify(caller)}`,
1318
+ wrapped: false,
1319
+ };
1320
+ }
1321
+
1322
+ /** A root that is not an object, as the property `value` of one; none when its refs would break. */
1323
+ function wrapRoot(caller: Record<string, unknown>): Record<string, unknown> | undefined {
1324
+ const { $defs, ...rest } = caller;
1325
+ // Only a ref into `$defs` stays valid once the root is the wrapper; a ref to the root ("#") or to
1326
+ // a place inside it ("#/items") would point somewhere else: such a schema is not wrapped.
1327
+ if (hasRefOutsideDefs(caller)) return undefined;
1328
+ return {
1329
+ type: "object",
1330
+ properties: { value: rest },
1331
+ required: ["value"],
1332
+ additionalProperties: false,
1333
+ ...($defs === undefined ? {} : { $defs }),
1334
+ };
1335
+ }
1336
+
1337
+ function hasRefOutsideDefs(node: unknown): boolean {
1338
+ if (Array.isArray(node)) return node.some(hasRefOutsideDefs);
1339
+ if (typeof node !== "object" || node === null) return false;
1340
+ return Object.entries(node).some(([key, value]) =>
1341
+ key === "$ref" && typeof value === "string"
1342
+ ? value.startsWith("#") && !value.startsWith("#/$defs/")
1343
+ : hasRefOutsideDefs(value),
1344
+ );
1345
+ }
1346
+
1347
+ /** The value inside a wrapped answer. */
1348
+ function valueOf(answer: unknown): unknown {
1349
+ return typeof answer === "object" && answer !== null && "value" in answer
1350
+ ? (answer as { value: unknown }).value
1351
+ : answer;
1352
+ }
1353
+
1354
+ /** The formats strict mode takes. */
1355
+ const STRICT_FORMATS: ReadonlySet<string> = new Set([
1356
+ "date-time",
1357
+ "time",
1358
+ "date",
1359
+ "duration",
1360
+ "email",
1361
+ "hostname",
1362
+ "ipv4",
1363
+ "ipv6",
1364
+ "uuid",
1365
+ ]);
1366
+
1367
+ /** The schema without what strict mode refuses and the caller's schema checks anyway. */
1368
+ function strictFit(node: unknown, names = false): unknown {
1369
+ if (Array.isArray(node)) return node.map((item) => strictFit(item));
1370
+ if (typeof node !== "object" || node === null) return node;
1371
+ const out: Record<string, unknown> = {};
1372
+ for (const [key, value] of Object.entries(node)) {
1373
+ if (!names && key === "propertyNames") continue;
1374
+ // Strict mode takes `anyOf` but not `oneOf` (a discriminated union); the caller's schema keeps the exclusivity.
1375
+ if (!names && key === "oneOf") {
1376
+ out["anyOf"] = strictFit(value);
1377
+ continue;
1378
+ }
1379
+ if (!names && key === "format" && typeof value === "string" && !STRICT_FORMATS.has(value)) continue;
1380
+ out[key] = !names && DATA_KEYWORDS.has(key) ? value : strictFit(value, !names && SCHEMA_MAPS.has(key));
1381
+ }
1382
+ return out;
1383
+ }
1384
+
1385
+ /** Whether strict mode can say the schema: no free map, no tuple. */
1386
+ function strictCanSay(node: unknown, names = false): boolean {
1387
+ if (Array.isArray(node)) return node.every((item) => strictCanSay(item));
1388
+ if (typeof node !== "object" || node === null) return true;
1389
+ const record = node as Record<string, unknown>;
1390
+ if (!names) {
1391
+ if (record["patternProperties"] !== undefined) return false;
1392
+ const extra = record["additionalProperties"];
1393
+ const properties = record["properties"];
1394
+ const named = typeof properties === "object" && properties !== null;
1395
+ // A typed map is not sayable; neither is a loose one that has no `properties` at all (a record
1396
+ // of anything), which closing would leave able to hold nothing. A loose object that lists its
1397
+ // properties is closed to them.
1398
+ if (typeof extra === "object" && extra !== null && (!named || Object.keys(extra).length > 0)) return false;
1399
+ if (extra === true && !named) return false;
1400
+ if (record["items"] === false || record["prefixItems"] !== undefined) return false;
1401
+ }
1402
+ return Object.entries(record).every(
1403
+ ([key, value]) => (!names && DATA_KEYWORDS.has(key)) || strictCanSay(value, !names && SCHEMA_MAPS.has(key)),
1404
+ );
1405
+ }
1406
+
1407
+ /** The caller's schema as JSON Schema, as zod writes it. */
1408
+ function callerJsonSchema(schema: z.ZodType): Record<string, unknown> {
1409
+ const { $schema: _dialect, ...rest } = z.toJSONSchema(schema, { io: "output" });
1410
+ return rest;
1411
+ }
1412
+
1413
+ /**
1414
+ * The schema with every object closed to keys it does not name.
1415
+ *
1416
+ * OpenAI's structured output refuses an `additionalProperties` that is not a typed schema or
1417
+ * `false` (a loose object, which a schema given as JSON becomes, says `{}`), and the whole turn
1418
+ * fails with a 400. Closing the object only narrows what the model may write: the answer is still
1419
+ * checked against the schema the caller gave, which takes it.
1420
+ */
1421
+ function closedObjects(node: unknown, names = false): unknown {
1422
+ if (Array.isArray(node)) return node.map((item) => closedObjects(item));
1423
+ if (typeof node !== "object" || node === null) return node;
1424
+ const out: Record<string, unknown> = {};
1425
+ // The keys of `properties` (and of the other maps of schemas) are names, not keywords: a
1426
+ // property may be called "additionalProperties". The values of `enum`, `const`, `default` and
1427
+ // `examples` are data, not schemas, and stay as they are.
1428
+ for (const [key, value] of Object.entries(node)) {
1429
+ out[key] = !names && DATA_KEYWORDS.has(key) ? value : closedObjects(value, !names && SCHEMA_MAPS.has(key));
1430
+ }
1431
+ if (names) return out;
1432
+ const extra = out["additionalProperties"];
1433
+ if (extra === true || (typeof extra === "object" && extra !== null && Object.keys(extra).length === 0)) {
1434
+ out["additionalProperties"] = false;
1435
+ }
1436
+ // OpenAI's strict mode wants every property listed as required. An optional property becomes a
1437
+ // required one that may be null, and the null is taken out of the answer again (see
1438
+ // `withoutOptionalNulls`) before the caller's schema checks it.
1439
+ const properties = out["properties"];
1440
+ if (typeof properties === "object" && properties !== null && !Array.isArray(properties)) {
1441
+ const names = Object.keys(properties);
1442
+ const required = new Set(Array.isArray(out["required"]) ? (out["required"] as string[]) : []);
1443
+ const map = properties as Record<string, unknown>;
1444
+ for (const name of names) {
1445
+ if (!required.has(name)) map[name] = { anyOf: [map[name], { type: "null" }] };
1446
+ }
1447
+ out["required"] = names;
1448
+ }
1449
+ return out;
1450
+ }
1451
+
1452
+ /**
1453
+ * The answer with the nulls Codex wrote for optional properties taken out, read along the schema
1454
+ * the caller gave (before the objects were closed): a property that schema does not require and
1455
+ * that came back null was left out by the model.
1456
+ *
1457
+ * The answer is first checked as it is; only one the schema refuses is cleaned and checked again.
1458
+ * A null the property's own schema accepts (nullable and optional) is kept either way.
1459
+ */
1460
+ function parseAnswer<T>(schema: z.ZodType<T>, answer: unknown): T {
1461
+ const raw = schema.safeParse(answer);
1462
+ if (raw.success) return raw.data;
1463
+ return schema.parse(withoutOptionalNulls(answer, callerJsonSchema(schema)));
1464
+ }
1465
+
1466
+ function withoutOptionalNulls(value: unknown, root: Record<string, unknown>): unknown {
1467
+ return stripNulls(value, root, root);
1468
+ }
1469
+
1470
+ type SchemaNode = Record<string, unknown>;
1471
+
1472
+ /** The schema nodes that apply to a value: the node, what it `$ref`s, and the branches of `anyOf`/`oneOf`/`allOf`. */
1473
+ function applicableNodes(schema: unknown, root: SchemaNode, seen = new Set<unknown>()): SchemaNode[] {
1474
+ if (typeof schema !== "object" || schema === null || Array.isArray(schema) || seen.has(schema)) return [];
1475
+ seen.add(schema);
1476
+ const node = schema as SchemaNode;
1477
+ const out: SchemaNode[] = [node];
1478
+ const ref = node["$ref"];
1479
+ if (typeof ref === "string" && ref.startsWith("#")) {
1480
+ let target: unknown = root;
1481
+ for (const part of ref.slice(1).split("/").filter((p) => p !== "")) {
1482
+ const name = decodeURIComponent(part).replaceAll("~1", "/").replaceAll("~0", "~");
1483
+ target = typeof target === "object" && target !== null ? (target as SchemaNode)[name] : undefined;
1484
+ }
1485
+ out.push(...applicableNodes(target, root, seen));
1486
+ }
1487
+ for (const keyword of ["anyOf", "oneOf", "allOf"]) {
1488
+ const branches = node[keyword];
1489
+ if (Array.isArray(branches)) for (const branch of branches) out.push(...applicableNodes(branch, root, seen));
1490
+ }
1491
+ return out;
1492
+ }
1493
+
1494
+ /** Whether a schema accepts null itself, so that a null for it is an answer and not a missing value. */
1495
+ function allowsNull(schema: unknown, root: SchemaNode): boolean {
1496
+ return applicableNodes(schema, root).some((node) => {
1497
+ const type = node["type"];
1498
+ return type === "null" || (Array.isArray(type) && type.includes("null")) || node["const"] === null;
1499
+ });
1500
+ }
1501
+
1502
+ function stripNulls(value: unknown, schema: unknown, root: SchemaNode): unknown {
1503
+ if (typeof value !== "object" || value === null) return value;
1504
+ const nodes = applicableNodes(schema, root);
1505
+ if (nodes.length === 0) return value;
1506
+ if (Array.isArray(value)) {
1507
+ return value.map((item, index) =>
1508
+ nodes.reduce((acc, node) => {
1509
+ const prefix = node["prefixItems"];
1510
+ const own = Array.isArray(prefix) && index < prefix.length ? prefix[index] : node["items"];
1511
+ return stripNulls(acc, own, root);
1512
+ }, item),
1513
+ );
1514
+ }
1515
+ const declared = (node: SchemaNode, key: string): unknown => {
1516
+ const properties = node["properties"];
1517
+ return typeof properties === "object" && properties !== null && Object.hasOwn(properties, key)
1518
+ ? (properties as SchemaNode)[key]
1519
+ : undefined;
1520
+ };
1521
+ const requires = (node: SchemaNode, key: string): boolean =>
1522
+ Array.isArray(node["required"]) && (node["required"] as unknown[]).includes(key);
1523
+ const out: Record<string, unknown> = {};
1524
+ for (const [key, item] of Object.entries(value)) {
1525
+ const declaring = nodes.filter((node) => declared(node, key) !== undefined);
1526
+ if (
1527
+ item === null &&
1528
+ declaring.length > 0 &&
1529
+ !nodes.some((node) => requires(node, key)) &&
1530
+ !declaring.some((node) => allowsNull(declared(node, key), root))
1531
+ ) {
1532
+ continue;
1533
+ }
1534
+ out[key] =
1535
+ declaring.length > 0
1536
+ ? declaring.reduce((acc, node) => stripNulls(acc, declared(node, key), root), item)
1537
+ : nodes.reduce((acc, node) => stripNulls(acc, node["additionalProperties"], root), item);
1538
+ }
1539
+ return out;
1540
+ }
1541
+
1542
+ /** The keywords whose value is a map from a name to a schema. */
1543
+ const SCHEMA_MAPS: ReadonlySet<string> = new Set([
1544
+ "properties",
1545
+ "patternProperties",
1546
+ "dependentSchemas",
1547
+ "$defs",
1548
+ "definitions",
1549
+ ]);
1550
+
1551
+ /** The keywords whose value is data a schema describes, not a schema. */
1552
+ const DATA_KEYWORDS: ReadonlySet<string> = new Set(["enum", "const", "default", "examples"]);
1553
+
1554
+ /**
1555
+ * The pieces of JSON an answer may hold, most likely first. An answer decoded under a schema is
1556
+ * JSON; one asked for in the text may come in a code fence or with words around it, and the words
1557
+ * may have braces of their own, so every balanced `{...}` or `[...]` in it is a reading.
1558
+ */
1559
+ function jsonReadings(text: string): unknown[] {
1560
+ const candidates = [text.trim()];
1561
+ for (const fenced of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)) candidates.push((fenced[1] ?? "").trim());
1562
+ for (let start = 0; start < text.length; start += 1) {
1563
+ if (text[start] !== "{" && text[start] !== "[") continue;
1564
+ const end = balancedEnd(text, start);
1565
+ if (end > start) candidates.push(text.slice(start, end + 1));
1566
+ }
1567
+ const readings: unknown[] = [];
1568
+ for (const candidate of candidates) {
1569
+ try {
1570
+ readings.push(JSON.parse(candidate) as unknown);
1571
+ } catch {
1572
+ // Not JSON.
1573
+ }
1574
+ }
1575
+ // Nothing to read: the schema gets `undefined`, and says what it wanted.
1576
+ return readings.length === 0 ? [undefined] : readings;
1577
+ }
1578
+
1579
+ /** The index of the bracket closing the one at `start`, reading strings as JSON does; -1 if none. */
1580
+ function balancedEnd(text: string, start: number): number {
1581
+ let depth = 0;
1582
+ let inString = false;
1583
+ for (let i = start; i < text.length; i += 1) {
1584
+ const char = text[i];
1585
+ if (inString) {
1586
+ if (char === "\\") i += 1;
1587
+ else if (char === '"') inString = false;
1588
+ } else if (char === '"') inString = true;
1589
+ else if (char === "{" || char === "[") depth += 1;
1590
+ else if (char === "}" || char === "]") {
1591
+ depth -= 1;
1592
+ if (depth === 0) return i;
1593
+ }
1594
+ }
1595
+ return -1;
1596
+ }