@stigmer/runner 3.14.0 → 3.15.0

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

@@ -0,0 +1,368 @@
+/**
+ * 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` (usage, `turn-ended`)
+ *  - `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` and `SDKAgent` are the SDK's own
+ * types (`@cursor/sdk` 1.0.13, concrete in `messages.d.ts` / `run.d.ts` /
+ * `agent.d.ts`), so a script that drifts from the real event shape fails
+ * `tsc`. The delta channel is the exception: `InteractionUpdate` re-exports
+ * from `@anysphere/cursor-sdk-shared`, a workspace package the published SDK
+ * does not ship, so under `skipLibCheck` it resolves to `any` — in production
+ * code too (`turn-stream.ts`, `delta-enricher.ts` read it untyped). The one
+ * delta this double emits, the `turn-ended` usage, is therefore typed HERE
+ * ({@link TurnEndedUsageDelta}) against what `turn-stream.ts` reads from it,
+ * and that gap is recorded in the entry's findings rather than papered over.
+ *
+ * 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 {
+  ModelSelection,
+  Run,
+  RunOperation,
+  RunResult,
+  RunStatus,
+  SDKAgent,
+  SDKMessage,
+  SDKUserMessage,
+  SendOptions,
+} from "@cursor/sdk";
+import type { ConversationTurn } from "@cursor/sdk";
+
+// ---------------------------------------------------------------------------
+// Script steps
+// ---------------------------------------------------------------------------
+
+/**
+ * The `turn-ended` delta as `turn-stream.ts` reads it (`update.type ===
+ * "turn-ended" && update.usage` -> `usageAccumulator.addTurn(update.usage)`).
+ * See the module header for why this is typed locally.
+ */
+export interface TurnEndedUsageDelta {
+  readonly type: "turn-ended";
+  readonly usage: {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly cacheReadTokens?: number;
+  };
+}
+
+/** 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: TurnEndedUsageDelta }
+  | { 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 };
+  },
+  turnEnded(usage: TurnEndedUsageDelta["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 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 as never });
+          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");
+  }
+}

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

@@ -0,0 +1,254 @@
+/**
+ * The `@cursor/sdk` module a hermetic `ExecuteCursor` run imports — every
+ * runtime surface the activity path touches, backed by scripted agents.
+ *
+ * The activity reaches the SDK at three runtime sites and nowhere else:
+ *
+ *  - `session-lifecycle.ts`: `Agent.create(options)`, `Agent.resume(id, options)`,
+ *    `Agent.archive(id, ...)` — the agent handle.
+ *  - `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; parent Q1/Q2), so — exactly as the
+ * native activity tests already do for their boundary modules — the module is
+ * 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 three at once, which is
+ * what this module is.
+ *
+ * `vi.mock` is hoisted and must appear in the test file; the factory can
+ * `await import()` this module and return {@link scriptedCursorSdkModule}. The
+ * module's 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 module.
+ *
+ * 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 (`agentForSession`, 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.
+ */
+
+import type { AgentOptions, ModelListItem, SDKAgent } from "@cursor/sdk";
+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 `platform.workspaceRef` (`session-lifecycle.ts`
+   * `resolvePlatformOptions`: `stigmer-session:<sessionId>`), so the resolver
+   * is keyed by that ref — a scenario computes the ref the same way the
+   * adapter does. `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 `platform.workspaceRef` a create names, read defensively: the platform
+ * option's type re-exports from the unshipped `@anysphere/cursor-sdk-local-runtime`
+ * and resolves to `any` under `skipLibCheck` (the same gap `scripted-agent.ts`
+ * records for the delta channel), so the shape is checked here, not assumed.
+ */
+function workspaceRefOf(options: AgentOptions): string | undefined {
+  const platform: unknown = (options as { platform?: unknown }).platform;
+  if (typeof platform !== "object" || platform === null) return undefined;
+  const ref = (platform as { workspaceRef?: unknown }).workspaceRef;
+  return typeof ref === "string" ? ref : undefined;
+}
+
+export class ScriptedCursorSdk {
+  readonly resolutions: RecordedResolution[] = [];
+  readonly archived: string[] = [];
+  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;
+  }
+
+  archive(agentId: string): void {
+    this.archived.push(agentId);
+  }
+
+  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),
+      archive: async (agentId: string): Promise<void> => current().archive(agentId),
+    },
+    Cursor: {
+      models: {
+        list: async (): Promise<readonly ModelListItem[]> => current().listModels(),
+      },
+    },
+    CursorSdkError: ScriptedCursorSdkError,
+  };
+}

package/src/activities/execute-cursor/__tests__/adapter-is-temporal-free.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Pins that the Cursor adapter is an SDK slice and nothing more: no
+ * production module under `activities/execute-cursor/` imports
+ * `@temporalio/*`.
+ *
+ * Why it matters: every Temporal fact a turn needs — the heartbeat, the
+ * cancellation, the throw the workflow sees — is the turn runtime's
+ * (`harness/run-turn.ts`) and reaches the adapter through the sink. The
+ * contract kit runs an adapter OUTSIDE any activity context
+ * (`__test-utils__/harness-contract/`), so a `Context.current()` anywhere
+ * in the adapter would throw there; and an adapter that threw a
+ * `CancelledFailure` would be deciding pause-vs-shutdown, which is the
+ * runtime's table. A static fence names the file in seconds where the kit
+ * would name it after a stack trace.
+ *
+ * Read off the syntax tree with the same primitive the import-direction
+ * fence uses (`__test-utils__/module-specifiers.ts`), so a package name in a
+ * comment cannot trip it and no import form can slip past it.
+ */
+
+import { describe, it, expect } from "vitest";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { packageImports, readSource, typeScriptFilesUnder } from "../../../__test-utils__/module-specifiers.js";
+
+const SRC_ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+const ADAPTER_ROOT = join(SRC_ROOT, "activities", "execute-cursor");
+
+describe("the Cursor adapter never imports @temporalio", () => {
+  const files = typeScriptFilesUnder(ADAPTER_ROOT, new Set(["__tests__", "__test-utils__"]));
+  const offences = files.flatMap((file) =>
+    packageImports(file, readSource(file), "@temporalio").map((specifier) => `  ${relative(SRC_ROOT, file)} imports "${specifier}"`),
+  );
+
+  it("inspected the adapter's own files (the walk is rooted where it claims)", () => {
+    expect(files.map((f) => relative(ADAPTER_ROOT, f))).toEqual(
+      expect.arrayContaining(["adapter.ts", "turn.ts", "turn-setup.ts", "turn-stream.ts", "turn-settle.ts"]),
+    );
+  });
+
+  it("finds no @temporalio import in any production module", () => {
+    expect(offences, `the Cursor adapter must not import @temporalio/*:\n${offences.join("\n")}`).toEqual([]);
+  });
+});