@vibelet/cli 0.1.35 → 0.1.37

package/src/drivers/codex.test.ts

@@ -0,0 +1,1096 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFile, rm, chmod, mkdtemp, readFile } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import type { ServerMessage } from '@vibelet/shared';
+import { CodexDriver } from './codex.js';
+
+// Helper: access private members via `any` cast
+function getDriver() {
+  const driver = new CodexDriver();
+  const d = driver as any;
+  return { driver, d };
+}
+
+// ─── RPC response handling ───────────────────────────────────────────
+
+test('handleRaw resolves pending promise on successful RPC response', async () => {
+  const { driver, d } = getDriver();
+
+  let resolved: unknown;
+  const promise = new Promise<unknown>((resolve, reject) => {
+    d.pending.set(1, { resolve, reject });
+  });
+  promise.then((v) => { resolved = v; });
+
+  d.handleRaw({ id: 1, result: { thread: { id: 'th-1' } } });
+
+  // Let microtask run
+  await new Promise((r) => setTimeout(r, 0));
+  assert.deepEqual(resolved, { thread: { id: 'th-1' } });
+  assert.equal(d.pending.size, 0);
+});
+
+test('handleRaw rejects pending promise on RPC error response', async () => {
+  const { driver, d } = getDriver();
+
+  let rejected: Error | undefined;
+  const promise = new Promise<unknown>((resolve, reject) => {
+    d.pending.set(2, { resolve, reject });
+  });
+  promise.catch((e: Error) => { rejected = e; });
+
+  d.handleRaw({ id: 2, error: { message: 'something went wrong' } });
+
+  await new Promise((r) => setTimeout(r, 0));
+  assert.ok(rejected);
+  assert.equal(rejected!.message, 'something went wrong');
+  assert.equal(d.pending.size, 0);
+});
+
+test('handleRaw rejects with default message when RPC error has no message', async () => {
+  const { driver, d } = getDriver();
+
+  let rejected: Error | undefined;
+  const promise = new Promise<unknown>((resolve, reject) => {
+    d.pending.set(3, { resolve, reject });
+  });
+  promise.catch((e: Error) => { rejected = e; });
+
+  d.handleRaw({ id: 3, error: {} });
+
+  await new Promise((r) => setTimeout(r, 0));
+  assert.ok(rejected);
+  assert.equal(rejected!.message, 'RPC error');
+});
+
+test('handleRaw ignores RPC response with unknown id', () => {
+  const { driver, d } = getDriver();
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  // No pending entry for id=99
+  d.handleRaw({ id: 99, result: 'ok' });
+
+  assert.equal(messages.length, 0);
+});
+
+// ─── Approval request ────────────────────────────────────────────────
+
+test('handleRaw emits approval.request for commandExecution/requestApproval', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'thread-42';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    jsonrpc: '2.0',
+    method: 'item/commandExecution/requestApproval',
+    id: 10,
+    params: {
+      command: 'rm -rf /',
+      cwd: '/home',
+      reason: 'needs cleanup',
+    },
+  });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'approval.request',
+    sessionId: 'thread-42',
+    requestId: '10',
+    toolName: 'Bash',
+    input: { command: 'rm -rf /', cwd: '/home' },
+    description: 'needs cleanup',
+    approvalContext: {
+      provider: 'codex',
+      kind: 'command-execution',
+      rpcId: 10,
+    },
+  });
+});
+
+test('handleRaw approval.request uses empty defaults when params missing', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'item/commandExecution/requestApproval',
+    id: 20,
+    params: {},
+  });
+
+  assert.equal(messages.length, 1);
+  const msg = messages[0] as any;
+  assert.deepEqual(msg.input, {});
+  assert.equal(msg.description, '');
+});
+
+test('handleRaw emits approval.request for fileChange/requestApproval using remembered tool context', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'thread-43';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'item/started',
+    params: {
+      item: {
+        type: 'file_change',
+        id: 'patch-1',
+        path: 'world.md',
+        changes: [{ kind: 'create' }],
+      },
+    },
+  });
+
+  d.handleRaw({
+    method: 'item/fileChange/requestApproval',
+    id: 11,
+    params: {
+      itemId: 'patch-1',
+      reason: 'create a file',
+    },
+  });
+
+  assert.equal(messages.length, 2);
+  assert.deepEqual(messages[1], {
+    type: 'approval.request',
+    sessionId: 'thread-43',
+    requestId: '11',
+    toolName: 'Patch',
+    input: {
+      path: 'world.md',
+      changes: [{ kind: 'create' }],
+    },
+    description: 'create a file',
+    approvalContext: {
+      provider: 'codex',
+      kind: 'file-change',
+      rpcId: 11,
+    },
+  });
+});
+
+test('handleRaw emits approval.request for approval-shaped requestUserInput', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'thread-44';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'item/started',
+    params: {
+      item: { type: 'command_execution', id: 'cmd-approval', command: 'touch world.md' },
+    },
+  });
+
+  d.handleRaw({
+    method: 'item/tool/requestUserInput',
+    id: 12,
+    params: {
+      itemId: 'cmd-approval',
+      questions: [
+        {
+          id: 'q1',
+          question: 'Allow this write?',
+          options: [{ label: 'Allow' }, { label: 'Deny' }],
+        },
+      ],
+    },
+  });
+
+  assert.equal(messages.length, 2);
+  assert.deepEqual(messages[1], {
+    type: 'approval.request',
+    sessionId: 'thread-44',
+    requestId: '12',
+    toolName: 'Bash',
+    input: { command: 'touch world.md' },
+    description: 'Allow this write?',
+    approvalContext: {
+      provider: 'codex',
+      kind: 'request-user-input-approval',
+      rpcId: 12,
+      questionId: 'q1',
+      approveLabel: 'Allow',
+      denyLabel: 'Deny',
+    },
+  });
+});
+
+test('handleRaw rejects multi-question approval requests when allow/deny labels belong to different questions', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'thread-45';
+  const messages: ServerMessage[] = [];
+  let written = '';
+  driver.onMessage((msg) => messages.push(msg));
+  d.proc = {
+    stdin: {
+      writable: true,
+      write(chunk: string) {
+        written += chunk;
+        return true;
+      },
+    },
+  };
+
+  d.handleRaw({
+    method: 'item/tool/requestUserInput',
+    id: 14,
+    params: {
+      questions: [
+        {
+          id: 'q-allow',
+          question: 'Allow this write?',
+          options: [{ label: 'Allow' }],
+        },
+        {
+          id: 'q-deny',
+          question: 'Block this write?',
+          options: [{ label: 'Deny' }],
+        },
+      ],
+    },
+  });
+
+  assert.equal(messages.length, 0);
+  const response = JSON.parse(written.trim());
+  assert.equal(response.id, 14);
+  assert.equal(response.error.code, -32601);
+  assert.match(response.error.message, /Malformed requestUserInput approval request/i);
+});
+
+test('handleRaw rejects unsupported permissions approval requests instead of hanging', () => {
+  const { d } = getDriver();
+  let written = '';
+  d.proc = {
+    stdin: {
+      writable: true,
+      write(chunk: string) {
+        written += chunk;
+        return true;
+      },
+    },
+  };
+
+  d.handleRaw({
+    method: 'item/permissions/requestApproval',
+    id: 13,
+    params: { itemId: 'perm-1' },
+  });
+
+  const response = JSON.parse(written.trim());
+  assert.equal(response.id, 13);
+  assert.equal(response.error.code, -32601);
+  assert.match(response.error.message, /Unsupported permissions approval request/i);
+});
+
+// ─── agentMessage/delta ──────────────────────────────────────────────
+
+test('handleRaw emits text.delta from params.text', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'item/agentMessage/delta', params: { text: 'hello' } });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'text.delta',
+    sessionId: 'th-1',
+    content: 'hello',
+  });
+});
+
+test('handleRaw emits text.delta from params.delta', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'item/agentMessage/delta', params: { delta: 'world' } });
+
+  assert.equal(messages.length, 1);
+  assert.equal((messages[0] as any).content, 'world');
+});
+
+test('handleRaw emits text.delta from params.content', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'item/agentMessage/delta', params: { content: 'foo' } });
+
+  assert.equal(messages.length, 1);
+  assert.equal((messages[0] as any).content, 'foo');
+});
+
+test('handleRaw ignores agentMessage/delta with empty text', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'item/agentMessage/delta', params: {} });
+
+  assert.equal(messages.length, 0);
+});
+
+// ─── commandExecution/outputDelta ────────────────────────────────────
+
+test('handleRaw emits tool.result for commandExecution/outputDelta', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'item/commandExecution/outputDelta',
+    params: { output: 'line1\nline2', itemId: 'item-5' },
+  });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'tool.result',
+    sessionId: 'th-1',
+    toolCallId: 'item-5',
+    output: 'line1\nline2',
+  });
+});
+
+test('handleRaw ignores commandExecution/outputDelta without output', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'item/commandExecution/outputDelta', params: {} });
+
+  assert.equal(messages.length, 0);
+});
+
+// ─── item/started ────────────────────────────────────────────────────
+
+test('handleRaw emits tool.call for item/started with command_execution', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'item/started',
+    params: {
+      item: { type: 'command_execution', command: 'ls -la', id: 'cmd-1' },
+    },
+  });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'tool.call',
+    sessionId: 'th-1',
+    toolName: 'Bash',
+    input: { command: 'ls -la' },
+    toolCallId: 'cmd-1',
+  });
+});
+
+test('handleRaw ignores item/started with non-command_execution type', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'item/started',
+    params: { item: { type: 'agent_message', id: 'msg-1' } },
+  });
+
+  assert.equal(messages.length, 0);
+});
+
+test('handleRaw ignores item/started without item param', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'item/started', params: {} });
+
+  assert.equal(messages.length, 0);
+});
+
+// ─── turn/completed ──────────────────────────────────────────────────
+
+test('handleRaw emits session.done on turn/completed with usage', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'turn/completed',
+    params: {
+      turn: { status: 'completed' },
+      usage: { input_tokens: 100, output_tokens: 50 },
+    },
+  });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'session.done',
+    sessionId: 'th-1',
+    usage: { inputTokens: 100, outputTokens: 50 },
+  });
+});
+
+test('handleRaw emits session.done on turn/completed without usage', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'turn/completed', params: {} });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'session.done',
+    sessionId: 'th-1',
+    usage: undefined,
+  });
+});
+
+test('handleRaw emits session.interrupted on turn/completed with aborted status', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'turn/completed',
+    params: {
+      turn: { status: 'aborted' },
+      usage: { input_tokens: 100, output_tokens: 50 },
+    },
+  });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'session.interrupted',
+    sessionId: 'th-1',
+  });
+});
+
+test('handleRaw emits session.interrupted on turn/aborted', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({
+    method: 'turn/aborted',
+    params: { reason: 'interrupted' },
+  });
+
+  assert.equal(messages.length, 1);
+  assert.deepEqual(messages[0], {
+    type: 'session.interrupted',
+    sessionId: 'th-1',
+  });
+});
+
+// ─── Unknown / default ──────────────────────────────────────────────
+
+test('handleRaw does not emit message for unknown notification method', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  d.handleRaw({ method: 'some/unknown/method', params: {} });
+
+  assert.equal(messages.length, 0);
+});
+
+test('handleRaw does not emit message when method is absent and id is not pending', () => {
+  const { driver, d } = getDriver();
+  d.threadId = 'th-1';
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+
+  // A response-like message with no pending entry
+  d.handleRaw({ id: 999, result: 'whatever' });
+
+  assert.equal(messages.length, 0);
+});
+
+// ─── No handler ──────────────────────────────────────────────────────
+
+test('handleRaw does not throw when handler is null', () => {
+  const { driver, d } = getDriver();
+  // Do NOT set handler
+
+  assert.doesNotThrow(() => {
+    d.handleRaw({ method: 'item/agentMessage/delta', params: { text: 'hi' } });
+  });
+});
+
+test('handleRaw does not throw for approval request when handler is null', () => {
+  const { driver, d } = getDriver();
+
+  assert.doesNotThrow(() => {
+    d.handleRaw({
+      method: 'item/commandExecution/requestApproval',
+      id: 1,
+      params: { command: 'ls' },
+    });
+  });
+});
+
+// ─── buildSpawnArgs ──────────────────────────────────────────────────
+
+test('buildSpawnArgs always returns base app-server args', () => {
+  const { d } = getDriver();
+
+  const args = d.buildSpawnArgs();
+
+  assert.deepEqual(args, ['app-server', '--listen', 'stdio://']);
+});
+
+// ─── stop() ──────────────────────────────────────────────────────────
+
+test('stop() does nothing when proc is null', () => {
+  const { driver } = getDriver();
+  assert.doesNotThrow(() => driver.stop());
+});
+
+test('stop() rejects all pending RPCs when proc is set', async () => {
+  const { driver, d } = getDriver();
+
+  // Fake proc so stop() doesn't bail out early
+  d.proc = { kill: () => {}, killed: false };
+
+  const errors: Error[] = [];
+  const p1 = new Promise<unknown>((resolve, reject) => {
+    d.pending.set(1, { resolve, reject });
+  }).catch((e: Error) => { errors.push(e); });
+  const p2 = new Promise<unknown>((resolve, reject) => {
+    d.pending.set(2, { resolve, reject });
+  }).catch((e: Error) => { errors.push(e); });
+
+  driver.stop();
+
+  await Promise.all([p1, p2]);
+  assert.equal(errors.length, 2);
+  assert.ok(errors.every((e) => e.message === 'Process stopped'));
+  assert.equal(d.pending.size, 0);
+});
+
+// ─── interrupt() ─────────────────────────────────────────────────────
+
+test('interrupt() rejects with Process not available when proc is null', async () => {
+  const { d } = getDriver();
+  await assert.rejects(() => d.rpc('turn/interrupt', { threadId: '' }), {
+    message: 'Process not available',
+  });
+});
+
+// ─── sendPrompt() ────────────────────────────────────────────────────
+
+test('sendPrompt() emits error when proc is null', async () => {
+  const { driver, d } = getDriver();
+  const messages: ServerMessage[] = [];
+  driver.onMessage((msg) => messages.push(msg));
+  d.threadId = 'th-1';
+
+  driver.sendPrompt('hello');
+
+  // Wait for the internal promise rejection to propagate
+  await new Promise((r) => setTimeout(r, 50));
+  assert.ok(messages.length >= 1);
+  const errMsg = messages.find((m) => m.type === 'error');
+  assert.ok(errMsg);
+});
+
+// ─── respondApproval() ───────────────────────────────────────────────
+
+test('respondApproval() does nothing when proc is null', () => {
+  const { driver } = getDriver();
+  assert.doesNotThrow(() => driver.respondApproval('1', true));
+  assert.doesNotThrow(() => driver.respondApproval('2', false));
+});
+
+test('respondApproval() maps command approvals to accept/decline', () => {
+  const { driver, d } = getDriver();
+  let written = '';
+  d.proc = {
+    stdin: {
+      writable: true,
+      write(chunk: string) {
+        written += chunk;
+        return true;
+      },
+    },
+  };
+  d.approvalRequests.set('21', {
+    kind: 'command-execution',
+    responseKind: 'v2',
+    rpcId: 21,
+    toolName: 'Bash',
+    input: { command: 'ls' },
+  });
+
+  assert.equal(driver.respondApproval('21', true), true);
+  assert.deepEqual(JSON.parse(written.trim()), {
+    jsonrpc: '2.0',
+    id: 21,
+    result: { decision: 'accept' },
+  });
+});
+
+test('respondApproval() maps requestUserInput approvals to answers payload', () => {
+  const { driver, d } = getDriver();
+  let written = '';
+  d.proc = {
+    stdin: {
+      writable: true,
+      write(chunk: string) {
+        written += chunk;
+        return true;
+      },
+    },
+  };
+  d.approvalRequests.set('22', {
+    kind: 'request-user-input-approval',
+    rpcId: 22,
+    questionId: 'q1',
+    approveLabel: 'Allow',
+    denyLabel: 'Deny',
+    toolName: 'Patch',
+    input: { path: 'world.md' },
+  });
+
+  assert.equal(driver.respondApproval('22', false), true);
+  assert.deepEqual(JSON.parse(written.trim()), {
+    jsonrpc: '2.0',
+    id: 22,
+    result: {
+      answers: {
+        q1: {
+          answers: ['Deny'],
+        },
+      },
+    },
+  });
+});
+
+// ─── onMessage() ─────────────────────────────────────────────────────
+
+test('onMessage() sets the handler', () => {
+  const { driver, d } = getDriver();
+  assert.equal(d.handler, null);
+  const handler = () => {};
+  driver.onMessage(handler);
+  assert.equal(d.handler, handler);
+});
+
+// ─── onExit() ────────────────────────────────────────────────────────
+
+test('onExit() sets the exit handler', () => {
+  const { driver, d } = getDriver();
+  assert.equal(d.exitHandler, null);
+  const handler = () => {};
+  driver.onExit(handler);
+  assert.equal(d.exitHandler, handler);
+});
+
+// ─── notify() (private) ─────────────────────────────────────────────
+
+test('notify() does nothing when proc is null', () => {
+  const { d } = getDriver();
+  assert.doesNotThrow(() => d.rpcNotify('some/method', { data: 1 }));
+});
+
+// ─── rpc() (private) ────────────────────────────────────────────────
+
+test('rpc() rejects immediately when proc is null', async () => {
+  const { d } = getDriver();
+  await assert.rejects(() => d.rpc('some/method', {}), {
+    message: 'Process not available',
+  });
+});
+
+// ─── Fake codex binary helper ────────────────────────────────────────
+
+async function createFakeCodex(tmpDir: string, behavior = 'normal'): Promise<string> {
+  const scriptPath = join(tmpDir, 'fake-codex');
+
+  let script: string;
+  if (behavior === 'normal') {
+    script = `#!/usr/bin/env node
+const fs = require('fs');
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin });
+let initializeCapabilities = null;
+rl.on('line', (line) => {
+  try {
+    const msg = JSON.parse(line);
+    if (process.env.CODEX_TEST_LOG) {
+      fs.appendFileSync(process.env.CODEX_TEST_LOG, JSON.stringify(msg) + '\\n');
+    }
+    if (msg.method === 'initialize') {
+      initializeCapabilities = msg.params?.capabilities ?? null;
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { ok: true } }) + '\\n');
+    } else if (msg.method === 'initialized') {
+      // notification
+    } else if (msg.method === 'thread/start') {
+      if (msg.params?.experimentalRawEvents && !initializeCapabilities?.experimentalApi) {
+        process.stdout.write(JSON.stringify({
+          jsonrpc: '2.0',
+          id: msg.id,
+          error: { code: -32602, message: 'thread/start.experimentalRawEvents requires experimentalApi capability' },
+        }) + '\\n');
+        return;
+      }
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { thread: { id: 'test-thread-123' } } }) + '\\n');
+    } else if (msg.method === 'thread/resume') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { thread: { id: msg.params?.threadId || 'resumed' } } }) + '\\n');
+    } else if (msg.method === 'turn/start') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', method: 'item/agentMessage/delta', params: { text: 'Hello' } }) + '\\n');
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', method: 'turn/completed', params: { usage: { input_tokens: 10, output_tokens: 5 } } }) + '\\n');
+    } else if (msg.method === 'turn/interrupt') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+    } else if (msg.method === 'thread/list') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { threads: [] } }) + '\\n');
+    } else if (msg.id != null) {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+    }
+  } catch {}
+});
+`;
+  } else if (behavior === 'interrupt-race') {
+    script = `#!/usr/bin/env node
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin });
+let turnReady = false;
+let turnInterrupted = false;
+let turnCompleted = false;
+rl.on('line', (line) => {
+  try {
+    const msg = JSON.parse(line);
+    if (msg.method === 'initialize') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { ok: true } }) + '\\n');
+    } else if (msg.method === 'initialized') {
+      // notification
+    } else if (msg.method === 'thread/start') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { thread: { id: 'race-thread-123' } } }) + '\\n');
+    } else if (msg.method === 'turn/start') {
+      setTimeout(() => {
+        turnReady = true;
+        process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+        setTimeout(() => {
+          if (turnInterrupted || turnCompleted) return;
+          turnCompleted = true;
+          process.stdout.write(JSON.stringify({ jsonrpc: '2.0', method: 'item/agentMessage/delta', params: { text: 'Late reply' } }) + '\\n');
+          process.stdout.write(JSON.stringify({ jsonrpc: '2.0', method: 'turn/completed', params: { usage: { input_tokens: 4, output_tokens: 2 } } }) + '\\n');
+        }, 80);
+      }, 120);
+    } else if (msg.method === 'turn/interrupt') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+      if (turnReady && !turnInterrupted && !turnCompleted) {
+        turnInterrupted = true;
+        process.stdout.write(JSON.stringify({ jsonrpc: '2.0', method: 'turn/aborted', params: { reason: 'interrupted' } }) + '\\n');
+      }
+    } else if (msg.id != null) {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+    }
+  } catch {}
+});
+`;
+  } else if (behavior === 'exit-immediately') {
+    script = `#!/usr/bin/env node
+process.exit(1);
+`;
+  } else {
+    script = `#!/usr/bin/env node
+setTimeout(() => {}, 60000);
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', () => {});
+`;
+  }
+
+  await writeFile(scriptPath, script, 'utf-8');
+  await chmod(scriptPath, 0o755);
+  return scriptPath;
+}
+
+async function withFakeCodex(
+  behavior: string,
+  fn: (driver: CodexDriver) => Promise<void>,
+): Promise<void> {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'codex-test-'));
+  const scriptPath = await createFakeCodex(tmpDir, behavior);
+  const originalCodexPath = process.env.CODEX_PATH;
+  process.env.CODEX_PATH = scriptPath;
+  const driver = new CodexDriver();
+  try {
+    await fn(driver);
+  } finally {
+    driver.stop();
+    process.env.CODEX_PATH = originalCodexPath;
+    if (!originalCodexPath) delete process.env.CODEX_PATH;
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// ─── Integration tests: start() ─────────────────────────────────────
+
+test('start: creates a new thread and returns threadId', async () => {
+  await withFakeCodex('normal', async (driver) => {
+    const threadId = await driver.start('/tmp');
+    assert.equal(threadId, 'test-thread-123');
+  });
+});
+
+test('start: resumes existing thread when resumeSessionId provided', async () => {
+  await withFakeCodex('normal', async (driver) => {
+    const threadId = await driver.start('/tmp', 'my-existing-thread');
+    assert.equal(threadId, 'my-existing-thread');
+  });
+});
+
+test('start: sends correct args for autoApprove mode', async () => {
+  await withFakeCodex('normal', async (driver) => {
+    const threadId = await driver.start('/tmp', undefined, 'autoApprove');
+    assert.equal(threadId, 'test-thread-123');
+  });
+});
+
+test('start: sends explicit on-request workspace-write policy for normal mode', async () => {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'codex-policy-'));
+  const logPath = join(tmpDir, 'requests.jsonl');
+  const originalLogPath = process.env.CODEX_TEST_LOG;
+  process.env.CODEX_TEST_LOG = logPath;
+  try {
+    await withFakeCodex('normal', async (driver) => {
+      await driver.start('/tmp', undefined, 'normal');
+    });
+
+    const entries = (await readFile(logPath, 'utf-8'))
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+    const initialize = entries.find((entry) => entry.method === 'initialize');
+    const threadStart = entries.find((entry) => entry.method === 'thread/start');
+    assert.ok(initialize);
+    assert.ok(threadStart);
+    assert.equal(initialize.params.capabilities.experimentalApi, true);
+    assert.equal(threadStart.params.approvalPolicy, 'on-request');
+    assert.equal(threadStart.params.sandbox, 'workspace-write');
+    assert.equal(threadStart.params.experimentalRawEvents, true);
+  } finally {
+    if (originalLogPath === undefined) delete process.env.CODEX_TEST_LOG;
+    else process.env.CODEX_TEST_LOG = originalLogPath;
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+// ─── Integration tests: sendPrompt() ────────────────────────────────
+
+test('sendPrompt: sends turn/start and receives response', async () => {
+  await withFakeCodex('normal', async (driver) => {
+    await driver.start('/tmp');
+
+    const messages: ServerMessage[] = [];
+    driver.onMessage((msg) => messages.push(msg));
+
+    driver.sendPrompt('test message');
+
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    const types = messages.map((m) => m.type);
+    assert.ok(types.includes('text.delta'), `Expected text.delta in ${JSON.stringify(types)}`);
+    assert.ok(types.includes('session.done'), `Expected session.done in ${JSON.stringify(types)}`);
+  });
+});
+
+test('sendPrompt: sends explicit turn approvalPolicy and sandboxPolicy', async () => {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'codex-turn-policy-'));
+  const logPath = join(tmpDir, 'requests.jsonl');
+  const originalLogPath = process.env.CODEX_TEST_LOG;
+  process.env.CODEX_TEST_LOG = logPath;
+  try {
+    await withFakeCodex('normal', async (driver) => {
+      await driver.start('/tmp', undefined, 'normal');
+      driver.onMessage(() => {});
+      driver.sendPrompt('create world.md');
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    });
+
+    const entries = (await readFile(logPath, 'utf-8'))
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+    const turnStart = entries.find((entry) => entry.method === 'turn/start');
+    assert.ok(turnStart);
+    assert.equal(turnStart.params.approvalPolicy, 'on-request');
+    assert.equal(turnStart.params.sandboxPolicy.type, 'workspaceWrite');
+    assert.deepEqual(turnStart.params.sandboxPolicy.writableRoots, ['/tmp']);
+  } finally {
+    if (originalLogPath === undefined) delete process.env.CODEX_TEST_LOG;
+    else process.env.CODEX_TEST_LOG = originalLogPath;
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('interrupt: retries after turn/start resolves when interrupt arrives too early', async () => {
+  await withFakeCodex('interrupt-race', async (driver) => {
+    await driver.start('/tmp');
+
+    const messages: ServerMessage[] = [];
+    driver.onMessage((msg) => messages.push(msg));
+
+    driver.sendPrompt('interrupt me quickly');
+    driver.interrupt();
+
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    const types = messages.map((m) => m.type);
+    assert.ok(types.includes('session.interrupted'), `Expected session.interrupted in ${JSON.stringify(types)}`);
+    assert.ok(!types.includes('session.done'), `Did not expect session.done in ${JSON.stringify(types)}`);
+    assert.ok(!types.includes('text.delta'), `Did not expect text.delta in ${JSON.stringify(types)}`);
+  });
+});
+
+// ─── Integration tests: stop() ──────────────────────────────────────
+
+test('stop: kills process and rejects pending RPCs', async () => {
+  await withFakeCodex('normal', async (driver) => {
+    await driver.start('/tmp');
+
+    driver.stop();
+    assert.equal((driver as any).proc, null);
+    assert.equal((driver as any).pending.size, 0);
+  });
+});
+
+// ─── Integration tests: exit handler ─────────────────────────────────
+
+test('start: exit handler rejects pending RPCs and emits error on non-zero exit', async () => {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'codex-exit-'));
+  const scriptPath = join(tmpDir, 'fake-codex');
+  await writeFile(scriptPath, `#!/usr/bin/env node
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', (line) => {
+  try {
+    const msg = JSON.parse(line);
+    if (msg.method === 'initialize') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+    } else if (msg.method === 'thread/start') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { thread: { id: 'exit-thread' } } }) + '\\n');
+      setTimeout(() => process.exit(1), 50);
+    } else if (msg.id != null) {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+    }
+  } catch {}
+});
+`, 'utf-8');
+  await chmod(scriptPath, 0o755);
+
+  const original = process.env.CODEX_PATH;
+  process.env.CODEX_PATH = scriptPath;
+  const driver = new CodexDriver();
+  try {
+    await driver.start('/tmp');
+    const messages: ServerMessage[] = [];
+    driver.onMessage((msg) => messages.push(msg));
+
+    // Wait for the process to exit
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    const errors = messages.filter(m => m.type === 'error');
+    assert.ok(errors.length > 0, 'Should emit error on non-zero exit');
+  } finally {
+    driver.stop();
+    process.env.CODEX_PATH = original;
+    if (!original) delete process.env.CODEX_PATH;
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('start: exit handler calls exitHandler callback', async () => {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'codex-exitcb-'));
+  const scriptPath = join(tmpDir, 'fake-codex');
+  await writeFile(scriptPath, `#!/usr/bin/env node
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', (line) => {
+  try {
+    const msg = JSON.parse(line);
+    if (msg.method === 'initialize') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+    } else if (msg.method === 'thread/start') {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { thread: { id: 'exit-thread' } } }) + '\\n');
+      setTimeout(() => process.exit(1), 50);
+    } else if (msg.id != null) {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} }) + '\\n');
+    }
+  } catch {}
+});
+`, 'utf-8');
+  await chmod(scriptPath, 0o755);
+
+  const original = process.env.CODEX_PATH;
+  process.env.CODEX_PATH = scriptPath;
+  const driver = new CodexDriver();
+  try {
+    await driver.start('/tmp');
+    let exitCode: number | null = null;
+    driver.onExit((code) => { exitCode = code; });
+
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    assert.equal(exitCode, 1);
+  } finally {
+    driver.stop();
+    process.env.CODEX_PATH = original;
+    if (!original) delete process.env.CODEX_PATH;
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+// ─── Integration tests: spawn error ──────────────────────────────────
+
+test('start: spawn error with exit-immediately behavior rejects start', async () => {
+  await assert.rejects(
+    () => withFakeCodex('exit-immediately', async (driver) => {
+      await driver.start('/tmp');
+    }),
+    (err: Error) => {
+      return err.message.includes('exited with code 1');
+    },
+  );
+});
+
+// ─── setApprovalMode ─────────────────────────────────────────────────
+
+test('setApprovalMode: updates approvalMode field', () => {
+  const driver = new CodexDriver();
+  (driver as any).approvalMode = 'normal';
+
+  driver.setApprovalMode('autoApprove');
+  assert.equal((driver as any).approvalMode, 'autoApprove');
+
+  driver.setApprovalMode('normal');
+  assert.equal((driver as any).approvalMode, 'normal');
+});