@cursor/july 0.1.1

package/src/internal/sdk-runner.ts

@@ -0,0 +1,315 @@
+/**
+ * Executes turns on the Cursor harness through `@cursor/sdk`.
+ * Each framework session maps 1:1 to an SDK agent. Local agents use the
+ * session id as the SDK agent id and materialize a workspace for project
+ * settings; cloud agents use Cursor cloud (`bc-…` ids) with optional
+ * `cloud` options from `defineAgent`.
+ */
+
+import { mkdir } from "node:fs/promises";
+import {
+  Agent,
+  type AgentDefinition,
+  type AgentOptions,
+  type CloudAgentOptions,
+  JsonlLocalAgentStore,
+  type LocalAgentStore,
+  type ModelSelection,
+  type RunResult,
+  type SDKAgent,
+} from "@cursor/sdk";
+import {
+  DEFAULT_MODEL,
+  type ModelSetting,
+  type RunnerSubagent,
+  type RunnerTurnRequest,
+  type TurnOutcome,
+  type TurnUsage,
+} from "../types.js";
+
+/** Internal seam between the session engine and the Cursor SDK harness. */
+export interface AgentRunner {
+  runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+  dispose?(): Promise<void>;
+}
+
+export interface CursorSdkRunnerOptions {
+  /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
+  apiKey?: string;
+  /**
+   * Conversation store override. Defaults to a JSONL store under the
+   * engine's state root; install `sqlite3` and pass an SQLite-backed
+   * `LocalAgentStore` for heavy multi-session concurrency.
+   */
+  store?: LocalAgentStore;
+}
+
+export class CursorSdkRunner implements AgentRunner {
+  private readonly agents = new Map<string, Promise<SDKAgent>>();
+  private readonly stores = new Map<string, Promise<LocalAgentStore>>();
+
+  constructor(private readonly options: CursorSdkRunnerOptions = {}) {}
+
+  async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    try {
+      const agent = await this.getAgent(request);
+      const run = await agent.send(request.prompt, {
+        onDelta: async ({ update }) => {
+          try {
+            await request.onUpdate(update);
+          } catch {
+            // Stream mapping must never reject into the SDK transport.
+          }
+        },
+        ...(request.runtime === "local"
+          ? {
+              local: {
+                customTools: request.customTools,
+                // Follow-up turns expire any run still marked active on the
+                // agent (a preempted or crash-wedged run) so this send is not
+                // rejected with "already has active run".
+                ...(request.forceExpireActiveRun === true
+                  ? { force: true }
+                  : {}),
+              },
+            }
+          : {}),
+      });
+      // A follow-up can preempt this turn: cancelling tears down execution and
+      // marks the SDK run terminal so the next send is admitted cleanly. The
+      // signal may already be aborted if the preempt landed while send() was
+      // still creating the run.
+      const signal = request.signal;
+      const onAbort = (): void => {
+        void run.cancel().catch(() => {});
+      };
+      if (signal !== undefined) {
+        if (signal.aborted) {
+          onAbort();
+        } else {
+          signal.addEventListener("abort", onAbort, { once: true });
+        }
+      }
+      // Cloud + envVars: server mints the real `bc-…` id during createAgent
+      // inside the first send. Bind only after that so we never persist/print
+      // the provisional client-seeded id.
+      if (request.onSdkAgentId !== undefined) {
+        await request.onSdkAgentId(agent.agentId);
+      }
+      try {
+        const result = await run.wait();
+        return toTurnOutcome(result);
+      } finally {
+        signal?.removeEventListener("abort", onAbort);
+      }
+    } catch (error) {
+      // Drop the cached agent so a dead Connect/HTTP2 session cannot poison
+      // the next turn (terminal/shell overflow often kills the transport).
+      this.agents.delete(request.sessionId);
+      throw error;
+    }
+  }
+
+  async dispose(): Promise<void> {
+    const agents = await Promise.allSettled([...this.agents.values()]);
+    this.agents.clear();
+    for (const settled of agents) {
+      if (settled.status === "fulfilled") {
+        settled.value.close();
+      }
+    }
+  }
+
+  private getAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+    let agentPromise = this.agents.get(request.sessionId);
+    if (agentPromise === undefined) {
+      agentPromise = this.openAgent(request).catch((error) => {
+        this.agents.delete(request.sessionId);
+        throw error;
+      });
+      this.agents.set(request.sessionId, agentPromise);
+    }
+    return agentPromise;
+  }
+
+  private async openAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+    const apiKey = this.options.apiKey ?? process.env.CURSOR_API_KEY;
+    if (apiKey === undefined || apiKey.trim() === "") {
+      throw new Error(
+        "The Cursor SDK runner requires a Cursor credential: run `agent-serve login`, set CURSOR_API_KEY, or pass serve({ apiKey })."
+      );
+    }
+    const model = request.model ?? DEFAULT_MODEL;
+    const subagents = toAgentDefinitions(request.subagents);
+    const shared: Pick<
+      AgentOptions,
+      "model" | "apiKey" | "mcpServers" | "agents"
+    > = {
+      model: toModelSelection(model),
+      apiKey,
+      ...(Object.keys(request.mcpServers).length > 0
+        ? { mcpServers: request.mcpServers as AgentOptions["mcpServers"] }
+        : {}),
+      ...(subagents === undefined ? {} : { agents: subagents }),
+    };
+
+    if (request.runtime === "cloud") {
+      return this.openCloudAgent(request, shared);
+    }
+    return this.openLocalAgent(request, shared);
+  }
+
+  private async openLocalAgent(
+    request: RunnerTurnRequest,
+    shared: Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents">
+  ): Promise<SDKAgent> {
+    const store =
+      this.options.store ?? (await this.getStore(request.runnerStateDir));
+    const options: AgentOptions = {
+      ...shared,
+      local: {
+        cwd: request.workspaceDir,
+        settingSources: ["project"],
+        store,
+      },
+    };
+
+    if (request.isFirstTurn || request.sdkAgentId === undefined) {
+      return Agent.create({
+        ...options,
+        agentId: request.sdkAgentId ?? request.sessionId,
+      });
+    }
+    return Agent.resume(request.sdkAgentId ?? request.sessionId, options);
+  }
+
+  private async openCloudAgent(
+    request: RunnerTurnRequest,
+    shared: Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents">
+  ): Promise<SDKAgent> {
+    const cloud = toCloudAgentOptions(request.cloud);
+    const hasEnvVars =
+      cloud.envVars !== undefined && Object.keys(cloud.envVars).length > 0;
+    const options: AgentOptions = {
+      ...shared,
+      cloud,
+    };
+
+    const sdkAgentId = request.sdkAgentId?.trim();
+    if (sdkAgentId !== undefined && sdkAgentId !== "") {
+      // A server-minted `bc-…` id always resumes — including on the first
+      // framework turn of a session seeded via SendMessageOptions.sdkAgentId
+      // (PR→bcId affinity across session-store resets). Any persisted id
+      // resumes on later turns.
+      if (isServerMintedCloudAgentId(sdkAgentId) || !request.isFirstTurn) {
+        return Agent.resume(sdkAgentId, options);
+      }
+      if (!hasEnvVars) {
+        // Client-seeded (non bc-…) id on a brand new session: forward it to
+        // create so the server adopts it. With envVars the server must mint
+        // the id, so the seed cannot be honored and create() runs below.
+        return Agent.create({ ...options, agentId: sdkAgentId });
+      }
+    }
+
+    if (request.isFirstTurn) {
+      return Agent.create(options);
+    }
+    throw new Error(
+      `Cloud session ${request.sessionId} is missing sdkAgentId; cannot resume.`
+    );
+  }
+
+  private getStore(stateDir: string): Promise<LocalAgentStore> {
+    let storePromise = this.stores.get(stateDir);
+    if (storePromise === undefined) {
+      storePromise = mkdir(stateDir, { recursive: true }).then(
+        () => new JsonlLocalAgentStore(stateDir)
+      );
+      this.stores.set(stateDir, storePromise);
+    }
+    return storePromise;
+  }
+}
+
+/** Cloud agent ids minted by the server are `bc-…`; those always resume. */
+export function isServerMintedCloudAgentId(id: string): boolean {
+  return id.startsWith("bc-");
+}
+
+export function toModelSelection(model: ModelSetting): ModelSelection {
+  if (typeof model === "string") {
+    return { id: model };
+  }
+  return {
+    id: model.id,
+    ...(model.params === undefined ? {} : { params: model.params }),
+  };
+}
+
+function toCloudAgentOptions(
+  cloud: RunnerTurnRequest["cloud"]
+): CloudAgentOptions {
+  if (cloud === undefined) {
+    return {};
+  }
+  return {
+    ...(cloud.env === undefined ? {} : { env: cloud.env }),
+    ...(cloud.repos === undefined ? {} : { repos: cloud.repos }),
+    ...(cloud.workOnCurrentBranch === undefined
+      ? {}
+      : { workOnCurrentBranch: cloud.workOnCurrentBranch }),
+    ...(cloud.autoCreatePR === undefined
+      ? {}
+      : { autoCreatePR: cloud.autoCreatePR }),
+    ...(cloud.skipReviewerRequest === undefined
+      ? {}
+      : { skipReviewerRequest: cloud.skipReviewerRequest }),
+    ...(cloud.envVars === undefined ? {} : { envVars: cloud.envVars }),
+  };
+}
+
+function toAgentDefinitions(
+  subagents: RunnerSubagent[]
+): Record<string, AgentDefinition> | undefined {
+  if (subagents.length === 0) {
+    return undefined;
+  }
+  const definitions: Record<string, AgentDefinition> = {};
+  for (const subagent of subagents) {
+    definitions[subagent.name] = {
+      description: subagent.description,
+      prompt: subagent.prompt,
+      model:
+        subagent.model === undefined
+          ? "inherit"
+          : toModelSelection(subagent.model),
+    };
+  }
+  return definitions;
+}
+
+function toTurnOutcome(result: RunResult): TurnOutcome {
+  const usage: TurnUsage | undefined =
+    result.usage === undefined
+      ? undefined
+      : {
+          inputTokens: result.usage.inputTokens,
+          outputTokens: result.usage.outputTokens,
+          cacheReadTokens: result.usage.cacheReadTokens,
+          cacheWriteTokens: result.usage.cacheWriteTokens,
+          ...(result.usage.reasoningTokens === undefined
+            ? {}
+            : { reasoningTokens: result.usage.reasoningTokens }),
+        };
+  return {
+    status: result.status,
+    ...(result.result === undefined ? {} : { result: result.result }),
+    // The published RunResult carries no structured error details; failures
+    // thrown by send()/wait() surface through the engine's catch instead.
+    ...(result.status === "error"
+      ? { errorMessage: "The Cursor agent run failed" }
+      : {}),
+    ...(usage === undefined ? {} : { usage }),
+  };
+}