@prismatic-io/lux 0.0.2-preview.4 → 0.0.2-preview.40

package/src/drivers/cursor/index.ts

@@ -0,0 +1,326 @@
+import { realpath } from "node:fs/promises";
+import { agentEnvironment } from "../../core/agent-environment.js";
+import { durationMs } from "../../core/duration.js";
+import {
+  type AgentDriver,
+  type Answer,
+  type Artifact,
+  type DriverEventMap,
+  defineDriver,
+  discoverCliVersion,
+  type ReadyState,
+  type StartContext,
+  selectModelAndReasoningEffort,
+  TypedEmitter,
+} from "../../core/index.js";
+import { AcpEvents } from "../shared/acp-events.js";
+import { permissionRequestText, records } from "../shared/acp-interaction.js";
+import { acpModel, selectAcpModel } from "../shared/acp-session.js";
+import { AcpTransport, asRecord, type RpcId, type RpcRecord } from "../shared/acp-transport.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+import { buildCursorArgs, type CursorDriverConfig, CursorDriverConfigSchema } from "./config.js";
+import { cursorAnswer, cursorQuestionText, effortSelector } from "./interaction.js";
+
+class CursorDriver implements AgentDriver {
+  private readonly emitter = new TypedEmitter<DriverEventMap>();
+  private readonly events: AcpEvents;
+  private transport: AcpTransport | undefined;
+  private sessionId: string | undefined;
+  private cwd: string | undefined;
+  private artifactsDir: string | undefined;
+  private ready = false;
+  private runPromise: Promise<void> | undefined;
+  private terminal = false;
+  private idleTimer: NodeJS.Timeout | undefined;
+  private interruptCount = 0;
+  private readonly interrupts = new Map<string, { id: RpcId; method: string; params: RpcRecord }>();
+
+  private readonly config: CursorDriverConfig;
+
+  constructor(config: CursorDriverConfig) {
+    this.config = config;
+    this.events = new AcpEvents("cursor", config.maxToolCalls, config.maxQueuedBytes);
+  }
+
+  on<K extends keyof DriverEventMap>(
+    event: K,
+    handler: (e: DriverEventMap[K]) => void | Promise<void>,
+  ): void {
+    this.emitter.on(event, handler);
+  }
+  off<K extends keyof DriverEventMap>(
+    event: K,
+    handler: (e: DriverEventMap[K]) => void | Promise<void>,
+  ): void {
+    this.emitter.off(event, handler);
+  }
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    if (this.transport || this.terminal)
+      throw new Error("Cursor driver cannot be started twice or after close");
+    this.cwd = await realpath(this.config.cwd ?? ctx.artifactsDir);
+    this.artifactsDir = await realpath(ctx.artifactsDir);
+    const cliVersion = await discoverCliVersion(this.config.command);
+    const transport = new AcpTransport({
+      label: "Cursor ACP",
+      command: this.config.command,
+      args: buildCursorArgs(this.config),
+      cwd: this.cwd,
+      env: agentEnvironment(process.env, this.config.inheritEnv, this.config.env),
+      signal: ctx.abortSignal,
+      maxLineBytes: this.config.maxLineBytes,
+      maxQueuedBytes: this.config.maxQueuedBytes,
+      onMessage: (message) => this.message(message),
+      onFailure: (error) => this.fail(error),
+      onActivity: () => this.bumpIdleTimer(),
+    });
+    this.transport = transport;
+    try {
+      await transport.spawned();
+      const initialized = await this.request("initialize", {
+        protocolVersion: 1,
+        clientInfo: { name: "lux", version: "1" },
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      });
+      if (initialized.protocolVersion !== 1)
+        throw new Error("Cursor ACP returned an unsupported protocol version");
+      if (!records(initialized.authMethods).some((method) => method.id === "cursor_login")) {
+        throw new Error(
+          "Expected Cursor ACP with cursor_login authentication; check the configured command points to Cursor CLI",
+        );
+      }
+      await this.request("authenticate", { methodId: "cursor_login" });
+      let session = await this.request("session/new", { cwd: this.cwd, mcpServers: [] });
+      if (typeof session.sessionId !== "string") throw new Error("Cursor ACP omitted sessionId");
+      this.sessionId = session.sessionId;
+      session = await selectAcpModel("Cursor", session, this.config.model, (method, params) =>
+        this.request(method, params),
+      );
+      if (this.config.reasoningEffort) {
+        const selection = effortSelector(session, this.config.reasoningEffort);
+        const updated = await this.request("session/set_config_option", {
+          sessionId: this.sessionId,
+          ...selection,
+        });
+        const applied = records(updated.configOptions).find(
+          (option) => option.id === selection.configId,
+        );
+        if (applied?.currentValue !== this.config.reasoningEffort)
+          throw new Error("Cursor ACP did not apply the requested reasoning effort");
+        session = { ...session, ...updated };
+      }
+      const model = acpModel(session);
+      if (typeof model === "string" && model !== this.config.model)
+        throw new Error(
+          `Cursor ACP selected '${model}' instead of requested '${this.config.model}'`,
+        );
+      this.ready = true;
+      this.bumpIdleTimer();
+      this.runPromise = this.run(ctx.prompt).catch((error: unknown) => this.fail(error));
+      return {
+        agentId: "cursor",
+        model: this.config.model,
+        detail: {
+          sessionId: this.sessionId,
+          transport: "acp",
+          protocolVersion: 1,
+          ...(cliVersion ? { cliVersion } : {}),
+          modelResolution: typeof model === "string" ? "reported" : "requested",
+          nativeConfig: session.configOptions ?? [],
+          usageAvailability: "unknown",
+          isolation: "none",
+        },
+      };
+    } catch (error) {
+      await this.close();
+      throw error;
+    }
+  }
+
+  private request(method: string, params: RpcRecord): Promise<RpcRecord> {
+    if (!this.transport) throw new Error("Cursor ACP has not started");
+    return this.transport.request(method, params, durationMs(this.config.startupTimeout));
+  }
+
+  private async run(prompt: string): Promise<void> {
+    const result = await this.transport?.request("session/prompt", {
+      sessionId: this.sessionId,
+      prompt: [{ type: "text", text: prompt }],
+    });
+    await this.transport?.drained();
+    if (this.terminal) return;
+    if (result?.stopReason !== "end_turn")
+      throw new Error(`Cursor stopped with ${String(result?.stopReason ?? "unknown reason")}`);
+    this.terminal = true;
+    clearTimeout(this.idleTimer);
+    await this.emitter.emit("done", {
+      exitReason: "done",
+      summary: {
+        sessionId: this.sessionId,
+        stopReason: result.stopReason,
+        usageAvailability: "unknown",
+      },
+    });
+  }
+
+  private async message(message: RpcRecord): Promise<void> {
+    if (this.terminal) return;
+    const method = String(message.method);
+    const params = asRecord(message.params) ?? {};
+    const id = message.id;
+    if (typeof id === "number" || typeof id === "string") {
+      if (typeof params.sessionId === "string" && params.sessionId !== this.sessionId) {
+        this.transport?.write({ id, error: { code: -32602, message: "Unknown session" } });
+        return;
+      }
+      if (
+        !["session/request_permission", "cursor/ask_question", "cursor/create_plan"].includes(
+          method,
+        )
+      ) {
+        this.transport?.write({
+          id,
+          error: { code: -32601, message: `Unsupported method: ${method}` },
+        });
+        return;
+      }
+      if (++this.interruptCount > this.config.maxInterrupts) {
+        this.transport?.write({ id, result: { outcome: { outcome: "cancelled" } } });
+        this.fail(new Error("Cursor exceeded maxInterrupts"), "max-interactions");
+        return;
+      }
+      const interruptId = `cursor-${id}`;
+      if (this.interrupts.has(interruptId)) throw new Error("Cursor reused a pending request ID");
+      this.interrupts.set(interruptId, { id, method, params });
+      clearTimeout(this.idleTimer);
+      if (method === "cursor/ask_question") {
+        await this.emitter.emit("interrupt", {
+          kind: "ask",
+          id: interruptId,
+          question: cursorQuestionText(params),
+          context: params,
+        });
+      } else {
+        await this.emitter.emit("interrupt", {
+          kind: "approve",
+          id: interruptId,
+          request:
+            method === "cursor/create_plan"
+              ? String(params.plan ?? params.overview ?? "Approve this plan?")
+              : permissionRequestText(params),
+          context: params,
+        });
+      }
+      return;
+    }
+    if (method === "session/update") {
+      if (params.sessionId !== this.sessionId) return;
+      const update = asRecord(params.update);
+      if (update)
+        for (const event of this.events.update(update)) await this.emitter.emit("progress", event);
+    } else if (method.startsWith("cursor/")) {
+      await this.emitter.emit("progress", {
+        id: `cursor-native-${Date.now()}-${method}`,
+        kind: "cursor-event",
+        payload: { method, params },
+        ts: Date.now(),
+      });
+    }
+  }
+
+  async respond(answer: Answer): Promise<void> {
+    const pending = this.interrupts.get(answer.id);
+    if (!pending) throw new Error(`Cursor has no pending interrupt '${answer.id}'`);
+    const result = cursorAnswer(pending.method, pending.params, answer);
+    this.transport?.write({ id: pending.id, result });
+    this.interrupts.delete(answer.id);
+    this.bumpIdleTimer();
+  }
+
+  private bumpIdleTimer(): void {
+    clearTimeout(this.idleTimer);
+    if (!this.ready || this.terminal || this.interrupts.size > 0) return;
+    this.idleTimer = setTimeout(
+      () =>
+        this.fail(
+          new Error(`Cursor emitted no event for ${durationMs(this.config.idleTimeout)}ms`),
+          "idle-timeout",
+        ),
+      durationMs(this.config.idleTimeout),
+    );
+  }
+
+  private fail(error: unknown, exitReason: DriverEventMap["error"]["exitReason"] = "error"): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    clearTimeout(this.idleTimer);
+    if (this.ready)
+      void this.transport?.drained().then(() =>
+        this.emitter.emit("error", {
+          exitReason,
+          reason: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    void this.transport?.close();
+  }
+
+  async quiesce(): Promise<void> {
+    clearTimeout(this.idleTimer);
+    const cancelling = !this.terminal && this.sessionId !== undefined;
+    this.terminal = true;
+    if (cancelling) {
+      for (const pending of this.interrupts.values())
+        this.transport?.write({ id: pending.id, result: { outcome: { outcome: "cancelled" } } });
+      this.transport?.write({ method: "session/cancel", params: { sessionId: this.sessionId } });
+      let timer: NodeJS.Timeout | undefined;
+      try {
+        await Promise.race([
+          this.runPromise,
+          new Promise<void>((resolve) => {
+            timer = setTimeout(resolve, 200);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    this.interrupts.clear();
+    await this.transport?.close();
+  }
+
+  async collect(): Promise<Artifact[]> {
+    await this.quiesce();
+    if (!this.cwd) return [];
+    const artifacts = await walkArtifacts(this.cwd);
+    return this.cwd === this.artifactsDir
+      ? artifacts
+      : artifacts.map((artifact) => ({ ...artifact, root: this.cwd as string }));
+  }
+
+  async close(): Promise<void> {
+    await this.quiesce();
+    this.emitter.removeAllListeners();
+  }
+}
+
+export const cursorDriver = defineDriver({
+  name: "cursor",
+  configSchema: CursorDriverConfigSchema,
+  runtime: (config) => ({
+    commands: [config.command],
+    capabilities: {
+      interactive: true,
+      "tool-calls": true,
+      "tool-results": true,
+      artifacts: true,
+      usage: false,
+      cost: false,
+      isolation: false,
+    },
+  }),
+  selectHarness: selectModelAndReasoningEffort,
+  create: (config) => new CursorDriver(config),
+});
+
+export type { CursorDriverConfig };
+export { buildCursorArgs, CursorDriverConfigSchema };

package/src/drivers/cursor/interaction.ts

@@ -0,0 +1,74 @@
+import type { Answer } from "../../core/index.js";
+import { permissionAnswer, records } from "../shared/acp-interaction.js";
+import { asRecord, type RpcRecord } from "../shared/acp-transport.js";
+
+export const cursorQuestionText = (params: RpcRecord): string =>
+  `Return a JSON object mapping each question ID to its selected option ID. For questions allowing multiple selections, use an array of option IDs.\n\n${records(
+    params.questions,
+  )
+    .map(
+      (question) =>
+        `Question ID: ${String(question.id)}${question.allowMultiple === true ? " (multiple selections allowed)" : " (select one)"}\n${String(question.prompt ?? question.id)}\n${records(
+          question.options,
+        )
+          .map((option) => `${String(option.id)}: ${String(option.label)}`)
+          .join("\n")}`,
+    )
+    .join("\n\n")}`;
+
+export const cursorAnswer = (method: string, params: RpcRecord, answer: Answer): RpcRecord => {
+  if (method === "cursor/ask_question") {
+    if (answer.kind !== "ask") throw new Error("Cursor questions require a text answer");
+    let supplied: RpcRecord = {};
+    try {
+      supplied = asRecord(JSON.parse(answer.text)) ?? {};
+    } catch {
+      /* Plain option IDs and labels are accepted too. */
+    }
+    const answers = records(params.questions).map((question) => {
+      const selection = supplied[String(question.id)] ?? answer.text;
+      const selections = Array.isArray(selection) ? selection : [selection];
+      if (question.allowMultiple !== true && selections.length !== 1)
+        throw new Error("Cursor question requires exactly one selection");
+      const selectedOptionIds = selections.map((value) => {
+        const option = records(question.options).find(
+          (entry) => entry.id === value || entry.label === value,
+        );
+        if (!option || typeof option.id !== "string")
+          throw new Error(`Cursor answer does not match an option for '${String(question.id)}'`);
+        return option.id;
+      });
+      return { questionId: question.id, selectedOptionIds };
+    });
+    return { outcome: { outcome: "answered", answers } };
+  }
+  if (answer.kind !== "approve") throw new Error("Cursor approval requires an approval answer");
+  if (method === "cursor/create_plan") {
+    return {
+      outcome: answer.approved
+        ? { outcome: "accepted" }
+        : { outcome: "rejected", ...(answer.reason ? { reason: answer.reason } : {}) },
+    };
+  }
+  return permissionAnswer(params, answer);
+};
+
+const optionValues = (options: unknown): string[] =>
+  records(options).flatMap((option) =>
+    typeof option.value === "string" ? [option.value] : optionValues(option.options),
+  );
+
+export const effortSelector = (session: RpcRecord, effort: string): RpcRecord => {
+  const option = records(session.configOptions).find(
+    (entry) =>
+      entry.category === "thought_level" ||
+      entry.id === "reasoning_effort" ||
+      entry.id === "effort",
+  );
+  if (!option || typeof option.id !== "string" || !optionValues(option.options).includes(effort)) {
+    throw new Error(
+      `Cursor ACP does not advertise reasoning effort '${effort}'; select an explicit supported model/effort ID or omit reasoningEffort`,
+    );
+  }
+  return { configId: option.id, value: effort };
+};

package/src/drivers/grok-build/README.md

@@ -0,0 +1,112 @@
+# Grok.build driver
+
+The `grok-build` driver runs the native Grok.build CLI over ACP (`grok agent
+--no-leader stdio`). Install Grok.build and run `grok login` first. This is
+separate from selecting a Grok model in the Copilot driver.
+
+```ts
+{
+  defaultDriver: {
+    name: "grok-build",
+    config: {
+      model: "grok-4.5",
+      reasoningEffort: "low",
+      permissionMode: "auto",
+      sandbox: "workspace",
+    },
+  },
+  defaultAnswerer: "persona",
+}
+```
+
+Or scaffold an eval project:
+
+```sh
+lux init --driver grok-build --model grok-4.5
+```
+
+An explicit model is required; effort defaults to `low`. Lux selects both through
+`session/set_config_option` and verifies the returned values before prompting.
+Grok 1.0.40 can choose a different model on `session/new` despite the CLI model
+flag, so passing that flag alone is insufficient.
+
+## Permissions
+
+The default `auto` mode uses Grok's native safety checks, including its LLM
+classifier, to approve routine operations. It is not blanket approval. `default`
+(ask) is also supported. Lux does not expose always-approve, arbitrary extra
+arguments, or the CLI `--allow`/`--deny` flags. In Grok 1.0.40, those rule flags
+are ignored by the agent subcommand. Project permission rules require Grok folder trust. Lux leaves
+`trustProject: false` by default; an untrusted fixture's rules are ignored by
+Grok. Enable `trustProject: true` only for reviewed fixtures: it also permits
+project configuration such as hooks and MCP servers. Then put native rules in
+`.grok/config.toml` and assert the expected denial. CLI `dontAsk` is also omitted because the ACP launch path does not propagate that
+policy.
+
+For example, this native rule denies the smoke test's command:
+
+```toml
+[[permission.rules]]
+action = "deny"
+tool = "bash"
+pattern = "printf *"
+```
+
+Change `action` to `"ask"` to exercise Lux's answerer explicitly. The live
+smoke task opts into trust only for its own generated ask/deny fixtures.
+
+ACP permission requests become Lux `approve` interrupts, including the tool
+call details. The configured answerer handles those requests; `persona` uses an
+LLM with the case's task and persona constraints. Lux selects only `allow_once`
+or `reject_once`, never a remembered grant. The persona parser accepts strict
+approval JSON either bare or in one complete JSON Markdown fence; ambiguous
+text and invalid fields still deny the operation. If the agent offers no matching
+one-operation option, Lux cancels and reports an error rather than widening the
+grant. Native auto decisions are handled inside Grok and are not Lux interrupts.
+
+Permission reviews have a separate `permissionTimeout` (150 seconds by
+default), while ordinary inactivity uses `idleTimeout` (10 minutes). Startup
+RPCs time out after 30 seconds. Cancelled turns, process failures, unanswered
+reviews, and turns ending with pending approvals cannot count as successful runs.
+A completed turn can still contain denied tool calls: assert the expected files
+or tool results to determine whether the task succeeded.
+
+## Scope and limitations
+
+Lux requests the native `workspace` sandbox and a private process with
+`--no-leader`. `read-only` and `strict` profiles are available; disabling the
+sandbox is not a driver option. The workspace profile allows filesystem reads,
+network access, and writes to the working directory, Grok state, and temporary
+directories. It is not configuration isolation: Grok still loads user/project
+settings, compatible Claude settings, hooks, skills, and MCP configuration.
+The driver reports configuration isolation, usage, and cost as unavailable;
+controlled experiments requiring those capabilities remain unsupported.
+
+The interaction surface currently supports tool permissions. Other ACP client
+requests receive an explicit unsupported-method response. Run evidence includes
+agent messages, reasoning, tool calls/results, and collected files. Use artifact
+assertions alongside `run-succeeded`.
+
+## Validation
+
+Synthetic tests cover explicit model/effort selection, one-operation approvals
+and rejections, refusal to substitute remembered grants, permission timeouts,
+process exit during review, cancellation, idle timeout, and cleanup.
+
+Live smoke validation uses Grok.build 1.0.40 with `grok-4.5` at low effort.
+
+The opt-in live smoke task runs three real evals: a local shell write under auto
+review, an explicit ask rule answered by Lux's LLM persona, and an explicit deny
+rule that must produce a failed tool result without creating the file. It
+requires Grok and Claude Code logins and consumes model usage. Evidence stays
+in the temporary directory printed by the task:
+
+```sh
+LUX_GROK_MODEL=grok-4.5 mise run smoke:grok-build
+```
+
+References:
+
+- [Grok ACP guide](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/15-agent-mode.md)
+- [Grok permissions](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/22-permissions-and-safety.md)
+- [Grok sandbox](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/18-sandbox.md)

package/src/drivers/grok-build/config.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { InheritEnvironmentSchema } from "../../core/agent-environment.js";
+import { DurationSchema } from "../../core/duration.js";
+import { applyCatalogEffort, grokBuildCatalog } from "../../core/index.js";
+
+export const GrokBuildDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("grok"),
+    model: z.string().min(1),
+    reasoningEffort: z.enum(grokBuildCatalog.efforts).default("low"),
+    permissionMode: z.enum(["auto", "default"]).default("auto"),
+    trustProject: z.boolean().default(false),
+    sandbox: z.enum(["workspace", "read-only", "strict"]).default("workspace"),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    inheritEnv: InheritEnvironmentSchema.optional(),
+    startupTimeout: DurationSchema.default("30 seconds"),
+    idleTimeout: DurationSchema.default("10 minutes"),
+    permissionTimeout: DurationSchema.default("150 seconds"),
+    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()
+  .transform(applyCatalogEffort(grokBuildCatalog));
+
+export type GrokBuildDriverConfig = z.infer<typeof GrokBuildDriverConfigSchema>;
+
+export const buildGrokBuildArgs = (config: GrokBuildDriverConfig): string[] => [
+  "--permission-mode",
+  config.permissionMode,
+  "--sandbox",
+  config.sandbox,
+  ...(config.trustProject ? ["--trust"] : []),
+  "agent",
+  "--no-leader",
+  "--model",
+  config.model,
+  "--reasoning-effort",
+  config.reasoningEffort,
+  "stdio",
+];