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

package/src/drivers/copilot/config.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { InheritEnvironmentSchema } from "../../core/agent-environment.js";
+import { DurationSchema } from "../../core/duration.js";
+import { applyCatalogEffort, copilotCatalog } from "../../core/index.js";
+
+export const CopilotDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("copilot"),
+    /** Copilot's catalog changes per plan; never inherit its `auto` selection. */
+    model: z.string().min(1),
+    reasoningEffort: z.enum(copilotCatalog.efforts).optional(),
+    mode: z.enum(["agent", "plan", "autopilot"]).default("agent"),
+    /** Permission patterns approved without an interrupt (`--allow-tool`). */
+    allowTools: z.array(z.string().min(1)).optional(),
+    denyTools: z.array(z.string().min(1)).optional(),
+    /** Approve every tool without interrupts; permissions stop being evidence. */
+    allowAllTools: z.boolean().default(false),
+    /** ACP cannot answer ask_user requests; reject configurations that would strand the run. */
+    askUser: z.literal(false).default(false),
+    /** Load AGENTS.md and related instruction files from the workspace. */
+    customInstructions: z.boolean().default(true),
+    /** Enable Copilot's bundled GitHub MCP server. */
+    builtinMcps: z.boolean().default(true),
+    addDirs: z.array(z.string()).optional(),
+    extraArgs: z.array(z.string()).optional(),
+    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"),
+    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(copilotCatalog));
+
+export type CopilotDriverConfig = z.infer<typeof CopilotDriverConfigSchema>;
+
+export const buildCopilotArgs = (config: CopilotDriverConfig): string[] => [
+  "--acp",
+  "--no-auto-update",
+  "--model",
+  config.model,
+  ...(config.reasoningEffort ? ["--effort", config.reasoningEffort] : []),
+  "--no-ask-user",
+  ...(config.customInstructions ? [] : ["--no-custom-instructions"]),
+  ...(config.builtinMcps ? [] : ["--disable-builtin-mcps"]),
+  ...(config.allowAllTools ? ["--allow-all-tools"] : []),
+  ...(config.allowTools ?? []).map((tool) => `--allow-tool=${tool}`),
+  ...(config.denyTools ?? []).map((tool) => `--deny-tool=${tool}`),
+  ...(config.addDirs ?? []).flatMap((dir) => ["--add-dir", dir]),
+  ...(config.extraArgs ?? []),
+];
+
+export const COPILOT_MODE_IDS: Record<CopilotDriverConfig["mode"], string> = {
+  agent: "https://agentclientprotocol.com/protocol/session-modes#agent",
+  plan: "https://agentclientprotocol.com/protocol/session-modes#plan",
+  autopilot: "https://agentclientprotocol.com/protocol/session-modes#autopilot",
+};

package/src/drivers/copilot/index.ts

@@ -0,0 +1,310 @@
+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 { permissionAnswer, 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 {
+  buildCopilotArgs,
+  COPILOT_MODE_IDS,
+  type CopilotDriverConfig,
+  CopilotDriverConfigSchema,
+} from "./config.js";
+
+class CopilotDriver 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 responseText = "";
+  private readonly interrupts = new Map<string, { id: RpcId; params: RpcRecord }>();
+
+  private readonly config: CopilotDriverConfig;
+
+  constructor(config: CopilotDriverConfig) {
+    this.config = config;
+    this.events = new AcpEvents("copilot", 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("Copilot 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: "Copilot ACP",
+      command: this.config.command,
+      args: buildCopilotArgs(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("Copilot ACP returned an unsupported protocol version");
+      if (!records(initialized.authMethods).some((method) => method.id === "copilot-login")) {
+        throw new Error(
+          "Expected Copilot ACP with copilot-login authentication; check the configured command points to GitHub Copilot CLI",
+        );
+      }
+      let session = await this.request("session/new", { cwd: this.cwd, mcpServers: [] });
+      if (typeof session.sessionId !== "string") throw new Error("Copilot ACP omitted sessionId");
+      this.sessionId = session.sessionId;
+      session = await selectAcpModel("Copilot", session, this.config.model, (method, params) =>
+        this.request(method, params),
+      );
+      const modeId = COPILOT_MODE_IDS[this.config.mode];
+      const currentModeId = asRecord(session.modes)?.currentModeId;
+      if (currentModeId !== modeId) {
+        if (!records(asRecord(session.modes)?.availableModes).some((mode) => mode.id === modeId))
+          throw new Error(`Copilot ACP does not advertise the '${this.config.mode}' mode`);
+        await this.request("session/set_mode", { sessionId: this.sessionId, modeId });
+      }
+      this.ready = true;
+      this.bumpIdleTimer();
+      this.runPromise = this.run(ctx.prompt).catch((error: unknown) => this.fail(error));
+      return {
+        agentId: "copilot",
+        model: this.config.model,
+        ...(typeof asRecord(initialized.agentInfo)?.version === "string"
+          ? { agentVersion: String(asRecord(initialized.agentInfo)?.version) }
+          : {}),
+        detail: {
+          sessionId: this.sessionId,
+          transport: "acp",
+          protocolVersion: 1,
+          ...(cliVersion ? { cliVersion } : {}),
+          mode: this.config.mode,
+          reasoningEffort: this.config.reasoningEffort,
+          modelResolution: typeof acpModel(session) === "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("Copilot 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(`Copilot stopped with ${String(result?.stopReason ?? "unknown reason")}`);
+    // Copilot 1.0.83 emits this native auth failure as text followed by end_turn.
+    if (
+      /^Error: Authorization error\. Your credentials may be expired or invalid\.(?: \(Request ID: [^)]+\))?\s*$/.test(
+        this.responseText,
+      )
+    )
+      throw new Error("Copilot authorization failed; run 'copilot login' and retry");
+    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 (method !== "session/request_permission") {
+        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("Copilot exceeded maxInterrupts"), "max-interactions");
+        return;
+      }
+      const interruptId = `copilot-${id}`;
+      if (this.interrupts.has(interruptId)) throw new Error("Copilot reused a pending request ID");
+      this.interrupts.set(interruptId, { id, params });
+      clearTimeout(this.idleTimer);
+      await this.emitter.emit("interrupt", {
+        kind: "approve",
+        id: interruptId,
+        request: permissionRequestText(params),
+        context: params,
+      });
+      return;
+    }
+    if (method === "session/update") {
+      if (params.sessionId !== this.sessionId) return;
+      const update = asRecord(params.update);
+      const content = asRecord(update?.content);
+      if (update?.sessionUpdate === "agent_message_chunk" && typeof content?.text === "string")
+        this.responseText = (this.responseText + content.text).slice(0, 8_192);
+      if (update)
+        for (const event of this.events.update(update)) await this.emitter.emit("progress", event);
+    }
+  }
+
+  async respond(answer: Answer): Promise<void> {
+    const pending = this.interrupts.get(answer.id);
+    if (!pending) throw new Error(`Copilot has no pending interrupt '${answer.id}'`);
+    this.transport?.write({ id: pending.id, result: permissionAnswer(pending.params, answer) });
+    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(`Copilot 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 copilotDriver = defineDriver({
+  name: "copilot",
+  configSchema: CopilotDriverConfigSchema,
+  runtime: (config) => ({
+    commands: [config.command],
+    capabilities: {
+      interactive: !config.allowAllTools,
+      "tool-calls": true,
+      "tool-results": true,
+      artifacts: true,
+      usage: false,
+      cost: false,
+      isolation: false,
+    },
+  }),
+  selectHarness: selectModelAndReasoningEffort,
+  create: (config) => new CopilotDriver(config),
+});
+
+export type { CopilotDriverConfig };
+export { buildCopilotArgs, CopilotDriverConfigSchema };

package/src/drivers/cursor/README.md

@@ -0,0 +1,66 @@
+# Cursor driver
+
+The `cursor` driver uses Cursor CLI's ACP transport. Install Cursor CLI and
+authenticate it before running Lux. Lux defaults to the unambiguous
+`cursor-agent` executable because other harnesses also install `agent`.
+Set `command` to an absolute path or to `agent` if that is your Cursor installation.
+
+```ts
+{
+  name: "cursor",
+  config: {
+    command: "/absolute/path/to/cursor-agent",
+    model: "YOUR_CURSOR_MODEL_ID",
+    // Optional: one of low, medium, high, xhigh; applied only when ACP advertises it.
+    // reasoningEffort: "low",
+  },
+}
+```
+
+`model` is required. Cursor's model list is account-scoped (`cursor-agent
+--list-models` after login), so the harness catalog keeps it open: any ID is
+accepted in configuration and in a `matrix`, and some IDs encode reasoning
+effort. Use the exact ACP model ID, including bracketed settings such as
+`composer-2.5[fast=true]`. Lux passes the ID through `--model`, selects it with
+ACP when the session advertises a model selector, and rejects a different
+reported model. If `reasoningEffort` is supplied (`low`, `medium`,
+`high`, or `xhigh`), Lux requires a matching advertised ACP thought-level
+selector and checks the response confirms the requested value before sending
+the prompt. No default effort is applied.
+
+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 has synthetic protocol and lifecycle tests plus an opt-in live
+smoke task: `mise run smoke:harnesses -- cursor` from the repository root.
+The live task checks tool evidence, exact file output, and normal completion;
+it uses your installed CLI, existing login, and model quota. Cursor CLI
+`2026.09.23-86fc751` passed the basic authenticated file-copy smoke on 2026-09-30.
+
+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/config.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { InheritEnvironmentSchema } from "../../core/agent-environment.js";
+import { DurationSchema } from "../../core/duration.js";
+import { cursorCatalog } from "../../core/index.js";
+
+export const CursorDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("cursor-agent"),
+    model: z.string().min(1),
+    reasoningEffort: z.enum(cursorCatalog.efforts).optional(),
+    mode: z.enum(["agent", "plan", "ask"]).default("agent"),
+    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"),
+    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",
+];