@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/sdk-runner.ts

@@ -1,948 +0,0 @@
-/**
- * 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";
-}