@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/activities/execute-cursor/__test-utils__/scripted-agent.ts

@@ -0,0 +1,374 @@
+/**
+ * Scripted `@cursor/sdk` agent — the double the hermetic `ExecuteCursor` runs
+ * drive instead of a live Cursor agent.
+ *
+ * The Cursor harness delegates the agent loop to the SDK: `agent.send()`
+ * returns a `Run` whose `stream()` yields `SDKMessage`s, whose `onDelta`
+ * callback carries usage, and whose `wait()` resolves the `RunResult`. Between
+ * those events the REAL SDK also performs side effects the harness observes
+ * only indirectly — it executes the tool (writing a file into the workspace) and
+ * it spawns the workspace's `.cursor/hooks.json` hook before a gated tool (the
+ * runner's own bash script, which appends to the denial ledger). A double that
+ * replays events alone would leave those effects out and the harness's
+ * deny-and-retry and file-review paths untested.
+ *
+ * So a turn is a SCRIPT of ordered steps, one of four kinds:
+ *
+ *  - `event(SDKMessage)`     — yielded from `stream()`
+ *  - `delta(update)`         — fired through `onDelta`: any `InteractionUpdate`
+ *                              (the `turn-ended` usage the loop prices; the
+ *                              tool-call timings, shell output and completion
+ *                              status the transcript folds — #1097 widened
+ *                              the step from `turn-ended` alone so the delta
+ *                              channel has an end-to-end net)
+ *  - `effect(fn)`            — the side effect the SDK would have performed
+ *                              (run the real hook, write a workspace file,
+ *                              cancel the activity from the outside)
+ *  - `result(RunResult)`     — what `wait()` resolves; ends the run
+ *
+ * The same shape as the native harness's `__test-utils__/scripted-model.ts`
+ * (`ScriptStep`, driven in order), applied to the SDK's event surface.
+ *
+ * Typing: `SDKMessage`, `Run`, `RunResult`, `SDKAgent` and the delta channel's
+ * `InteractionUpdate` are the SDK's own types (`@cursor/sdk` 1.0.31, concrete
+ * in `messages.d.ts` / `run.d.ts` / `agent.d.ts` / the vendored `delta-types`),
+ * so a script that drifts from the real event shape fails `tsc`. (At 1.0.13
+ * the delta types resolved to `any` and the one delta this double emitted was
+ * typed locally; stigmer/stigmer#1053 closed that gap.)
+ *
+ * Cancellation: `run.cancel()` is how the harness stops a turn (first denial,
+ * cost cap, stall). The double honours it the way the SDK does — the stream
+ * ends at the next step, `wait()` resolves `{ status: "cancelled" }` — because
+ * the deny-and-retry path depends on exactly that ordering.
+ *
+ * Every `send()` consumes the NEXT script in the agent's queue: turn 1, then
+ * the resumed turn 2 on the same parked agent. A `send()` with no script left
+ * is a test bug and throws. A golden scenario declares every script up front
+ * (`turns`); a driver that learns what the next turn plays only just before
+ * it runs — the harness contract kit's Cursor subject — arranges it with
+ * {@link ScriptedCursorAgent.arrangeNextTurn}, which REPLACES the slot the
+ * next `send()` will consume.
+ */
+
+import type {
+  AgentUsage,
+  GetUsageOptions,
+  InteractionUpdate,
+  ModelSelection,
+  Run,
+  RunOperation,
+  RunResult,
+  RunStatus,
+  SDKAgent,
+  SDKMessage,
+  SDKUserMessage,
+  SendOptions,
+  TurnEndedUpdate,
+} from "@cursor/sdk";
+import type { ConversationTurn } from "@cursor/sdk";
+
+// ---------------------------------------------------------------------------
+// Script steps
+// ---------------------------------------------------------------------------
+
+/** What an `effect` step can reach: the run it is part of. */
+export interface EffectContext {
+  readonly run: ScriptedRun;
+  readonly agent: ScriptedCursorAgent;
+}
+
+export type ScriptStep =
+  | { readonly kind: "event"; readonly event: SDKMessage }
+  | { readonly kind: "delta"; readonly update: InteractionUpdate }
+  | { readonly kind: "effect"; readonly label: string; readonly run: (ctx: EffectContext) => void | Promise<void> }
+  | { readonly kind: "result"; readonly result: Omit<RunResult, "id"> };
+
+/** One `send()`'s worth of behaviour. */
+export type TurnScript = readonly ScriptStep[];
+
+/** Step builders — the vocabulary a scenario file reads as. */
+export const step = {
+  event(event: SDKMessage): ScriptStep {
+    return { kind: "event", event };
+  },
+  /** Any delta the SDK fires through `onDelta` between stream events: tool-call timings, shell output, a completion's status. */
+  delta(update: InteractionUpdate): ScriptStep {
+    return { kind: "delta", update };
+  },
+  /** The `turn-ended` delta `turn-stream.ts` prices; the SDK's shape, all four counts stated. */
+  turnEnded(usage: NonNullable<TurnEndedUpdate["usage"]>): ScriptStep {
+    return { kind: "delta", update: { type: "turn-ended", usage } };
+  },
+  effect(label: string, run: (ctx: EffectContext) => void | Promise<void>): ScriptStep {
+    return { kind: "effect", label, run };
+  },
+  finished(result?: Partial<Omit<RunResult, "id" | "status">>): ScriptStep {
+    return { kind: "result", result: { status: "finished", ...result } };
+  },
+  errored(result?: Partial<Omit<RunResult, "id" | "status">>): ScriptStep {
+    return { kind: "result", result: { status: "error", ...result } };
+  },
+} as const;
+
+/**
+ * `SDKMessage` builders bound to one (agent_id, run_id) pair, so a scenario
+ * reads as the conversation it scripts. Shapes are the SDK's `messages.d.ts`;
+ * tool names are the STREAM taxonomy (`edit`, `shell`, `read` — lowercase; the
+ * hook sees `Write`, `Shell`, `Read`; see `approval-gate.test.ts`).
+ */
+export function sdkEvents(agentId: string, runId: string) {
+  const base = { agent_id: agentId, run_id: runId } as const;
+  return {
+    init(): SDKMessage {
+      return { type: "system", subtype: "init", ...base };
+    },
+    assistant(text: string): SDKMessage {
+      return { type: "assistant", ...base, message: { role: "assistant", content: [{ type: "text", text }] } };
+    },
+    thinking(text: string): SDKMessage {
+      return { type: "thinking", ...base, text };
+    },
+    toolCall(
+      callId: string,
+      name: string,
+      status: "running" | "completed" | "error",
+      args?: unknown,
+      result?: unknown,
+    ): SDKMessage {
+      return { type: "tool_call", ...base, call_id: callId, name, status, args, result };
+    },
+    status(status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED", message?: string): SDKMessage {
+      return { type: "status", ...base, status, message };
+    },
+    /** The SDK's `task` event: a status line about the run in the agent's own voice, which the transcript shows as a SYSTEM message. */
+    task(text: string, status?: string): SDKMessage {
+      return { type: "task", ...base, text, status };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The run
+// ---------------------------------------------------------------------------
+
+/** Called once per step so the driver's clock can tick. */
+export type StepObserver = (step: ScriptStep, index: number) => void;
+
+export class ScriptedRun implements Run {
+  readonly id: string;
+  readonly agentId: string;
+  private _status: RunStatus = "running";
+  private cancelled = false;
+  private scriptedResult: Omit<RunResult, "id"> | undefined;
+  private streamed = false;
+  private readonly statusListeners = new Set<(status: RunStatus) => void>();
+  /** `run.cancel()` calls, for assertions. */
+  readonly cancelCalls: number[] = [];
+
+  constructor(
+    readonly agent: ScriptedCursorAgent,
+    id: string,
+    private readonly script: TurnScript,
+    private readonly onDelta: SendOptions["onDelta"],
+    private readonly observeStep: StepObserver | undefined,
+    /** What `conversation()` answers; the error classifier reads it on a failed run. */
+    private readonly conversationTurns: ConversationTurn[] = [],
+  ) {
+    this.id = id;
+    this.agentId = agent.agentId;
+  }
+
+  get status(): RunStatus {
+    return this._status;
+  }
+
+  get result(): string | undefined {
+    return this.scriptedResult?.result;
+  }
+
+  get model(): ModelSelection | undefined {
+    return this.scriptedResult?.model ?? this.agent.model;
+  }
+
+  supports(_operation: RunOperation): boolean {
+    return true;
+  }
+
+  unsupportedReason(_operation: RunOperation): string | undefined {
+    return undefined;
+  }
+
+  onDidChangeStatus(listener: (status: RunStatus) => void): () => void {
+    this.statusListeners.add(listener);
+    return () => this.statusListeners.delete(listener);
+  }
+
+  async conversation(): Promise<ConversationTurn[]> {
+    return this.conversationTurns;
+  }
+
+  async *stream(): AsyncGenerator<SDKMessage, void> {
+    if (this.streamed) {
+      throw new Error(`ScriptedRun ${this.id}: stream() consumed twice`);
+    }
+    this.streamed = true;
+    for (let i = 0; i < this.script.length; i++) {
+      // A cancel lands between steps, exactly where the SDK's own stream would
+      // stop delivering.
+      if (this.cancelled) break;
+      const s = this.script[i];
+      this.observeStep?.(s, i);
+      switch (s.kind) {
+        case "event":
+          yield s.event;
+          break;
+        case "delta":
+          await this.onDelta?.({ update: s.update });
+          break;
+        case "effect":
+          await s.run({ run: this, agent: this.agent });
+          break;
+        case "result":
+          this.scriptedResult = s.result;
+          break;
+        default: {
+          const exhaustive: never = s;
+          throw new Error(`ScriptedRun: unknown step ${String(exhaustive)}`);
+        }
+      }
+    }
+    if (!this.cancelled) this.setStatus(this.scriptedResult?.status ?? "finished");
+  }
+
+  async wait(): Promise<RunResult> {
+    if (this.cancelled) {
+      return { id: this.id, status: "cancelled" };
+    }
+    if (!this.scriptedResult) {
+      // A script that never declared its result is a test bug — surface it
+      // instead of inventing a "finished" the golden would then pin.
+      throw new Error(
+        `ScriptedRun ${this.id}: wait() called but the script has no result step ` +
+          `(add step.finished() or step.errored())`,
+      );
+    }
+    return { id: this.id, ...this.scriptedResult };
+  }
+
+  async cancel(): Promise<void> {
+    this.cancelCalls.push(Date.now());
+    this.cancelled = true;
+    this.setStatus("cancelled");
+  }
+
+  private setStatus(status: RunStatus): void {
+    this._status = status;
+    for (const l of this.statusListeners) l(status);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The agent
+// ---------------------------------------------------------------------------
+
+export interface ScriptedAgentOptions {
+  readonly agentId: string;
+  /** One script per `send()`, consumed in order. */
+  readonly turns: readonly TurnScript[];
+  /** Run ids, one per turn, so goldens carry stable `run_id`s. */
+  readonly runIds?: readonly string[];
+  readonly observeStep?: StepObserver;
+  readonly conversationTurns?: ConversationTurn[];
+}
+
+/** What the harness passed to `send()`, kept for assertions on the prompt. */
+export interface RecordedSend {
+  readonly message: string | SDKUserMessage;
+  readonly hasOnDelta: boolean;
+}
+
+/** The run id a send is given when the scenario named none: `run-<agentId>-<n>`, `n` counting sends from 1. */
+export function defaultRunId(agentId: string, sendIndex: number): string {
+  return `run-${agentId}-${sendIndex + 1}`;
+}
+
+export class ScriptedCursorAgent implements SDKAgent {
+  readonly agentId: string;
+  model: ModelSelection | undefined = undefined;
+  readonly sends: RecordedSend[] = [];
+  readonly runs: ScriptedRun[] = [];
+  closeCalls = 0;
+  private nextTurn = 0;
+  /** The scenario's scripts, one slot per send; `arrangeNextTurn` writes the slot the next send consumes. */
+  private readonly turns: TurnScript[];
+
+  constructor(private readonly options: ScriptedAgentOptions) {
+    this.agentId = options.agentId;
+    this.turns = [...options.turns];
+  }
+
+  /** The run id the NEXT `send()` will be given — so a script can be built with matching event ids before the send happens. */
+  get nextRunId(): string {
+    return this.options.runIds?.[this.nextTurn] ?? defaultRunId(this.agentId, this.nextTurn);
+  }
+
+  /**
+   * Set (or replace) what the NEXT `send()` plays. Scripts already consumed
+   * are untouched; a slot declared up front for a later send stays where it
+   * is.
+   */
+  arrangeNextTurn(script: TurnScript): void {
+    this.turns[this.nextTurn] = script;
+  }
+
+  async send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run> {
+    const script = this.turns[this.nextTurn];
+    if (!script) {
+      throw new Error(
+        `ScriptedCursorAgent ${this.agentId}: send() #${this.nextTurn + 1} has no script ` +
+          `(the scenario declared ${this.turns.length})`,
+      );
+    }
+    const runId = this.nextRunId;
+    this.nextTurn++;
+    this.sends.push({ message, hasOnDelta: !!options?.onDelta });
+    if (options?.model) this.model = options.model;
+    const run = new ScriptedRun(
+      this,
+      runId,
+      script,
+      options?.onDelta,
+      this.options.observeStep,
+      this.options.conversationTurns,
+    );
+    this.runs.push(run);
+    return run;
+  }
+
+  close(): void {
+    this.closeCalls++;
+  }
+
+  async reload(): Promise<void> {
+    // No persisted state to reload in the double.
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    this.close();
+  }
+
+  async listArtifacts(): Promise<never[]> {
+    return [];
+  }
+
+  async downloadArtifact(_path: string): Promise<Buffer> {
+    throw new Error("ScriptedCursorAgent: artifacts are not part of the scripted surface");
+  }
+
+  async getUsage(_options?: GetUsageOptions): Promise<AgentUsage> {
+    // The harness prices the `turn-ended` delta itself (`usage-pricing.ts`) and
+    // never asks the SDK for billed usage; a call here is a test bug, like a
+    // `send()` with no script.
+    throw new Error("ScriptedCursorAgent: getUsage() is not part of the scripted surface");
+  }
+}

package/src/activities/execute-cursor/__test-utils__/scripted-sdk.ts

@@ -0,0 +1,310 @@
+/**
+ * The `@cursor/sdk` module a hermetic `ExecuteCursor` run imports — every
+ * runtime surface the activity path touches, backed by scripted agents — and
+ * the `@cursor/sdk/sqlite` module beside it, backed by a store that holds
+ * nothing.
+ *
+ * The activity reaches the SDK at four runtime sites and nowhere else:
+ *
+ *  - `session-lifecycle.ts`: `Agent.create(options)`, `Agent.resume(id, options)`
+ *    — the agent handle.
+ *  - `session-store.ts`: `SqliteLocalAgentStore.open({ workspaceRef, stateRoot })`
+ *    from `@cursor/sdk/sqlite` — the session's store the handle is created and
+ *    resumed over (`local.store`).
+ *  - `service-tier.ts`: `Cursor.models.list({ apiKey })` — the catalog the
+ *    variant params (`fast`, `thinking`) are pinned from.
+ *  - `index.ts` outer catch: `import("@cursor/sdk")` for `CursorSdkError`, the
+ *    `instanceof` the error classifier keys on.
+ *
+ * Neither the SDK nor the client is injectable into the activity (the real
+ * seam arrives with the harness contract), so — exactly as the
+ * native activity tests already do for their boundary modules — the modules
+ * are substituted with `vi.mock`. Three existing tests each mock ONE of these
+ * surfaces (`session-lifecycle.test.ts`, `service-tier.test.ts`,
+ * `sdk-warmup.test.ts`); a whole-activity run needs all of them at once, which
+ * is what this module is.
+ *
+ * `vi.mock` is hoisted and must appear in the test file, once per module id
+ * (a subpath is its own module id, so `@cursor/sdk/sqlite` needs its own
+ * `vi.mock`); the factories `await import()` this module and return
+ * {@link scriptedCursorSdkModule} and {@link scriptedCursorSqliteModule}. The
+ * modules' statics read the {@link ScriptedCursorSdk} bound for the current
+ * scenario ({@link bindScriptedSdk}), so one test file can run several
+ * scenarios with different agents against the same mocked modules.
+ *
+ * Resolution rules a scenario declares, mirroring what the real SDK does:
+ *  - `Agent.create` hands out the agent declared for the session it is asked
+ *    for (`agentForWorkspaceRef`, when the scenario resolves agents per
+ *    session — the harness contract kit runs several sessions concurrently on
+ *    one adapter, and the order their creates arrive in is real I/O timing),
+ *    else the NEXT unclaimed agent in `agents` (turn 1 of a fresh session; the
+ *    fresh agent of a poisoned-handle recovery) — unless the scenario declared
+ *    a `createFailure`, which the FIRST create throws instead (the SDK refusing
+ *    to mint an agent: a 401 on the key, a validation error).
+ *  - `Agent.resume(id)` hands back the agent with that id if the scenario
+ *    declared it (in `agents` or `resumableAgents`, or handed out for a
+ *    session), else throws — `resolveAgent` then falls back to `create`, which
+ *    is the production shape of a lost handle.
+ *  - `Cursor.models.list` answers the scenario's catalog.
+ *  - `SqliteLocalAgentStore.open` hands out a {@link ScriptedLocalAgentStore}
+ *    carrying the ref and root it was asked for, and records the open; its
+ *    `dispose()` is recorded too, so a scenario can assert the adapter's
+ *    session-store lifetime (`releaseSession`, `shutdown`).
+ */
+
+import type { AgentOptions, ModelListItem, SDKAgent } from "@cursor/sdk";
+import type { SqliteLocalAgentStore, SqliteLocalAgentStoreOptions } from "@cursor/sdk/sqlite";
+import type { ScriptedCursorAgent } from "./scripted-agent.js";
+
+export interface ScriptedSdkOptions {
+  /** Agents handed out by `Agent.create`, in order. Also resumable by id. */
+  readonly agents: readonly ScriptedCursorAgent[];
+  /**
+   * The agent `Agent.create` hands out for the session the create names,
+   * consulted before the ordered list. The SDK's create options carry the
+   * session as the store's `workspaceRef` (`local.store`, opened by
+   * `session-store.ts`: `stigmer-session:<sessionId>`), so the resolver is
+   * keyed by that ref — a scenario computes the ref the same way the adapter
+   * does (`resolveSessionStoreLocation`). `undefined` falls through to the
+   * list. Consulted live on every create, so a scenario may mint the session's
+   * agent only when it learns of the session.
+   */
+  readonly agentForWorkspaceRef?: (workspaceRef: string) => ScriptedCursorAgent | undefined;
+  /**
+   * Agents `Agent.resume` finds by id but `Agent.create` never hands out — a
+   * previous turn's agent the session knows only by `harness_state_id`.
+   */
+  readonly resumableAgents?: readonly ScriptedCursorAgent[];
+  /**
+   * Thrown by the FIRST `Agent.create` instead of handing out an agent; later
+   * creates hand out `agents` as usual. A {@link ScriptedCursorSdkError} here is
+   * the SDK's own refusal (the activity's outer catch keys on `instanceof`);
+   * a plain `Error` is anything else that can escape the SDK boundary.
+   */
+  readonly createFailure?: Error;
+  /** What `Cursor.models.list` answers. */
+  readonly catalog: readonly ModelListItem[];
+}
+
+/** One `Agent.create` / `Agent.resume` call as the activity made it. */
+export interface RecordedResolution {
+  readonly kind: "create" | "resume";
+  readonly agentId: string | undefined;
+  readonly options: Partial<AgentOptions> | undefined;
+}
+
+/**
+ * The session a create names: the `workspaceRef` of the store it passes as
+ * `local.store`. In a hermetic run that store is the one this module's sqlite
+ * double opened; anything else (a test that mocks `@cursor/sdk` with its own
+ * stub and passes no store) names no session and falls through to the list.
+ */
+function workspaceRefOf(options: AgentOptions): string | undefined {
+  const store = options.local?.store;
+  return store instanceof ScriptedLocalAgentStore ? store.workspaceRef : undefined;
+}
+
+/**
+ * The `@cursor/sdk/sqlite` store the adapter opens per session, holding
+ * nothing: the scripted agents carry their own state, so the store only has
+ * to be the thing `Agent.create` / `Agent.resume` are handed and the thing
+ * `releaseSession` / `shutdown` dispose. `open` and `dispose` are recorded on
+ * the bound {@link ScriptedCursorSdk} for lifetime assertions.
+ */
+export class ScriptedLocalAgentStore {
+  disposeCalls = 0;
+
+  constructor(
+    readonly workspaceRef: string,
+    readonly stateRoot: string,
+  ) {}
+
+  static async open(options: SqliteLocalAgentStoreOptions): Promise<ScriptedLocalAgentStore> {
+    const store = new ScriptedLocalAgentStore(options.workspaceRef, options.stateRoot ?? "");
+    current().stores.push(store);
+    return store;
+  }
+
+  async dispose(): Promise<void> {
+    this.disposeCalls++;
+  }
+}
+
+export class ScriptedCursorSdk {
+  readonly resolutions: RecordedResolution[] = [];
+  /** Every store `SqliteLocalAgentStore.open` handed out, in order. */
+  readonly stores: ScriptedLocalAgentStore[] = [];
+  private nextCreate = 0;
+  private createFailurePending: boolean;
+  private readonly byId = new Map<string, ScriptedCursorAgent>();
+
+  constructor(private readonly options: ScriptedSdkOptions) {
+    for (const a of [...options.agents, ...(options.resumableAgents ?? [])]) {
+      this.byId.set(a.agentId, a);
+    }
+    this.createFailurePending = options.createFailure !== undefined;
+  }
+
+  create(options: AgentOptions): SDKAgent {
+    if (this.createFailurePending && this.options.createFailure) {
+      this.createFailurePending = false;
+      this.resolutions.push({ kind: "create", agentId: undefined, options });
+      throw this.options.createFailure;
+    }
+    const workspaceRef = workspaceRefOf(options);
+    const forSession = workspaceRef !== undefined ? this.options.agentForWorkspaceRef?.(workspaceRef) : undefined;
+    if (forSession) {
+      this.byId.set(forSession.agentId, forSession);
+      forSession.model = options.model;
+      this.resolutions.push({ kind: "create", agentId: forSession.agentId, options });
+      return forSession;
+    }
+    const agent = this.options.agents[this.nextCreate];
+    if (!agent) {
+      throw new Error(
+        `ScriptedCursorSdk: Agent.create() #${this.nextCreate + 1} has no agent ` +
+          `(the scenario declared ${this.options.agents.length})`,
+      );
+    }
+    this.nextCreate++;
+    agent.model = options.model;
+    this.resolutions.push({ kind: "create", agentId: agent.agentId, options });
+    return agent;
+  }
+
+  resume(agentId: string, options: Partial<AgentOptions> | undefined): SDKAgent {
+    this.resolutions.push({ kind: "resume", agentId, options });
+    const agent = this.byId.get(agentId);
+    if (!agent) {
+      throw new ScriptedCursorSdkError(`agent ${agentId} not found`, { code: "agent_not_found" });
+    }
+    if (options?.model) agent.model = options.model;
+    return agent;
+  }
+
+  listModels(): readonly ModelListItem[] {
+    return this.options.catalog;
+  }
+}
+
+/** The construction options of the SDK's `CursorSdkError` (`errors.d.ts`), minus `cause`. */
+export interface ScriptedCursorSdkErrorOptions {
+  readonly isRetryable?: boolean;
+  readonly code?: string;
+  readonly status?: number;
+  readonly endpoint?: string;
+  readonly requestId?: string;
+  readonly operation?: string;
+}
+
+/**
+ * The `CursorSdkError` the mocked module exports. A real `Error` subclass with
+ * the SDK class's public surface (`@cursor/sdk` `errors.d.ts`: `isRetryable`,
+ * `code`, `status`, `endpoint`, `requestId`, `operation`, `toJSON()`), under
+ * the SDK's class name so `err.constructor.name` and `instanceof` (against
+ * THIS module's export, which is what the activity's dynamic import resolves
+ * to) both hold. The activity's outer catch reads `code`, `status` and
+ * `message` for the classifier and logs `toJSON()`; the double must carry the
+ * whole surface or the catch arm itself throws instead of mapping the error.
+ */
+export class ScriptedCursorSdkError extends Error {
+  readonly isRetryable: boolean;
+  readonly code: string | undefined;
+  readonly status: number | undefined;
+  readonly endpoint: string | undefined;
+  readonly requestId: string | undefined;
+  readonly operation: string | undefined;
+  constructor(message: string, opts: ScriptedCursorSdkErrorOptions = {}) {
+    super(message);
+    this.name = "CursorSdkError";
+    this.isRetryable = opts.isRetryable ?? false;
+    this.code = opts.code;
+    this.status = opts.status;
+    this.endpoint = opts.endpoint;
+    this.requestId = opts.requestId;
+    this.operation = opts.operation;
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      isRetryable: this.isRetryable,
+      code: this.code,
+      status: this.status,
+      endpoint: this.endpoint,
+      requestId: this.requestId,
+      operation: this.operation,
+    };
+  }
+}
+
+let bound: ScriptedCursorSdk | undefined;
+
+/** Bind the SDK the mocked module serves for the current scenario. */
+export function bindScriptedSdk(sdk: ScriptedCursorSdk): void {
+  bound = sdk;
+}
+
+function current(): ScriptedCursorSdk {
+  if (!bound) {
+    throw new Error(
+      "scripted-sdk: no ScriptedCursorSdk bound — call bindScriptedSdk(sdk) before running the activity",
+    );
+  }
+  return bound;
+}
+
+/**
+ * The factory a test passes to `vi.mock("@cursor/sdk", ...)`:
+ *
+ * ```ts
+ * vi.mock("@cursor/sdk", async () =>
+ *   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
+ * );
+ * ```
+ *
+ * Only the runtime surface the activity path uses is provided. Any other
+ * import from the mocked module is `undefined` and fails loudly at the call
+ * site — deliberately, so a new SDK dependency in production code is noticed
+ * here rather than silently stubbed.
+ */
+export function scriptedCursorSdkModule(): Record<string, unknown> {
+  return {
+    Agent: {
+      create: async (options: AgentOptions): Promise<SDKAgent> => current().create(options),
+      resume: async (agentId: string, options?: Partial<AgentOptions>): Promise<SDKAgent> =>
+        current().resume(agentId, options),
+    },
+    Cursor: {
+      models: {
+        list: async (): Promise<readonly ModelListItem[]> => current().listModels(),
+      },
+    },
+    CursorSdkError: ScriptedCursorSdkError,
+  };
+}
+
+/**
+ * The factory a test passes to `vi.mock("@cursor/sdk/sqlite", ...)`, beside
+ * the one above:
+ *
+ * ```ts
+ * vi.mock("@cursor/sdk/sqlite", async () =>
+ *   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+ * );
+ * ```
+ *
+ * The one export the runner reads from that entry (`session-store.ts`). The
+ * class is exported under the SDK's name so `session-store.ts`'s dynamic
+ * import destructures it unchanged; its type is the SDK's, which is why
+ * {@link ScriptedLocalAgentStore} carries `workspaceRef`, `stateRoot` and
+ * `dispose()` — the members the runner touches — and nothing else.
+ */
+export function scriptedCursorSqliteModule(): Record<string, unknown> {
+  return {
+    SqliteLocalAgentStore: ScriptedLocalAgentStore satisfies {
+      open(options: SqliteLocalAgentStoreOptions): Promise<Pick<SqliteLocalAgentStore, "workspaceRef" | "stateRoot" | "dispose">>;
+    },
+  };
+}