@prismatic-io/lux 0.0.2-preview.14 → 0.0.2-preview.16

package/src/drivers/codex/index.ts

@@ -3,23 +3,22 @@ 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,
+  defineDriver,
   discoverCliVersion,
-  type ParsedDriverEvent,
   type ReadyState,
   type StartContext,
   spawnManagedProcess,
   type TokenUsage,
   TypedEmitter,
-  toolResultProgress,
 } from "../../core/index.js";
 import { walkArtifacts } from "../shared/artifacts.js";
+import { configuredClaudeSourceHashes } from "../shared/experiment-behavior.js";
+import { prepareCodexExperimentConfig } from "../shared/experiment-policy.js";
 import { copyRegularFileNoFollow } from "../shared/secure-copy.js";
 import { subprocessDriver } from "../subprocess/index.js";
 import {
@@ -43,264 +42,11 @@ import {
   CodexDriverConfigSchema,
 } from "./config.js";
 
+import { makeParseEvent } from "./exec-events.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;
@@ -661,6 +407,7 @@ class CodexAppServerDriverImpl implements AgentDriver {
   }
 
   private async dispatch(message: RpcRecord): Promise<void> {
+    if (this.terminal) return;
     const method = typeof message.method === "string" ? message.method : "";
     const params = asRecord(message.params) ?? {};
     if (message.id !== undefined && method) {
@@ -671,6 +418,14 @@ class CodexAppServerDriverImpl implements AgentDriver {
       await this.handleItemNotification(method, params);
       return;
     }
+    if (
+      (method === "thread/tokenUsage/updated" ||
+        method === "turn/completed" ||
+        method === "error") &&
+      typeof params.threadId === "string" &&
+      params.threadId !== this.threadId
+    )
+      return;
     if (method === "thread/tokenUsage/updated") {
       this.handleTokenUsageNotification(params);
       return;
@@ -725,7 +480,7 @@ class CodexAppServerDriverImpl implements AgentDriver {
 
   private handleTokenUsageNotification(params: RpcRecord): void {
     const tokenUsage = asRecord(params.tokenUsage);
-    const usage = appUsage(tokenUsage?.last);
+    const usage = appUsage(tokenUsage?.total) ?? appUsage(tokenUsage?.last);
     if (usage) this.latestUsage = usage;
   }
 
@@ -777,6 +532,7 @@ class CodexAppServerDriverImpl implements AgentDriver {
   }
 
   private handleErrorNotification(params: RpcRecord): void {
+    if (params.willRetry === true) return;
     const error = asRecord(params.error);
     let errorMessage = "codex app-server reported an error";
     if (typeof params.message === "string") errorMessage = params.message;
@@ -984,14 +740,33 @@ class CodexExecDriverImpl implements AgentDriver {
   }
 }
 
-export const codexDriver: DriverPlugin<CodexDriverConfig> = {
+export const codexDriver = defineDriver({
   name: "codex",
   configSchema: CodexDriverConfigSchema,
+  runtime: (config) => ({
+    commands: [config.command],
+    capabilities: {
+      interactive: config.interactionMode === "app-server",
+      "tool-calls": true,
+      "tool-results": true,
+      artifacts: true,
+      subagents: config.interactionMode === "app-server",
+      usage: true,
+      cost: false,
+      isolation: Boolean(config.isolation),
+    },
+  }),
+  experiment: {
+    version: "1",
+    prepare: prepareCodexExperimentConfig,
+    identity: (config, { rootDir }) =>
+      configuredClaudeSourceHashes({ name: "codex", config }, rootDir),
+  },
   create: (config) =>
     config.interactionMode === "app-server"
       ? new CodexAppServerDriverImpl(config)
       : new CodexExecDriverImpl(config),
-};
+});
 
 export type { CodexDriverConfig };
 export { appItemProgress, buildAppServerArgs, buildArgs, CodexDriverConfigSchema, makeParseEvent };

package/src/drivers/cursor/README.md

@@ -0,0 +1,57 @@
+# Cursor driver
+
+The `cursor` driver uses Cursor CLI's ACP transport. Install Cursor CLI and
+authenticate it before running Lux. The executable is normally named `agent`;
+set `command` to its absolute path if another application owns that name.
+
+```ts
+{
+  name: "cursor",
+  config: {
+    command: "/absolute/path/to/cursor/agent",
+    model: "YOUR_CURSOR_MODEL_ID",
+    // Optional: only accepted when ACP advertises this effort value.
+    // reasoningEffort: "low",
+  },
+}
+```
+
+`model` is required. Use an explicit model ID from your installed Cursor CLI;
+some IDs encode reasoning effort. Lux passes that ID through `--model` and
+rejects a different model when the session reports one. If `reasoningEffort` is
+supplied, Lux requires a matching advertised ACP thought-level selector and
+checks the response confirms the requested value before sending the prompt.
+
+Supported interactions are Cursor's native multiple-choice questions, plan
+approval, and ACP tool permissions. Lux grants one-operation permissions only;
+it never converts an approval into a remembered permission. Multi-question
+answers use a JSON mapping from question IDs to option IDs, with arrays for
+multiple selections. The generated question prompt explains this format.
+
+The driver normalizes streamed text, reasoning and tool calls/results. Other
+session updates and Cursor notifications remain available as `cursor-update`
+and `cursor-event` progress. Tool names use ACP's supplied title; assertions
+based on tool names may therefore need harness-specific selectors.
+
+The default working directory is the run's staged artifacts directory. `cwd`
+can select another existing workspace. Neither setting provides a security
+sandbox or ambient-configuration isolation. Cursor can inherit its user and
+project rules, hooks, MCP servers, credentials and persisted state. The driver
+does not claim controlled-experiment support or complete usage/cost accounting;
+usage availability is recorded as unknown, not a zero-token observation.
+
+Startup RPCs, idle periods, protocol lines, queued events and retained tool state
+are bounded. On close, Lux attempts ACP cancellation, then terminates the
+managed process tree before collecting artifacts. Aborting a run also terminates
+the managed tree. Unsupported client filesystem/terminal operations are not
+advertised and unsupported requests receive a JSON-RPC error.
+
+The adapter is covered by synthetic protocol and lifecycle tests. Its initial
+implementation has not been validated against an authenticated Cursor session.
+
+Protocol references:
+
+- [Cursor ACP](https://cursor.com/docs/cli/acp)
+- [Cursor CLI parameters](https://cursor.com/docs/cli/reference/parameters)
+- [ACP configuration options](https://agentclientprotocol.com/protocol/session-config-options)
+- [ACP tool calls and permissions](https://agentclientprotocol.com/protocol/tool-calls)

package/src/drivers/cursor/acp-transport.ts

@@ -0,0 +1,182 @@
+import { type ManagedProcess, spawnManagedProcess } from "../../core/index.js";
+
+export type RpcRecord = Record<string, unknown>;
+export type RpcId = number | string;
+export const asRecord = (value: unknown): RpcRecord | undefined =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as RpcRecord)
+    : undefined;
+
+type TransportOptions = {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  signal: AbortSignal;
+  maxLineBytes: number;
+  maxQueuedBytes: number;
+  onMessage: (message: RpcRecord) => Promise<void>;
+  onFailure: (error: Error) => void;
+  onActivity: () => void;
+};
+
+export class AcpTransport {
+  private readonly process: ManagedProcess;
+  private readonly pending = new Map<
+    RpcId,
+    {
+      resolve: (result: RpcRecord) => void;
+      reject: (error: Error) => void;
+      timer: NodeJS.Timeout | undefined;
+    }
+  >();
+  private nextId = 1;
+  private buffer = Buffer.alloc(0);
+  private queuedBytes = 0;
+  private chain: Promise<void> = Promise.resolve();
+  private stopped = false;
+  private stderrTail = "";
+
+  private readonly options: TransportOptions;
+
+  constructor(options: TransportOptions) {
+    this.options = options;
+    this.process = spawnManagedProcess(options.command, options.args, {
+      cwd: options.cwd,
+      ...(options.env ? { env: options.env } : {}),
+      signal: options.signal,
+    });
+    this.process.child.stdout.on("data", (chunk: Buffer) => this.read(chunk));
+    this.process.child.stderr.setEncoding("utf8");
+    this.process.child.stderr.on("data", (chunk: string) => {
+      this.stderrTail = (this.stderrTail + chunk).slice(-8_192);
+    });
+    void this.process.exited.then(({ exitCode, signal }) => {
+      if (!this.stopped)
+        this.fail(
+          new Error(
+            `Cursor ACP exited before completion (code=${exitCode}, signal=${signal})${this.stderrTail ? `: ${this.stderrTail}` : ""}`,
+          ),
+        );
+    });
+  }
+
+  async spawned(): Promise<void> {
+    await this.process.spawned;
+  }
+
+  request(method: string, params: RpcRecord, timeoutMs?: number): Promise<RpcRecord> {
+    if (this.stopped) return Promise.reject(new Error("Cursor ACP is closed"));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer =
+        timeoutMs === undefined
+          ? undefined
+          : setTimeout(() => {
+              this.fail(new Error(`Cursor ACP ${method} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        this.write({ id, method, params });
+      } catch (error) {
+        this.fail(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  write(message: RpcRecord): void {
+    if (this.stopped) throw new Error("Cursor ACP is closed");
+    const line = `${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`;
+    if (Buffer.byteLength(line) > this.options.maxLineBytes)
+      throw new Error("Cursor ACP outgoing message exceeded maxLineBytes");
+    this.process.child.stdin.write(line);
+  }
+
+  async drained(): Promise<void> {
+    await this.chain;
+  }
+
+  async close(): Promise<void> {
+    this.stopped = true;
+    this.rejectPending(new Error("Cursor ACP is closed"));
+    this.buffer = Buffer.alloc(0);
+    await this.process.terminate();
+  }
+
+  private rejectPending(error: Error): void {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  private fail(error: Error): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.rejectPending(error);
+    this.options.onFailure(error);
+    void this.process.terminate();
+  }
+
+  private read(chunk: Buffer): void {
+    let offset = 0;
+    while (offset < chunk.length && !this.stopped) {
+      const newline = chunk.indexOf(0x0a, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      const segment = chunk.subarray(offset, end);
+      if (this.buffer.length + segment.length > this.options.maxLineBytes) {
+        this.fail(new Error("Cursor ACP stdout line exceeded maxLineBytes"));
+        return;
+      }
+      this.buffer = Buffer.concat([this.buffer, segment]);
+      if (newline === -1) return;
+      const line = this.buffer;
+      this.buffer = Buffer.alloc(0);
+      this.line(line);
+      offset = newline + 1;
+    }
+  }
+
+  private line(line: Buffer): void {
+    if (!line.toString("utf8").trim()) return;
+    let message: RpcRecord | undefined;
+    try {
+      message = asRecord(JSON.parse(line.toString("utf8")));
+    } catch {
+      /* Rejected below. */
+    }
+    if (message?.jsonrpc !== "2.0") {
+      this.fail(new Error("Cursor ACP returned an invalid JSON-RPC message"));
+      return;
+    }
+    this.options.onActivity();
+    if (message.method === undefined) {
+      const pending = this.pending.get(message.id as RpcId);
+      if (!pending) return;
+      this.pending.delete(message.id as RpcId);
+      clearTimeout(pending.timer);
+      const error = asRecord(message.error);
+      if (error) pending.reject(new Error(String(error.message ?? "Cursor ACP request failed")));
+      else pending.resolve(asRecord(message.result) ?? {});
+      return;
+    }
+    this.queuedBytes += line.length;
+    if (this.queuedBytes > this.options.maxQueuedBytes) {
+      this.fail(new Error("Cursor ACP pending events exceeded maxQueuedBytes"));
+      return;
+    }
+    const queued = message;
+    this.chain = this.chain
+      .then(async () => {
+        try {
+          if (!this.stopped) await this.options.onMessage(queued);
+        } finally {
+          this.queuedBytes -= line.length;
+        }
+      })
+      .catch((error: unknown) =>
+        this.fail(error instanceof Error ? error : new Error(String(error))),
+      );
+  }
+}

package/src/drivers/cursor/config.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+export const CursorDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("agent"),
+    /** Cursor model IDs may include an effort suffix; never inherit Auto. */
+    model: z.string().min(1),
+    /** Applied only through an advertised ACP thought-level selector. */
+    reasoningEffort: z.string().min(1).optional(),
+    mode: z.enum(["agent", "plan", "ask"]).default("agent"),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    startupTimeoutMs: z.number().int().positive().default(30_000),
+    idleTimeoutMs: z.number().int().positive().default(600_000),
+    maxInterrupts: z.number().int().positive().default(20),
+    maxLineBytes: z.number().int().positive().default(10_000_000),
+    maxQueuedBytes: z.number().int().positive().default(20_000_000),
+    maxToolCalls: z.number().int().positive().default(10_000),
+  })
+  .strict();
+
+export type CursorDriverConfig = z.infer<typeof CursorDriverConfigSchema>;
+
+export const buildCursorArgs = (config: CursorDriverConfig): string[] => [
+  "--model",
+  config.model,
+  ...(config.mode === "agent" ? [] : ["--mode", config.mode]),
+  "acp",
+];