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

package/src/drivers/cursor/events.ts

@@ -0,0 +1,83 @@
+import { type Progress, toolResultProgress } from "../../core/index.js";
+import { asRecord, type RpcRecord } from "./acp-transport.js";
+import { records } from "./interaction.js";
+
+type ToolState = { value: RpcRecord; bytes: number; name: string };
+
+export class CursorEvents {
+  private seq = 0;
+  private retainedBytes = 0;
+  private readonly tools = new Map<string, ToolState>();
+  private readonly completed = new Set<string>();
+
+  private readonly maxToolCalls: number;
+  private readonly maxBytes: number;
+
+  constructor(maxToolCalls: number, maxBytes: number) {
+    this.maxToolCalls = maxToolCalls;
+    this.maxBytes = maxBytes;
+  }
+
+  update(update: RpcRecord): Progress[] {
+    const ts = Date.now();
+    if (
+      update.sessionUpdate === "agent_message_chunk" ||
+      update.sessionUpdate === "agent_thought_chunk"
+    ) {
+      const content = asRecord(update.content);
+      if (content?.type !== "text" || typeof content.text !== "string") return [];
+      return [
+        {
+          id: `cursor-message-${++this.seq}`,
+          kind: update.sessionUpdate === "agent_message_chunk" ? "agent-message" : "reasoning",
+          payload: { text: content.text },
+          ts,
+        },
+      ];
+    }
+    if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
+      return [{ id: `cursor-update-${++this.seq}`, kind: "cursor-update", payload: update, ts }];
+    }
+    const id = update.toolCallId;
+    if (typeof id !== "string") throw new Error("Cursor ACP tool update omitted toolCallId");
+    if (this.completed.has(id)) return [];
+    const old = this.tools.get(id);
+    if (!old && this.tools.size + this.completed.size >= this.maxToolCalls)
+      throw new Error("Cursor ACP exceeded maxToolCalls");
+    const value = { ...old?.value, ...update };
+    const bytes = Buffer.byteLength(JSON.stringify(value));
+    this.retainedBytes += bytes - (old?.bytes ?? 0);
+    if (this.retainedBytes > this.maxBytes)
+      throw new Error("Cursor ACP tool state exceeded maxQueuedBytes");
+    const name = old?.name ?? String(value.title ?? value.kind ?? "cursor-tool");
+    this.tools.set(id, { value, bytes, name });
+    const events: Progress[] = old
+      ? []
+      : [
+          {
+            id: `tc-${id}`,
+            kind: "tool-call",
+            payload: { name, input: value.rawInput ?? {}, toolUseId: id },
+            ts,
+          },
+        ];
+    if (value.status === "completed" || value.status === "failed") {
+      const content = value.rawOutput ?? value.content ?? [];
+      const text = records(value.content)
+        .map((block) => asRecord(block.content)?.text)
+        .filter((entry) => typeof entry === "string")
+        .join("\n");
+      events.push(
+        toolResultProgress(
+          ++this.seq,
+          { name, toolUseId: id, content, isError: value.status === "failed", text },
+          ts,
+        ),
+      );
+      this.retainedBytes -= bytes;
+      this.tools.delete(id);
+      this.completed.add(id);
+    }
+    return events;
+  }
+}

package/src/drivers/cursor/index.ts

@@ -0,0 +1,316 @@
+import { realpath } from "node:fs/promises";
+import {
+  type AgentDriver,
+  type Answer,
+  type Artifact,
+  type DriverEventMap,
+  defineDriver,
+  discoverCliVersion,
+  type ReadyState,
+  type StartContext,
+  TypedEmitter,
+} from "../../core/index.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+import { AcpTransport, asRecord, type RpcId, type RpcRecord } from "./acp-transport.js";
+import { buildCursorArgs, type CursorDriverConfig, CursorDriverConfigSchema } from "./config.js";
+import { CursorEvents } from "./events.js";
+import { cursorAnswer, cursorQuestionText, effortSelector, records } from "./interaction.js";
+
+class CursorDriver implements AgentDriver {
+  private readonly emitter = new TypedEmitter<DriverEventMap>();
+  private readonly events: CursorEvents;
+  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 CursorEvents(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({
+      command: this.config.command,
+      args: buildCursorArgs(this.config),
+      cwd: this.cwd,
+      env: { ...process.env, ...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;
+      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 =
+        records(session.configOptions).find(
+          (option) => option.category === "model" || option.id === "model",
+        )?.currentValue ?? asRecord(session.models)?.currentModelId;
+      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, this.config.startupTimeoutMs);
+  }
+
+  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)
+        throw new Error("Cursor exceeded maxInterrupts");
+      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?")
+              : String(asRecord(params.toolCall)?.title ?? "Approve this tool call?"),
+          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 ${this.config.idleTimeoutMs}ms`),
+          "idle-timeout",
+        ),
+      this.config.idleTimeoutMs,
+    );
+  }
+
+  private fail(error: unknown, exitReason: "error" | "idle-timeout" = "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,
+    },
+  }),
+  create: (config) => new CursorDriver(config),
+});
+
+export type { CursorDriverConfig };
+export { buildCursorArgs, CursorDriverConfigSchema };

package/src/drivers/cursor/interaction.ts

@@ -0,0 +1,90 @@
+import type { Answer } from "../../core/index.js";
+import { asRecord, type RpcRecord } from "./acp-transport.js";
+
+export const records = (value: unknown): RpcRecord[] =>
+  Array.isArray(value)
+    ? value.flatMap((entry): RpcRecord[] => {
+        const record = asRecord(entry);
+        return record ? [record] : [];
+      })
+    : [];
+
+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 } : {}) },
+    };
+  }
+  const option = records(params.options).find(
+    (entry) => entry.kind === (answer.approved ? "allow_once" : "reject_once"),
+  );
+  // A Lux approval applies to this operation, never a remembered permission.
+  return {
+    outcome:
+      option && typeof option.optionId === "string"
+        ? { outcome: "selected", optionId: option.optionId }
+        : { outcome: "cancelled" },
+  };
+};
+
+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/mcp/index.ts

@@ -6,7 +6,7 @@ import {
   type Answer,
   type Artifact,
   type DriverEventMap,
-  type DriverPlugin,
+  defineDriver,
   type ListedTool,
   MCP_INIT_KIND,
   MCP_TOOLS_LIST_KIND,
@@ -344,8 +344,21 @@ class McpProbeDriverImpl implements AgentDriver {
   }
 }
 
-export const mcpProbeDriver: DriverPlugin<McpProbeDriverConfig> = {
+export const mcpProbeDriver = defineDriver({
   name: "mcp-probe",
   configSchema: McpProbeDriverConfigSchema,
+  runtime: (config) => ({
+    commands: [config.command],
+    capabilities: {
+      interactive: false,
+      "tool-calls": true,
+      "tool-results": true,
+      artifacts: true,
+      subagents: false,
+      usage: false,
+      cost: false,
+      isolation: false,
+    },
+  }),
   create: (config) => new McpProbeDriverImpl(config),
-};
+});