@cursor/bdk 0.2.1

package/src/internal/sdk-runner.ts

@@ -0,0 +1,948 @@
+/**
+ * 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,
+  Cursor,
+  createAgentPlatform,
+  type LocalAgentStore,
+  type ModelSelection,
+  type Run,
+  type RunResult,
+  type SDKAgent,
+} from "@cursor/sdk";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
+import {
+  DEFAULT_MODEL,
+  type ModelSetting,
+  type RunnerSubagent,
+  type RunnerTurnRequest,
+  type TurnOutcome,
+  type TurnUsage,
+} from "../types.js";
+import { mapSdkTokenUsage, usageTokenSum } from "./cloud-turn-cost.js";
+import type { ConversationMirror } from "./conversation-mirror.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { describeError } from "./describe-error.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { sleep } from "./sleep.js";
+
+/** Mirrors @cursor/sdk's SteerAckOutcome; the published dist may predate it. */
+export type SteerAckOutcome = "complete_delivered" | "revert_to_followup";
+
+/** Internal seam between the session engine and the Cursor SDK harness. */
+export interface AgentRunner {
+  runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+  steer?(request: { sessionId: string; text: string }): Promise<SteerAckOutcome>;
+  /**
+   * Resolve a local workspace before any session needs it, so the first turn
+   * is not the one that pays for it. Best effort, hence the reported outcome:
+   * a runner that cannot warm must say so rather than let a caller log
+   * success over a workspace that was never touched.
+   */
+  prewarm?(request: RunnerPrewarmRequest): Promise<PrewarmOutcome>;
+  dispose?(): Promise<void>;
+}
+
+/**
+ * The parts of a turn that decide which local executor it runs on. Must stay
+ * a subset of {@link RunnerTurnRequest} — anything that disagrees warms an
+ * executor no turn will ask for.
+ */
+export type RunnerPrewarmRequest = Pick<
+  RunnerTurnRequest,
+  | "workspaceDir"
+  | "runnerStateDir"
+  | "sandbox"
+  | "tools"
+  | "disallowedTools"
+  | "mcpServers"
+  | "perSendMcpServers"
+  | "subagents"
+  | "model"
+>;
+
+/** Whether a workspace was actually resolved, and why not when it wasn't. */
+export type PrewarmOutcome =
+  | { readonly warmed: true }
+  | { readonly warmed: false; readonly reason: string };
+
+/**
+ * How long a non-`--dev` serve holds workspace scans (rules, skills,
+ * `AGENTS.md`, ignore files). The SDK default is 20s for an editor whose
+ * files move under it; agent-serve checkouts only change on deploy, so a
+ * missed mid-process edit is the right trade. `CURSOR_RIPWALK_CACHE_TTL_MS`
+ * still wins when set. `--dev` leaves the 20s default so skill edits show up.
+ */
+export const SERVE_WORKSPACE_SCAN_CACHE_TTL_MS: number = 24 * 60 * 60 * 1000;
+
+/**
+ * Resolve the SDK workspace-scan TTL for this serve. `undefined` means "do
+ * not call `Cursor.configure`" and leave the SDK at its 20s editor default.
+ */
+export function resolveServeWorkspaceScanCacheTtlMs(args: {
+  dev: boolean;
+  env?: NodeJS.ProcessEnv;
+}): number | undefined {
+  const raw = (args.env ?? process.env).CURSOR_RIPWALK_CACHE_TTL_MS?.trim();
+  if (raw !== undefined && raw !== "") {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  if (args.dev) {
+    return undefined;
+  }
+  return SERVE_WORKSPACE_SCAN_CACHE_TTL_MS;
+}
+
+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;
+  /**
+   * Durable mirror for local conversations (v2 hosted engines). Hydrated
+   * before `Agent.resume` so a follow-up landing on a fresh pod finds the
+   * conversation, and persisted — awaited — after each local turn settles,
+   * because a hosted pod can be parked right after the execution reply.
+   */
+  conversationMirror?: ConversationMirror;
+  /** Diagnostics for degraded paths (resume-miss fallback). */
+  logger?: (line: string) => void;
+  /**
+   * Hold workspace scans this long (ms). Applied via `Cursor.configure` so
+   * each new local executor reuses the walk. Omit to keep the SDK 20s default.
+   */
+  workspaceScanCacheTtlMs?: number;
+}
+
+/**
+ * How long one SDK agent handle (and the Connect transport inside it) may be
+ * reused before the runner retires it.
+ *
+ * The transport exchanges the account API key for a short-lived access token
+ * (`SessionType.API_KEY_TOKEN`, 60 minutes) once per handle, and has no
+ * reliable refresh: an Unauthenticated rejection on the agent's streaming RPC
+ * surfaces while the stream is being read — outside the transport's
+ * request-time 401 retry — so an expired token gets replayed on every
+ * subsequent turn until the handle is rebuilt. Long-lived sessions (watch
+ * wakes, crons) hit this at the ~60 minute mark and then fail forever.
+ * Retiring the handle comfortably before the token can expire keeps them
+ * healthy: `Agent.resume` rehydrates the same conversation from the runner
+ * store on a fresh transport, so recycling costs only transport warmth.
+ */
+const MAX_AGENT_HANDLE_AGE_MS = 45 * 60 * 1000;
+
+interface CachedAgentHandle {
+  agent: Promise<SDKAgent>;
+  openedAtMs: number;
+}
+
+/**
+ * The backend's `NotLoggedIn` copy ("Authentication error" title, "try
+ * logging out and back in." detail) as it surfaces through SDK RunResults.
+ * Deliberately narrow: this gates a one-shot in-place retry, and matching
+ * broader error text would retry turns that a fresh transport cannot fix.
+ */
+export function isAuthErrorMessage(message: string | undefined): boolean {
+  if (message === undefined) {
+    return false;
+  }
+  return /authentication error|try logging out and back in/i.test(message);
+}
+
+/** Cloud `wait()` copy for `stream_expired` / a missing start-state blob. */
+function isStreamExpiredErrorMessage(message: string | undefined): boolean {
+  if (message === undefined) {
+    return false;
+  }
+  return /run stream is no longer available|\[stream_expired\]/i.test(message);
+}
+
+function retryReason(message: string | undefined, isFirstTurn: boolean): string | undefined {
+  if (isStreamExpiredErrorMessage(message)) {
+    return "cloud run stream expired";
+  }
+  // First-turn auth is the credential; a fresh handle cannot fix it.
+  if (!isFirstTurn && isAuthErrorMessage(message)) {
+    return "authentication failure";
+  }
+  return undefined;
+}
+
+/**
+ * The SDK rejects a selection the credential's catalog does not list with
+ * this copy, thrown from `Agent.create` / `Agent.resume` before the turn
+ * streams anything. Matched on the message because the SDK uses its generic
+ * configuration error here.
+ */
+export function isUnavailableModelSelectionMessage(message: string | undefined): boolean {
+  return message !== undefined && /cannot use this model/i.test(message);
+}
+
+export function isUnavailableModelSelectionError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : undefined;
+  return isUnavailableModelSelectionMessage(message);
+}
+
+/**
+ * Inference / provider capacity on the selected model. `wait()` stores the
+ * connect status on `error.code` and strips `[code]` from the message, so
+ * both must be checked. `[unavailable]` in text is the connect status, not
+ * a loose "temporarily unavailable" substring.
+ */
+export function isModelCapacityError(
+  message: string | undefined,
+  code?: string | undefined,
+): boolean {
+  if (code !== undefined && /^(resource_exhausted|unavailable)$/i.test(code)) {
+    return true;
+  }
+  return message !== undefined && /resource_exhausted|\[unavailable\]/i.test(message);
+}
+
+export function isModelCapacityErrorMessage(message: string | undefined): boolean {
+  return isModelCapacityError(message);
+}
+
+/** Catalog refusal or capacity: the authored fallback list can still save the turn. */
+export function shouldFallbackToNextModel(
+  message: string | undefined,
+  code?: string | undefined,
+): boolean {
+  return isUnavailableModelSelectionMessage(message) || isModelCapacityError(message, code);
+}
+
+export function shouldFallbackToNextModelOnError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : undefined;
+  return shouldFallbackToNextModel(message, errorCodeOf(error));
+}
+
+function errorCodeOf(error: unknown): string | undefined {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return undefined;
+  }
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" ? code : undefined;
+}
+
+function modelSettingLabel(model: ModelSetting | undefined): string {
+  if (model === undefined) {
+    return "default";
+  }
+  return typeof model === "string" ? model : model.id;
+}
+
+/** Primary model, then authored fallbacks. No fallbacks keeps today's single attempt. */
+function modelAttemptChain(request: RunnerTurnRequest): Array<ModelSetting | undefined> {
+  const fallbacks = request.modelFallbacks ?? [];
+  if (fallbacks.length === 0) {
+    return [request.model];
+  }
+  return [request.model ?? DEFAULT_MODEL, ...fallbacks];
+}
+
+/**
+ * A rejected create may already have stored the agent id. Later attempts
+ * resume that id so the next model does not die on "already exists". A
+ * create that threw before persisting falls through the runner's not-found
+ * path and creates again. Cloud turns that never received a server id stay
+ * on create: resuming the framework session id is not a cloud agent.
+ */
+function modelAttemptRequest(
+  request: RunnerTurnRequest,
+  model: ModelSetting | undefined,
+  attempt: number,
+): RunnerTurnRequest {
+  if (attempt === 0) {
+    return model === request.model ? request : { ...request, model };
+  }
+  const persistedId = request.sdkAgentId ?? request.sessionId;
+  if (
+    request.runtime === "cloud" &&
+    request.isFirstTurn &&
+    !isServerMintedCloudAgentId(persistedId)
+  ) {
+    return { ...request, model };
+  }
+  return {
+    ...request,
+    model,
+    isFirstTurn: false,
+    sdkAgentId: persistedId,
+  };
+}
+
+export class CursorSdkRunner implements AgentRunner {
+  private readonly agents = new Map<string, CachedAgentHandle>();
+  private readonly activeRuns = new Map<string, Run>();
+  private readonly stores = new Map<string, Promise<LocalAgentStore>>();
+  private readonly prewarmReleases: Array<() => Promise<void>> = [];
+
+  constructor(private readonly options: CursorSdkRunnerOptions = {}) {
+    if (options.workspaceScanCacheTtlMs !== undefined) {
+      Cursor.configure({
+        local: { workspaceScanCacheTtlMs: options.workspaceScanCacheTtlMs },
+      });
+      this.log(`[agent-sdk] workspace scan cache ttl=${options.workspaceScanCacheTtlMs}ms`);
+    }
+  }
+
+  async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    // Fail closed: this runner only knows the Cursor SDK's local and cloud
+    // harnesses. A grokbot turn reaching it means the serve wiring skipped
+    // the Grok Bot runner — running it on the local harness would silently
+    // swap the box (and the SendToUser contract) out from under the agent.
+    if (request.runtime === "grokbot") {
+      throw new Error(
+        `Session ${request.sessionId} is a grokbot turn, which the Cursor SDK runner cannot execute. Serve must route grokbot turns to the Grok Bot runner.`,
+      );
+    }
+    const models = modelAttemptChain(request);
+    let lastError: unknown;
+    for (let attempt = 0; attempt < models.length; attempt++) {
+      const model = models[attempt];
+      let streamed = false;
+      const attemptRequest = modelAttemptRequest(request, model, attempt);
+      try {
+        const outcome = await this.runTurnWithTransportRetry(attemptRequest, () => {
+          streamed = true;
+        });
+        if (
+          outcome.status !== "error" ||
+          streamed ||
+          request.signal?.aborted === true ||
+          !shouldFallbackToNextModel(outcome.errorMessage, outcome.errorCode) ||
+          attempt === models.length - 1
+        ) {
+          return outcome;
+        }
+        this.logModelFallback(request.sessionId, model, models[attempt + 1], outcome.errorMessage);
+      } catch (error) {
+        lastError = error;
+        if (
+          streamed ||
+          request.signal?.aborted === true ||
+          !shouldFallbackToNextModelOnError(error) ||
+          attempt === models.length - 1
+        ) {
+          throw error;
+        }
+        const message = error instanceof Error ? error.message : undefined;
+        this.logModelFallback(request.sessionId, model, models[attempt + 1], message);
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * One model attempt, plus the existing in-place transport retry (expired
+   * cloud stream, or a follow-up auth failure) on that same model. Model
+   * fallback is the caller's job: this returns the error outcome when a
+   * fresh handle cannot fix it.
+   */
+  private async runTurnWithTransportRetry(
+    request: RunnerTurnRequest,
+    onStreamed: () => void,
+  ): Promise<TurnOutcome> {
+    let sawUpdate = false;
+    const tracked: RunnerTurnRequest = {
+      ...request,
+      onUpdate: update => {
+        sawUpdate = true;
+        onStreamed();
+        return request.onUpdate(update);
+      },
+    };
+    const outcome = await this.runTurnAttempt(tracked);
+    if (outcome.status !== "error" || sawUpdate || request.signal?.aborted === true) {
+      return outcome;
+    }
+    const reason = retryReason(outcome.errorMessage, request.isFirstTurn);
+    if (reason === undefined) {
+      return outcome;
+    }
+    // Log the original error even when the retry succeeds so the expiry
+    // still shows up in Datadog.
+    this.log(
+      `[agent-sdk] session ${request.sessionId}: ${reason}: ${outcome.errorMessage}; retrying the turn`,
+    );
+    try {
+      return await this.runTurnAttempt(tracked);
+    } catch {
+      return outcome;
+    }
+  }
+
+  private logModelFallback(
+    sessionId: string,
+    from: ModelSetting | undefined,
+    to: ModelSetting | undefined,
+    message: string | undefined,
+  ): void {
+    this.log(
+      `[agent-sdk] session ${sessionId}: cannot use model ${modelSettingLabel(from)}; retrying on ${modelSettingLabel(to)}: ${message ?? "model unavailable"}`,
+    );
+  }
+
+  private async runTurnAttempt(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    const agentPromise = this.getAgent(request);
+    try {
+      const agent = await agentPromise;
+      const sendMessage =
+        request.images !== undefined && request.images.length > 0
+          ? {
+              text: request.prompt,
+              images: request.images.map(image => ({
+                data: image.data,
+                mimeType: image.mimeType,
+              })),
+            }
+          : request.prompt;
+      const run = await agent.send(sendMessage, {
+        onDelta: async ({ update }) => {
+          try {
+            await request.onUpdate(update);
+          } catch {
+            // Stream mapping must never reject into the SDK transport.
+          }
+        },
+        // The SDK builds this send's MCP session from exactly this set, so
+        // a turn always runs on the headers the engine evaluated for it —
+        // never on the ones a previous turn opened the cached handle with.
+        ...(request.runtime === "local" && request.perSendMcpServers === true
+          ? { mcpServers: request.mcpServers as AgentOptions["mcpServers"] }
+          : {}),
+        ...(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);
+      }
+      // Readable on the handle as soon as send resolves, long before wait().
+      if (
+        request.onRequestId !== undefined &&
+        run.requestId !== undefined &&
+        run.requestId !== ""
+      ) {
+        await request.onRequestId(run.requestId);
+      }
+      this.activeRuns.set(request.sessionId, run);
+      try {
+        const result = await run.wait();
+        let outcome = toTurnOutcome(result);
+        if (outcome.status === "error") {
+          // An error result usually means the handle's transport is poisoned
+          // — most often a cached access token that aged past its 60-minute
+          // lifetime and gets replayed on every request (stream failures
+          // bypass the transport's 401 retry). Retire the handle so the next
+          // attempt resumes the conversation from the store on a fresh
+          // transport instead of failing every turn until a restart.
+          this.evictAgent(request.sessionId, agentPromise);
+        } else if (
+          request.runtime === "cloud" &&
+          outcome.status === "finished" &&
+          usageTokenSum(outcome.usage) <= 0 &&
+          result.id !== ""
+        ) {
+          // Cloud `wait()` drops usage after stream reconnect / getRun replay,
+          // or returns an all-zero stub. `getUsage` still has the run's tokens
+          // (eventually); without them traces never record an estimated cost.
+          outcome = await fillMissingCloudUsage(agent, result.id, outcome);
+        }
+        return outcome;
+      } finally {
+        if (this.activeRuns.get(request.sessionId) === run) {
+          this.activeRuns.delete(request.sessionId);
+        }
+        signal?.removeEventListener("abort", onAbort);
+        // Mirror the conversation before replying: on hosted v2 the pod can
+        // be parked as soon as the execution reply lands, so a
+        // fire-and-forget write would race VM teardown. In the `finally` so
+        // a `wait()` that THROWS (transport death mid-turn, an abort with
+        // no follow-up) still persists the checkpoints the turn already
+        // wrote — the store is local SQLite, safe to read on the throw
+        // path, and persistConversation swallows its own errors. Guarded
+        // here (not just inside the helper) so unmirrored turns keep their
+        // exact post-wait sequencing.
+        if (request.runtime === "local" && this.options.conversationMirror !== undefined) {
+          await this.persistConversation(request, agent.agentId);
+        }
+      }
+    } 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.evictAgent(request.sessionId, agentPromise);
+      throw error;
+    }
+  }
+
+  async steer(request: { sessionId: string; text: string }): Promise<SteerAckOutcome> {
+    const run = this.activeRuns.get(request.sessionId) as
+      | (Run & {
+          steer?: (text: string) => Promise<SteerAckOutcome>;
+        })
+      | undefined;
+    if (run?.steer === undefined) {
+      return "revert_to_followup";
+    }
+    try {
+      return await run.steer(request.text);
+    } catch (error) {
+      this.log(`[agent-sdk] session ${request.sessionId}: steer failed: ${describeError(error)}`);
+      return "revert_to_followup";
+    }
+  }
+
+  /**
+   * Build the local executor for a workspace before any session asks for it.
+   * The warmed executor is reference counted, so the lease is held until
+   * {@link dispose}; dropping it early would tear the workspace back down.
+   */
+  async prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome> {
+    const platform = await createAgentPlatform();
+    const release = await platform.prewarmLocalWorkspace(await this.buildLocalOptions(request));
+    this.prewarmReleases.push(release);
+    return { warmed: true };
+  }
+
+  /**
+   * Drop the cached SDK agent for this session, if one is open.
+   *
+   * Hosted v2 parks and hibernates this process as soon as the execution
+   * reply lands on non-interactive channels. A leftover handle still holds
+   * the pre-freeze Connect/HTTP2 session; the next wake then reuses it and
+   * `AgentService/Run` never starts. Call after `waitForCompletion` so the
+   * hibernate snapshot has an empty cache. Slack's interactive hot-window
+   * still reuses handles because that path does not go through hosted
+   * delivery.
+   */
+  evictSession(sessionId: string): void {
+    const cached = this.agents.get(sessionId);
+    if (cached === undefined) {
+      return;
+    }
+    this.evictAgent(sessionId, cached.agent);
+  }
+
+  async dispose(): Promise<void> {
+    const releases = this.prewarmReleases.splice(0);
+    await Promise.allSettled(releases.map(release => release()));
+    const agents = await Promise.allSettled([...this.agents.values()].map(handle => handle.agent));
+    this.agents.clear();
+    for (const settled of agents) {
+      if (settled.status === "fulfilled") {
+        settled.value.close();
+      }
+    }
+  }
+
+  private getAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+    const cached = this.agents.get(request.sessionId);
+    if (cached !== undefined) {
+      const ageMs = Date.now() - cached.openedAtMs;
+      if (ageMs < MAX_AGENT_HANDLE_AGE_MS) {
+        return cached.agent;
+      }
+      // Past this age the handle's exchanged access token could expire
+      // mid-turn. Retire it and reopen below on a fresh transport.
+      this.log(
+        `[agent-sdk] session ${request.sessionId}: recycling the SDK agent handle after ${Math.round(ageMs / 60_000)} min so the turn runs on a fresh access token`,
+      );
+      this.evictAgent(request.sessionId, cached.agent);
+    }
+    const agentPromise = this.openAgent(request).catch(error => {
+      // Nothing opened, so there is no handle to close — just free the slot.
+      this.agents.delete(request.sessionId);
+      throw error;
+    });
+    this.agents.set(request.sessionId, {
+      agent: agentPromise,
+      openedAtMs: Date.now(),
+    });
+    return agentPromise;
+  }
+
+  /**
+   * Drop a cached handle and close it best-effort to release its transport
+   * and executor lease. Identity-checked so a turn that lost a race with a
+   * newer open cannot evict the replacement handle.
+   */
+  private evictAgent(sessionId: string, agent: Promise<SDKAgent>): void {
+    const cached = this.agents.get(sessionId);
+    if (cached === undefined || cached.agent !== agent) {
+      return;
+    }
+    this.agents.delete(sessionId);
+    void cached.agent.then(sdkAgent => sdkAgent.close()).catch(() => {});
+  }
+
+  private log(line: string): void {
+    (this.options.logger ?? (() => {}))(line);
+  }
+
+  /**
+   * Re-resolve on every turn. Hosted freeze snapshots listen unsigned; the
+   * binder drops `CURSOR_API_KEY` / `CURSOR_API_KEY_FILE` at task time into
+   * the already-running process, which must not have closed over `undefined`.
+   */
+  private requireApiKey(): string {
+    const resolved = resolveApiKeySync({ apiKey: this.options.apiKey });
+    if (resolved === undefined) {
+      throw new Error(
+        `The Cursor SDK runner requires a Cursor credential: run \`${CLI} login\`, set CURSOR_API_KEY, CURSOR_SERVICE_ACCOUNT_KEY, or CURSOR_API_KEY_FILE, or pass serve({ apiKey }).`,
+      );
+    }
+    return resolved.apiKey;
+  }
+
+  private buildSharedOptions(
+    request: RunnerPrewarmRequest,
+  ): Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents"> {
+    const subagents = toAgentDefinitions(request.subagents);
+    return {
+      model: toModelSelection(request.model ?? DEFAULT_MODEL),
+      apiKey: this.requireApiKey(),
+      // Per-send servers ride each agent.send instead (fresh per-session
+      // auth headers every turn). Keeping them out of the create/resume
+      // options also keeps the local executor cache key — which hashes
+      // these options — stable while credentials rotate.
+      ...(Object.keys(request.mcpServers).length > 0 && request.perSendMcpServers !== true
+        ? { mcpServers: request.mcpServers as AgentOptions["mcpServers"] }
+        : {}),
+      ...(subagents === undefined ? {} : { agents: subagents }),
+    };
+  }
+
+  /**
+   * The options that decide which local executor a turn runs on. Prewarming
+   * goes through here too, so a warmed workspace is the one turns land on.
+   */
+  private async buildLocalOptions(
+    request: RunnerPrewarmRequest & Pick<RunnerTurnRequest, "instructions">,
+  ): Promise<AgentOptions> {
+    // Not resolveStore: an injected store is used synchronously (no
+    // microtask, no thenable assimilation), exactly as before the mirror
+    // existed.
+    const store = this.options.store ?? (await this.getStore(request.runnerStateDir));
+    return {
+      ...this.buildSharedOptions(request),
+      // The built-in tool allowlist rides AgentOptions, not `local`, and is
+      // deliberately absent from openCloudAgent's options: the SDK rejects
+      // tool restrictions on cloud agents. Passed on create *and* resume
+      // (both flow through here) — the SDK does not persist it across runs.
+      ...(request.tools === undefined ? {} : { tools: request.tools }),
+      ...(request.disallowedTools === undefined
+        ? {}
+        : { disallowedTools: request.disallowedTools }),
+      // Same shape: local-only (the SDK rejects it with `cloud`), not
+      // persisted, so it rides every create/resume. Replaces Cursor's
+      // built-in system prompt with the agent's composed instructions.
+      // Prewarm requests carry none, and the SDK's workspace cache key
+      // ignores it, so a warmed executor is still the one turns land on.
+      systemPrompt: request.instructions,
+      local: {
+        cwd: request.workspaceDir,
+        settingSources: ["project"],
+        store,
+        ...(request.sandbox === true ? { sandboxOptions: { enabled: true } } : {}),
+      },
+    };
+  }
+
+  private async openAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+    if (request.runtime === "cloud") {
+      return this.openCloudAgent(request, this.buildSharedOptions(request));
+    }
+    return this.openLocalAgent(request);
+  }
+
+  private async openLocalAgent(request: RunnerTurnRequest): Promise<SDKAgent> {
+    const options = await this.buildLocalOptions(request);
+
+    if (request.isFirstTurn || request.sdkAgentId === undefined) {
+      return Agent.create({
+        ...options,
+        agentId: request.sdkAgentId ?? request.sessionId,
+      });
+    }
+
+    const agentId = request.sdkAgentId ?? request.sessionId;
+    const mirror = this.options.conversationMirror;
+    if (mirror !== undefined) {
+      // Host replacement: restore the conversation from the durable mirror
+      // before resuming, so the thread continues instead of starting fresh.
+      // A sink failure propagates and fails the turn (retryable) — reading
+      // an outage as "nothing mirrored" would silently fork the thread.
+      const store = await this.resolveStore(request);
+      await mirror.hydrate(store, agentId);
+    }
+    try {
+      return await Agent.resume(agentId, options);
+    } catch (error) {
+      if (!isLocalAgentNotFoundError(error, agentId)) {
+        throw error;
+      }
+      // Host replacement: the session record survived in durable storage,
+      // but the conversation store died with the old pod. A fresh
+      // conversation under the same id beats failing this thread's turns
+      // forever ("Agent … not found" on every follow-up). The channel's
+      // warm-turn prompt context re-hydrates the thread history.
+      this.log(
+        `[agent-sdk] no stored conversation for ${agentId} on this host; starting a fresh one`,
+      );
+      return Agent.create({ ...options, agentId });
+    }
+  }
+
+  private async openCloudAgent(
+    request: RunnerTurnRequest,
+    shared: Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents">,
+  ): Promise<SDKAgent> {
+    const cloud = toCloudAgentOptions(request.cloud, request.agentServeAgent);
+    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);
+    }
+    // A cloud session past its first turn should carry the bound agent id
+    // (the engine persists it via onSdkAgentId as soon as create() reports
+    // one). Reaching here means the binding turn failed before the server
+    // ever minted an agent — e.g. create() rejected its PR attach — so the
+    // session would otherwise fail every future turn. Mirror the local
+    // host-replacement path above: a fresh conversation beats failing this
+    // thread forever, and the new id binds to the session for later resumes.
+    this.log(
+      `[agent-sdk] cloud session ${request.sessionId} has no bound cloud agent; creating a fresh one`,
+    );
+    return Agent.create(options);
+  }
+
+  private resolveStore(
+    request: Pick<RunnerPrewarmRequest, "runnerStateDir">,
+  ): Promise<LocalAgentStore> {
+    return this.options.store !== undefined
+      ? Promise.resolve(this.options.store)
+      : this.getStore(request.runnerStateDir);
+  }
+
+  /**
+   * Mirror the settled turn's conversation. Persist failures are logged and
+   * dropped — a durable-mirror outage must not fail a turn that already ran.
+   */
+  private async persistConversation(request: RunnerTurnRequest, sdkAgentId: string): Promise<void> {
+    const mirror = this.options.conversationMirror;
+    if (mirror === undefined) {
+      return;
+    }
+    try {
+      const store = await this.resolveStore(request);
+      await mirror.persist(store, sdkAgentId);
+    } catch (error) {
+      this.log(
+        `[agent-sdk] conversation mirror: persist for ${sdkAgentId} failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  private getStore(stateDir: string): Promise<LocalAgentStore> {
+    let storePromise = this.stores.get(stateDir);
+    if (storePromise === undefined) {
+      storePromise = mkdir(stateDir, { recursive: true }).then(() =>
+        SqliteLocalAgentStore.open({
+          stateRoot: stateDir,
+          workspaceRef: 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-");
+}
+
+/**
+ * `Agent.resume` on a store with no row for the agent ("Agent <id> not
+ * found", surfaced by every built-in {@link LocalAgentStore} backend).
+ * Deliberately narrow: transient store/transport failures must propagate
+ * rather than silently fork the thread onto a fresh conversation.
+ */
+export function isLocalAgentNotFoundError(error: unknown, agentId: string): boolean {
+  return (
+    error instanceof Error &&
+    error.message.includes(agentId) &&
+    /\bnot found\b/i.test(error.message)
+  );
+}
+
+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"],
+  agentServeAgent?: string,
+): CloudAgentOptions {
+  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 }),
+    ...(agentServeAgent === undefined ? {} : { agentServeAgent }),
+  };
+}
+
+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 }),
+    ...(result.status === "error" ? { errorMessage: runErrorMessage(result) } : {}),
+    errorCode: result.status === "error" ? result.error?.code : undefined,
+    ...(usage === undefined ? {} : { usage }),
+  };
+}
+
+/** Billing can lag briefly after `wait()`; retry before giving up on cost. */
+const CLOUD_USAGE_RETRY_DELAYS_MS = [0, 400, 1200] as const;
+
+/**
+ * Cloud `wait()` often omits usage after a stream drop. Pull the run's
+ * tokens from the usage API so the engine can still price the turn.
+ * Failures are ignored: a missing estimate is better than failing the turn.
+ */
+async function fillMissingCloudUsage(
+  agent: SDKAgent,
+  runId: string,
+  outcome: TurnOutcome,
+): Promise<TurnOutcome> {
+  for (const delayMs of CLOUD_USAGE_RETRY_DELAYS_MS) {
+    if (delayMs > 0) {
+      await sleep(delayMs);
+    }
+    try {
+      const billed = await agent.getUsage({ runId });
+      const mapped = mapSdkTokenUsage(billed.usage);
+      if (usageTokenSum(mapped) <= 0) {
+        continue;
+      }
+      return { ...outcome, usage: mapped };
+    } catch {
+      // Transient usage-API failures should still burn the retry budget.
+    }
+  }
+  return outcome;
+}
+
+export function runErrorMessage(result: Pick<RunResult, "error">): string {
+  return result.error?.message?.trim() || "The Cursor agent run failed";
+}