@prismatic-io/lux 0.0.1

package/src/drivers/codex/index.ts

@@ -0,0 +1,995 @@
+import { cp, mkdir, realpath, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { temporaryDirectory } from "tempy";
+import { z } from "zod";
+import {
+  type AgentDriver,
+  type Answer,
+  type Artifact,
+  type DriverEventMap,
+  type DriverPlugin,
+  discoverCliVersion,
+  type ParsedDriverEvent,
+  type ReadyState,
+  type StartContext,
+  spawnManagedProcess,
+  type TokenUsage,
+  TypedEmitter,
+  toolResultProgress,
+} from "../../core/index.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+import { copyRegularFileNoFollow } from "../shared/secure-copy.js";
+import { subprocessDriver } from "../subprocess/index.js";
+import {
+  type AppTurnFacets,
+  appItemProgress,
+  appItemToolName,
+  appTurnLabel,
+  appUsage,
+  asRecord,
+  messageOf,
+  type RpcId,
+  type RpcRecord,
+} from "./app-events.js";
+import {
+  buildAppServerArgs,
+  buildExecArgs as buildArgs,
+  type CodexConfigValue,
+  type CodexDriverConfig,
+  CodexDriverConfigSchema,
+} from "./config.js";
+
+const LUX_BOOKKEEPING_FILES = new Set(["events.jsonl", "case.json", "run.json", "grading.json"]);
+const commandName = (command: string): string => command.split(/[\\/]/).at(-1) ?? command;
+
+const CodexUsageSchema = z.object({
+  input_tokens: z.number().nonnegative().catch(0),
+  cached_input_tokens: z.number().nonnegative().catch(0),
+  output_tokens: z.number().nonnegative().catch(0),
+});
+
+const parseUsage = (raw: unknown): TokenUsage | null => {
+  const usage = CodexUsageSchema.safeParse(raw).data;
+  if (!usage) return null;
+  return {
+    input: Math.max(0, usage.input_tokens - usage.cached_input_tokens),
+    output: usage.output_tokens,
+    cacheRead: usage.cached_input_tokens,
+    cacheCreation: 0,
+  };
+};
+
+const resultText = (content: unknown): string => {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (block): block is { type: "text"; text: string } =>
+        typeof block === "object" &&
+        block !== null &&
+        (block as { type?: unknown }).type === "text" &&
+        typeof (block as { text?: unknown }).text === "string",
+    )
+    .map((block) => block.text)
+    .join("\n");
+};
+
+const startedItemProgress = (
+  item: Record<string, unknown>,
+  id: string,
+): ParsedDriverEvent | null => {
+  if (item.type === "command_execution") {
+    return {
+      tag: "progress",
+      progress: {
+        id: `tc-${id}`,
+        kind: "tool-call",
+        payload: { name: "command_execution", input: { command: item.command }, toolUseId: id },
+        ts: Date.now(),
+      },
+    };
+  }
+  if (item.type === "mcp_tool_call") {
+    const tool = typeof item.tool === "string" ? item.tool : String(item.name ?? "mcp_tool_call");
+    const server = typeof item.server === "string" ? item.server : undefined;
+    return {
+      tag: "progress",
+      progress: {
+        id: `tc-${id}`,
+        kind: "tool-call",
+        payload: {
+          name: tool,
+          input: item.arguments ?? item.input,
+          toolUseId: id,
+          ...(server ? { server } : {}),
+        },
+        ts: Date.now(),
+      },
+    };
+  }
+  if (item.type === "web_search") {
+    return {
+      tag: "progress",
+      progress: {
+        id: `tc-${id}`,
+        kind: "tool-call",
+        payload: { name: "web_search", input: { query: item.query }, toolUseId: id },
+        ts: Date.now(),
+      },
+    };
+  }
+  if (item.type === "file_change") {
+    return {
+      tag: "progress",
+      progress: {
+        id: `tc-${id}`,
+        kind: "tool-call",
+        payload: { name: "file_change", input: { changes: item.changes }, toolUseId: id },
+        ts: Date.now(),
+      },
+    };
+  }
+  return null;
+};
+
+const completedItemProgress = (
+  item: Record<string, unknown>,
+  id: string,
+): ParsedDriverEvent | null => {
+  if (item.type === "agent_message" && typeof item.text === "string") {
+    return {
+      tag: "progress",
+      progress: {
+        id: `am-${id}`,
+        kind: "agent-message",
+        payload: { text: item.text },
+        ts: Date.now(),
+      },
+    };
+  }
+  if (item.type === "reasoning") {
+    const text = typeof item.text === "string" ? item.text : item.summary;
+    return {
+      tag: "progress",
+      progress: { id: `reasoning-${id}`, kind: "reasoning", payload: { text }, ts: Date.now() },
+    };
+  }
+  if (item.type === "mcp_tool_call") {
+    const tool = typeof item.tool === "string" ? item.tool : String(item.name ?? "mcp_tool_call");
+    const raw =
+      item.result && typeof item.result === "object"
+        ? (item.result as Record<string, unknown>)
+        : item;
+    const content = raw.content ?? item.result ?? [];
+    const structuredContent = raw.structuredContent ?? raw.structured_content;
+    return {
+      tag: "progress",
+      progress: toolResultProgress(
+        0,
+        {
+          name: tool,
+          toolUseId: id,
+          content,
+          ...(structuredContent && typeof structuredContent === "object"
+            ? { structuredContent: structuredContent as Record<string, unknown> }
+            : {}),
+          isError:
+            raw.isError === true ||
+            raw.is_error === true ||
+            item.status === "failed" ||
+            (item.error !== undefined && item.error !== null),
+          text: resultText(content) || (typeof item.error === "string" ? item.error : ""),
+        },
+        Date.now(),
+      ),
+    };
+  }
+  if (item.type === "command_execution") {
+    const output = item.aggregated_output ?? item.output ?? "";
+    const exitCode = typeof item.exit_code === "number" ? item.exit_code : undefined;
+    return {
+      tag: "progress",
+      progress: toolResultProgress(
+        0,
+        {
+          name: "command_execution",
+          toolUseId: id,
+          content: { output, ...(exitCode !== undefined ? { exitCode } : {}) },
+          isError: item.status === "failed" || (exitCode !== undefined && exitCode !== 0),
+          text: typeof output === "string" ? output : JSON.stringify(output),
+        },
+        Date.now(),
+      ),
+    };
+  }
+  if (item.type === "web_search" || item.type === "file_change") {
+    const isWebSearch = item.type === "web_search";
+    const content = isWebSearch
+      ? { query: item.query }
+      : { changes: item.changes, status: item.status };
+    let text = JSON.stringify(item.changes ?? []);
+    if (isWebSearch) text = typeof item.query === "string" ? item.query : "";
+    return {
+      tag: "progress",
+      progress: toolResultProgress(
+        0,
+        {
+          name: item.type,
+          toolUseId: id,
+          content,
+          isError: item.status === "failed",
+          text,
+        },
+        Date.now(),
+      ),
+    };
+  }
+  return null;
+};
+
+const itemProgress = (
+  item: Record<string, unknown>,
+  phase: "started" | "completed",
+): ParsedDriverEvent | null => {
+  const id = typeof item.id === "string" ? item.id : `${String(item.type)}-${Date.now()}`;
+  return phase === "started" ? startedItemProgress(item, id) : completedItemProgress(item, id);
+};
+
+const makeParseEvent = (config: CodexDriverConfig, cliVersion?: string) => {
+  let threadId: string | undefined;
+  return (line: string): ParsedDriverEvent | ParsedDriverEvent[] | null => {
+    let event: Record<string, unknown>;
+    try {
+      event = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+    if (event.type === "thread.started") {
+      threadId = typeof event.thread_id === "string" ? event.thread_id : undefined;
+      return {
+        tag: "ready",
+        ready: {
+          agentId: "codex",
+          model: config.model,
+          detail: { ...(threadId ? { threadId } : {}), ...(cliVersion ? { cliVersion } : {}) },
+        },
+      };
+    }
+    if (event.type === "item.started" || event.type === "item.completed") {
+      if (!event.item || typeof event.item !== "object") return null;
+      return itemProgress(
+        event.item as Record<string, unknown>,
+        event.type === "item.started" ? "started" : "completed",
+      );
+    }
+    if (event.type === "turn.completed") {
+      const usage = parseUsage(event.usage);
+      const events: ParsedDriverEvent[] = [];
+      if (usage) {
+        events.push({
+          tag: "progress",
+          progress: {
+            id: `usage-${threadId ?? Date.now()}`,
+            kind: "usage",
+            payload: usage,
+            ts: Date.now(),
+          },
+        });
+      }
+      events.push({
+        tag: "done",
+        done: { exitReason: "done", summary: { threadId, ...(usage ? { usage } : {}) } },
+      });
+      return events;
+    }
+    if (event.type === "turn.failed" || event.type === "error") {
+      const nestedMessage =
+        event.error && typeof event.error === "object"
+          ? (event.error as Record<string, unknown>).message
+          : undefined;
+      let message = "codex reported an error";
+      if (typeof event.message === "string") message = event.message;
+      else if (typeof event.error === "string") message = event.error;
+      else if (typeof nestedMessage === "string") message = nestedMessage;
+      return { tag: "error", error: { exitReason: "error", reason: message } };
+    }
+    return null;
+  };
+};
+
+class CodexAppServerDriverImpl implements AgentDriver {
+  private readonly emitter = new TypedEmitter<DriverEventMap>();
+  private readonly config: CodexDriverConfig;
+  private process: ReturnType<typeof spawnManagedProcess> | null = null;
+  private collectDir: string | null = null;
+  private artifactsDir: string | null = null;
+  private runDir: string | null = null;
+  private isolatedWorkspace: string | null = null;
+  private isolatedStateDir: string | null = null;
+  private threadId: string | null = null;
+  private cliVersion: string | undefined;
+  private nextRequestId = 1;
+  private readonly responses = new Map<
+    RpcId,
+    { resolve: (result: RpcRecord) => void; reject: (error: Error) => void }
+  >();
+  private readonly interrupts = new Map<string, { id: RpcId; method: string; params: RpcRecord }>();
+  private readonly subagentParents = new Map<string, string>();
+  private readonly turnFacets = new Map<string, AppTurnFacets>();
+  private interruptCount = 0;
+  private idleTimer: NodeJS.Timeout | null = null;
+  private turnActive = false;
+  private terminal = false;
+  private startReady:
+    | { resolve: (ready: ReadyState) => void; reject: (error: Error) => void }
+    | undefined;
+  private dispatchChain: Promise<void> = Promise.resolve();
+  private latestUsage: TokenUsage | null = null;
+
+  constructor(config: CodexDriverConfig) {
+    this.config = config;
+  }
+
+  on<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    this.emitter.on(event, handler);
+  }
+
+  off<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    this.emitter.off(event, handler);
+  }
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    if (this.process) throw new Error("codex driver: start called more than once");
+    let cwd =
+      this.config.cwd ?? (this.config.cwdMode === "artifacts" ? ctx.artifactsDir : ctx.runDir);
+    let env = this.config.env;
+    if (this.config.isolation) {
+      const workspace = await realpath(temporaryDirectory({ prefix: "lux-codex-workspace-" }));
+      await cp(ctx.artifactsDir, workspace, { recursive: true });
+      this.isolatedWorkspace = workspace;
+      cwd = workspace;
+    }
+    if (this.config.isolation || this.config.ignoreUserConfig) {
+      const stateDir = await realpath(temporaryDirectory({ prefix: "lux-codex-state-" }));
+      this.isolatedStateDir = stateDir;
+      const sourceHome =
+        this.config.env?.CODEX_HOME ?? process.env.CODEX_HOME ?? join(homedir(), ".codex");
+      try {
+        const resolvedSourceHome = await realpath(sourceHome);
+        await copyRegularFileNoFollow(
+          resolvedSourceHome,
+          join(resolvedSourceHome, "auth.json"),
+          join(stateDir, "auth.json"),
+        );
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      env = {
+        ...this.config.env,
+        CODEX_HOME: stateDir,
+        CODEX_CONFIG_HOME: stateDir,
+      };
+    }
+    this.collectDir = cwd;
+    this.artifactsDir = ctx.artifactsDir;
+    this.runDir = ctx.runDir;
+    const ready = new Promise<ReadyState>((resolve, reject) => {
+      this.startReady = { resolve, reject };
+    });
+    this.cliVersion =
+      commandName(this.config.command) === "codex"
+        ? await discoverCliVersion(this.config.command)
+        : undefined;
+    const managed = spawnManagedProcess(this.config.command, buildAppServerArgs(this.config), {
+      cwd,
+      env: {
+        ...process.env,
+        LUX_RUN_DIR: ctx.runDir,
+        LUX_ARTIFACTS_DIR: ctx.artifactsDir,
+        ...env,
+      },
+      signal: ctx.abortSignal,
+    });
+    this.process = managed;
+    managed.child.stderr.setEncoding("utf8");
+    let stderrTail = "";
+    managed.child.stderr.on("data", (chunk: string) => {
+      const lines = (stderrTail + chunk).split("\n");
+      stderrTail = (lines.pop() ?? "").slice(0, 8_192);
+      for (const line of lines) process.stderr.write(`[codex] ${line}\n`);
+    });
+    managed.child.stderr.on("close", () => {
+      if (stderrTail) process.stderr.write(`[codex] ${stderrTail}\n`);
+      stderrTail = "";
+    });
+    let lineBytes = 0;
+    managed.child.stdout.on("data", (chunk: Buffer) => {
+      const lastNewline = chunk.lastIndexOf(0x0a);
+      lineBytes = lastNewline === -1 ? lineBytes + chunk.length : chunk.length - lastNewline - 1;
+      if (lineBytes > this.config.maxLineBytes) {
+        this.fail(`stdout line exceeded ${this.config.maxLineBytes} bytes`);
+      }
+    });
+    const lines = createInterface({ input: managed.child.stdout });
+    lines.on("line", (line) => this.handleLine(line));
+    void managed.exited.then(({ exitCode, signal }) => {
+      lines.close();
+      if (!this.terminal) {
+        this.fail(`codex app-server exited before completion (code=${exitCode}, signal=${signal})`);
+      }
+    });
+    try {
+      await managed.spawned;
+    } catch (error) {
+      this.fail(messageOf(error));
+      return ready;
+    }
+    void this.initialize(ctx.prompt, cwd).catch((error: unknown) => this.fail(messageOf(error)));
+    return ready;
+  }
+
+  private async initialize(prompt: string, cwd: string): Promise<void> {
+    await this.request("initialize", {
+      clientInfo: { name: "lux", title: "Lux", version: "1" },
+      capabilities: { experimentalApi: true, requestAttestation: false },
+    });
+    this.notify("initialized");
+    const isolationReads = this.config.isolation
+      ? await Promise.all(this.config.isolation.allowRead.map((path) => realpath(path)))
+      : [];
+    const threadConfig: Record<string, CodexConfigValue> = {
+      ...(this.config.config ?? {}),
+      model_reasoning_effort: this.config.reasoningEffort,
+      ...(this.config.isolation
+        ? {
+            project_doc_max_bytes: 0,
+            projects: { [cwd]: { trust_level: "untrusted" } },
+            permissions: {
+              "lux-isolated": {
+                filesystem: {
+                  ":minimal": "read",
+                  ":workspace_roots": { ".": "write" },
+                  ...Object.fromEntries(isolationReads.map((path) => [path, "read"])),
+                },
+                network: { enabled: true },
+              },
+            },
+          }
+        : {}),
+    };
+    const started = await this.request("thread/start", {
+      model: this.config.model,
+      cwd,
+      runtimeWorkspaceRoots: this.config.addDirs ?? [],
+      approvalPolicy: this.config.approvalPolicy,
+      approvalsReviewer: "user",
+      ...(this.config.isolation
+        ? { permissions: "lux-isolated" }
+        : { sandbox: this.config.sandbox }),
+      config: threadConfig,
+      ephemeral: this.config.ephemeral,
+    });
+    const thread = asRecord(started.thread);
+    if (!thread || typeof thread.id !== "string") {
+      throw new Error("codex app-server returned an invalid thread/start response");
+    }
+    this.threadId = thread.id;
+    const ready: ReadyState = {
+      agentId: "codex",
+      model: typeof started.model === "string" ? started.model : this.config.model,
+      detail: {
+        threadId: thread.id,
+        ...(typeof thread.sessionId === "string" ? { sessionId: thread.sessionId } : {}),
+        ...(this.cliVersion ? { cliVersion: this.cliVersion } : {}),
+      },
+    };
+    this.startReady?.resolve(ready);
+    this.startReady = undefined;
+    this.turnActive = true;
+    this.bumpIdleTimer();
+    await this.request("turn/start", {
+      threadId: thread.id,
+      input: [{ type: "text", text: prompt, text_elements: [] }],
+      effort: this.config.reasoningEffort,
+    });
+    if (this.turnActive && this.interrupts.size === 0) this.bumpIdleTimer();
+  }
+
+  async respond(answer: Answer): Promise<void> {
+    const pending = this.interrupts.get(answer.id);
+    if (!pending) throw new Error(`codex driver: no pending interrupt '${answer.id}'`);
+    this.interrupts.delete(answer.id);
+    let result: unknown;
+    if (pending.method === "item/tool/requestUserInput") {
+      if (answer.kind !== "ask") throw new Error(`codex driver: '${answer.id}' requires an answer`);
+      const questions = Array.isArray(pending.params.questions) ? pending.params.questions : [];
+      let supplied: Record<string, unknown> = {};
+      try {
+        const parsed = JSON.parse(answer.text);
+        if (asRecord(parsed)) supplied = asRecord(parsed) ?? {};
+      } catch {
+        // A plain answer applies to every question, matching the persona answerer contract.
+      }
+      result = {
+        answers: Object.fromEntries(
+          questions.flatMap((question) => {
+            const value = asRecord(question);
+            if (!value || typeof value.id !== "string") return [];
+            const selected = supplied[value.id] ?? supplied[String(value.question)] ?? answer.text;
+            return [
+              [
+                value.id,
+                { answers: Array.isArray(selected) ? selected.map(String) : [String(selected)] },
+              ],
+            ];
+          }),
+        ),
+      };
+    } else if (
+      pending.method === "item/commandExecution/requestApproval" ||
+      pending.method === "item/fileChange/requestApproval"
+    ) {
+      if (answer.kind !== "approve") {
+        throw new Error(`codex driver: '${answer.id}' requires an approval decision`);
+      }
+      result = { decision: answer.approved ? "accept" : "decline" };
+    } else if (pending.method === "item/permissions/requestApproval") {
+      if (answer.kind !== "approve") {
+        throw new Error(`codex driver: '${answer.id}' requires an approval decision`);
+      }
+      result = {
+        permissions: answer.approved ? (pending.params.permissions ?? {}) : {},
+        scope: "turn",
+      };
+    } else if (pending.method === "mcpServer/elicitation/request" && answer.kind === "ask") {
+      let content: unknown = answer.text;
+      try {
+        content = JSON.parse(answer.text);
+      } catch {
+        // Plain text is valid content for open-ended elicitations.
+      }
+      result = { action: "accept", content, _meta: null };
+    } else {
+      result = answer.kind === "custom" ? answer.payload : answer;
+    }
+    this.write({ id: pending.id, result });
+    if (this.interrupts.size === 0) this.bumpIdleTimer();
+  }
+
+  async collect(): Promise<Artifact[]> {
+    if (!this.collectDir) return [];
+    await this.quiesce();
+    const artifacts = await walkArtifacts(this.collectDir);
+    if (this.isolatedWorkspace && this.artifactsDir) {
+      await rm(this.artifactsDir, { recursive: true, force: true });
+      await mkdir(this.artifactsDir, { recursive: true });
+      await Promise.all(
+        artifacts.map(async (artifact) => {
+          const target = join(this.artifactsDir as string, artifact.path);
+          await mkdir(dirname(target), { recursive: true });
+          await copyRegularFileNoFollow(
+            this.isolatedWorkspace as string,
+            join(this.isolatedWorkspace as string, artifact.path),
+            target,
+          );
+        }),
+      );
+      return artifacts;
+    }
+    if (this.collectDir === this.artifactsDir) return artifacts;
+    const root = this.collectDir;
+    const withRoot = artifacts.map((artifact) => ({ ...artifact, root }));
+    return root === this.runDir
+      ? withRoot.filter((artifact) => !LUX_BOOKKEEPING_FILES.has(artifact.path))
+      : withRoot;
+  }
+
+  async quiesce(): Promise<void> {
+    this.clearIdleTimer();
+    await this.process?.terminate();
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.quiesce();
+      this.emitter.removeAllListeners();
+    } finally {
+      await Promise.all([
+        ...(this.isolatedWorkspace
+          ? [rm(this.isolatedWorkspace, { recursive: true, force: true })]
+          : []),
+        ...(this.isolatedStateDir
+          ? [rm(this.isolatedStateDir, { recursive: true, force: true })]
+          : []),
+      ]);
+      this.isolatedWorkspace = null;
+      this.isolatedStateDir = null;
+    }
+  }
+
+  private request(method: string, params: RpcRecord): Promise<RpcRecord> {
+    const id = this.nextRequestId++;
+    const response = new Promise<RpcRecord>((resolve, reject) => {
+      this.responses.set(id, { resolve, reject });
+    });
+    this.write({ method, id, params });
+    return response;
+  }
+
+  private notify(method: string, params?: RpcRecord): void {
+    this.write({ method, ...(params ? { params } : {}) });
+  }
+
+  private write(message: RpcRecord): void {
+    const stdin = this.process?.child.stdin;
+    if (!stdin || stdin.destroyed) throw new Error("codex app-server is not running");
+    stdin.write(`${JSON.stringify(message)}\n`);
+  }
+
+  private handleLine(line: string): void {
+    if (this.terminal || !line.trim()) return;
+    if (Buffer.byteLength(line) > this.config.maxLineBytes) {
+      this.fail(`stdout line exceeded ${this.config.maxLineBytes} bytes`);
+      return;
+    }
+    let message: RpcRecord;
+    try {
+      message = JSON.parse(line) as RpcRecord;
+    } catch {
+      return;
+    }
+    if (this.turnActive && this.interrupts.size === 0) this.bumpIdleTimer();
+    if (message.id !== undefined && !message.method) {
+      const pending = this.responses.get(message.id as RpcId);
+      if (!pending) return;
+      this.responses.delete(message.id as RpcId);
+      const error = asRecord(message.error);
+      if (error) {
+        pending.reject(new Error(typeof error.message === "string" ? error.message : "RPC failed"));
+      } else {
+        pending.resolve(asRecord(message.result) ?? {});
+      }
+      return;
+    }
+    this.dispatchChain = this.dispatchChain
+      .then(() => this.dispatch(message))
+      .catch((error: unknown) => this.fail(messageOf(error)));
+  }
+
+  private async dispatch(message: RpcRecord): Promise<void> {
+    const method = typeof message.method === "string" ? message.method : "";
+    const params = asRecord(message.params) ?? {};
+    if (message.id !== undefined && method) {
+      await this.dispatchServerRequest(message.id as RpcId, method, params);
+      return;
+    }
+    if (method === "item/started" || method === "item/completed") {
+      await this.handleItemNotification(method, params);
+      return;
+    }
+    if (method === "thread/tokenUsage/updated") {
+      this.handleTokenUsageNotification(params);
+      return;
+    }
+    if (method === "turn/completed") {
+      await this.handleTurnCompleted(params);
+      return;
+    }
+    if (method === "error") this.handleErrorNotification(params);
+  }
+
+  private async handleItemNotification(
+    method: "item/started" | "item/completed",
+    params: RpcRecord,
+  ): Promise<void> {
+    const item = asRecord(params.item);
+    const turnId = typeof params.turnId === "string" ? params.turnId : "";
+    const facets = this.turnFacets.get(turnId) ?? {
+      tools: [],
+      asked: false,
+      thought: false,
+    };
+    if (item?.type === "reasoning") facets.thought = true;
+    if (
+      item?.type === "agentMessage" &&
+      typeof item.text === "string" &&
+      facets.text === undefined
+    ) {
+      facets.text = item.text;
+    }
+    const toolName = item ? appItemToolName(item) : null;
+    if (toolName && !facets.tools.includes(toolName)) facets.tools.push(toolName);
+    if (turnId) this.turnFacets.set(turnId, facets);
+    this.recordSubagentParents(item);
+    const parentToolUseId =
+      typeof params.threadId === "string" ? this.subagentParents.get(params.threadId) : undefined;
+    const event = item
+      ? appItemProgress(item, method === "item/started" ? "started" : "completed", parentToolUseId)
+      : null;
+    if (event?.tag === "progress") await this.emitter.emit("progress", event.progress);
+  }
+
+  private recordSubagentParents(item: RpcRecord | null): void {
+    if (item?.type !== "collabAgentToolCall" || typeof item.id !== "string") return;
+    const receiverThreadIds = Array.isArray(item.receiverThreadIds)
+      ? item.receiverThreadIds.filter((value): value is string => typeof value === "string")
+      : [];
+    for (const receiverThreadId of receiverThreadIds) {
+      this.subagentParents.set(receiverThreadId, item.id);
+    }
+  }
+
+  private handleTokenUsageNotification(params: RpcRecord): void {
+    const tokenUsage = asRecord(params.tokenUsage);
+    const usage = appUsage(tokenUsage?.last);
+    if (usage) this.latestUsage = usage;
+  }
+
+  private async handleTurnCompleted(params: RpcRecord): Promise<void> {
+    const turn = asRecord(params.turn);
+    if (
+      turn?.status !== "failed" &&
+      turn?.status !== "interrupted" &&
+      turn?.status !== "completed"
+    ) {
+      this.fail("codex returned an invalid turn/completed notification");
+      return;
+    }
+    const turnId = typeof turn?.id === "string" ? turn.id : String(Date.now());
+    const completedUsage = this.latestUsage;
+    if (completedUsage) {
+      const label = appTurnLabel(this.turnFacets.get(turnId));
+      await this.emitter.emit("progress", {
+        id: `usage-${turnId}`,
+        kind: "usage",
+        payload: { ...completedUsage, ...(label ? { label } : {}) },
+        ts: Date.now(),
+      });
+    }
+    this.terminal = true;
+    this.clearIdleTimer();
+    if (turn?.status === "failed") {
+      const error = asRecord(turn.error);
+      await this.emitter.emit("error", {
+        exitReason: "error",
+        reason: typeof error?.message === "string" ? error.message : "codex turn failed",
+      });
+    } else if (turn?.status === "interrupted") {
+      await this.emitter.emit("error", {
+        exitReason: "error",
+        reason: "codex turn was interrupted",
+      });
+    } else if (turn?.status === "completed") {
+      await this.emitter.emit("done", {
+        exitReason: "done",
+        summary: {
+          threadId: this.threadId,
+          ...(completedUsage ? { usage: completedUsage } : {}),
+          ...(typeof turn.durationMs === "number" ? { durationMs: turn.durationMs } : {}),
+          numTurns: 1,
+        },
+      });
+    }
+  }
+
+  private handleErrorNotification(params: RpcRecord): void {
+    const error = asRecord(params.error);
+    let errorMessage = "codex app-server reported an error";
+    if (typeof params.message === "string") errorMessage = params.message;
+    else if (typeof error?.message === "string") errorMessage = error.message;
+    this.fail(errorMessage);
+  }
+
+  private async dispatchServerRequest(id: RpcId, method: string, params: RpcRecord): Promise<void> {
+    if (
+      method !== "item/tool/requestUserInput" &&
+      method !== "item/commandExecution/requestApproval" &&
+      method !== "item/fileChange/requestApproval" &&
+      method !== "item/permissions/requestApproval" &&
+      method !== "mcpServer/elicitation/request" &&
+      method !== "item/tool/call"
+    ) {
+      this.write({ id, error: { code: -32601, message: `unsupported server request: ${method}` } });
+      return;
+    }
+    this.interruptCount++;
+    if (this.interruptCount > this.config.maxInterrupts) {
+      this.write({ id, error: { code: -32000, message: "interaction limit exceeded" } });
+      this.fail(`exceeded maxInterrupts (${this.config.maxInterrupts})`, "max-interactions");
+      return;
+    }
+    const itemId = typeof params.itemId === "string" ? params.itemId : String(id);
+    const interruptId = `${itemId}:${String(id)}`;
+    this.interrupts.set(interruptId, { id, method, params });
+    this.clearIdleTimer();
+    if (typeof params.turnId === "string") {
+      const facets = this.turnFacets.get(params.turnId) ?? {
+        tools: [],
+        asked: false,
+        thought: false,
+      };
+      facets.asked = true;
+      this.turnFacets.set(params.turnId, facets);
+    }
+    if (method === "item/tool/requestUserInput") {
+      const questions = Array.isArray(params.questions) ? params.questions : [];
+      const question = questions
+        .map((entry) => asRecord(entry)?.question)
+        .filter((entry): entry is string => typeof entry === "string")
+        .join("\n");
+      await this.emitter.emit("interrupt", {
+        kind: "ask",
+        id: interruptId,
+        question: question || "Codex requested user input",
+        context: { questions, autoResolutionMs: params.autoResolutionMs },
+      });
+      return;
+    }
+    if (method === "mcpServer/elicitation/request") {
+      await this.emitter.emit("interrupt", {
+        kind: "ask",
+        id: interruptId,
+        question:
+          typeof params.message === "string" ? params.message : "An MCP server requested input",
+        context: params,
+      });
+      return;
+    }
+    if (method === "item/tool/call") {
+      await this.emitter.emit("interrupt", {
+        kind: "custom",
+        id: interruptId,
+        payload: params,
+        context: { method },
+      });
+      return;
+    }
+    let request =
+      method === "item/fileChange/requestApproval"
+        ? "Approve the requested file changes?"
+        : "Approve the requested command?";
+    if (typeof params.reason === "string") request = params.reason;
+    else if (typeof params.command === "string") request = params.command;
+    await this.emitter.emit("interrupt", {
+      kind: "approve",
+      id: interruptId,
+      request,
+      context: params,
+    });
+  }
+
+  private fail(
+    reason: string,
+    exitReason: "error" | "idle-timeout" | "max-interactions" = "error",
+  ): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    this.clearIdleTimer();
+    for (const pending of this.responses.values()) pending.reject(new Error(reason));
+    this.responses.clear();
+    if (this.startReady) {
+      this.startReady.reject(new Error(reason));
+      this.startReady = undefined;
+    } else {
+      void this.emitter.emit("error", { exitReason, reason });
+    }
+    void this.process?.terminate();
+  }
+
+  private bumpIdleTimer(): void {
+    this.clearIdleTimer();
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      if (this.interrupts.size > 0) return;
+      this.fail(`no event for ${this.config.idleTimeoutMs}ms`, "idle-timeout");
+    }, this.config.idleTimeoutMs);
+  }
+
+  private clearIdleTimer(): void {
+    if (!this.idleTimer) return;
+    clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+}
+
+class CodexExecDriverImpl implements AgentDriver {
+  private inner: AgentDriver | null = null;
+  private pendingAttach: Array<{
+    event: keyof DriverEventMap;
+    handler: unknown;
+    attach: (inner: AgentDriver) => void;
+  }> = [];
+  private collectDir: string | null = null;
+  private artifactsDir: string | null = null;
+  private runDir: string | null = null;
+  private readonly config: CodexDriverConfig;
+
+  constructor(config: CodexDriverConfig) {
+    this.config = config;
+  }
+
+  on<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    if (!this.inner) {
+      this.pendingAttach.push({ event, handler, attach: (inner) => inner.on(event, handler) });
+      return;
+    }
+    this.inner.on(event, handler);
+  }
+
+  off<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    if (!this.inner) {
+      this.pendingAttach = this.pendingAttach.filter(
+        (queued) => queued.event !== event || queued.handler !== handler,
+      );
+      return;
+    }
+    this.inner.off(event, handler);
+  }
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    const cwd =
+      this.config.cwd ?? (this.config.cwdMode === "artifacts" ? ctx.artifactsDir : ctx.runDir);
+    this.collectDir = cwd;
+    this.artifactsDir = ctx.artifactsDir;
+    this.runDir = ctx.runDir;
+    const cliVersion =
+      commandName(this.config.command) === "codex"
+        ? await discoverCliVersion(this.config.command)
+        : undefined;
+    const inner = await subprocessDriver.create({
+      command: this.config.command,
+      args: buildArgs(this.config),
+      cwd,
+      env: this.config.env,
+      protocol: "custom",
+      parseEvent: makeParseEvent(this.config, cliVersion),
+      formatPrompt: (prompt) => prompt,
+      closeStdinAfterPrompt: true,
+      idleTimeoutMs: this.config.idleTimeoutMs,
+      maxLineBytes: this.config.maxLineBytes,
+      maxInterrupts: 1,
+    });
+    for (const queued of this.pendingAttach) queued.attach(inner);
+    this.pendingAttach = [];
+    this.inner = inner;
+    return inner.start(ctx);
+  }
+
+  async respond(_answer: Answer): Promise<void> {
+    throw new Error("codex driver does not support mid-run responses in non-interactive mode");
+  }
+
+  async collect(): Promise<Artifact[]> {
+    if (!this.collectDir) return [];
+    await this.inner?.close();
+    const artifacts = await walkArtifacts(this.collectDir);
+    if (this.collectDir === this.artifactsDir) return artifacts;
+    const root = this.collectDir;
+    const withRoot = artifacts.map((artifact) => ({ ...artifact, root }));
+    return root === this.runDir
+      ? withRoot.filter((artifact) => !LUX_BOOKKEEPING_FILES.has(artifact.path))
+      : withRoot;
+  }
+
+  async quiesce(): Promise<void> {
+    await this.inner?.close();
+  }
+
+  async close(): Promise<void> {
+    await this.inner?.close();
+  }
+}
+
+export const codexDriver: DriverPlugin<CodexDriverConfig> = {
+  name: "codex",
+  configSchema: CodexDriverConfigSchema,
+  create: (config) =>
+    config.interactionMode === "app-server"
+      ? new CodexAppServerDriverImpl(config)
+      : new CodexExecDriverImpl(config),
+};
+
+export type { CodexDriverConfig };
+export { appItemProgress, buildAppServerArgs, buildArgs, CodexDriverConfigSchema, makeParseEvent };