@stigmer/runner 3.14.1 → 3.15.0

package/src/activities/execute-cursor/__test-utils__/hermetic-cursor.ts

@@ -21,17 +21,24 @@
  *   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule());
  * ```
  *
- * Network: the activity's only HTTP fetch is the model registry
- * (`model-pricing-data.ts`, `shared/model-registry.ts`; both fail SOFT to
- * defaults with a 60s failure cache, which would make the goldens depend on
- * DEFAULT_PRICING and log warnings on every run). `fetch` is stubbed to answer
- * one registry document — and to THROW for any other URL, so a new network
- * dependency on the activity path fails the hermetic run instead of leaking.
+ * Network: the registry document and the `fetch` stub that serves it are
+ * the runtime's fixtures (`src/__test-utils__/model-registry-fixture.ts`);
+ * the record's four resources come from `execution-record-fixture.ts` with
+ * this harness's ids and model laid over the defaults.
  *
  * The fixture model is `composer-2.5`, pinned (not Auto) on purpose: Auto short-
  * circuits `resolveServiceTierParams` before the catalog, and a pinned model runs
  * the catalog path, the variant-param pinning, and the `run.wait()` model echo
  * check — more of the production path under the golden.
+ *
+ * Where a scenario reaches the knobs that drive the terminal table, each on
+ * the object that models the thing deciding it: the execution's cost budget
+ * and the control plane's STOP answer on the record (`CursorRecordOptions`);
+ * a control-plane fault on the client (`clientOverrides`); the runner's stall
+ * and lock windows on the scenario's `Config` (`config`); an SDK failure on
+ * the SDK double (`ScriptedSdkOptions`); an SDK-side cancel or a mid-stream
+ * wedge as an `effect` step on the run. Nothing here is a switch in production
+ * code — every knob is a value the production path already reads.
  */
 
 import { execFileSync } from "node:child_process";
@@ -39,31 +46,13 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { create } from "@bufbuild/protobuf";
 import type { ModelListItem } from "@cursor/sdk";
-import { vi } from "vitest";
-import {
-  AgentExecutionSchema,
-  type AgentExecution,
-} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import {
-  AgentExecutionSpecSchema,
-  ExecutionConfigSchema,
-} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
-import { SessionSchema, type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
-import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import {
   LocalPathSourceSchema,
   WorkspaceEntrySchema,
   WorkspaceSourceSchema,
   type WorkspaceEntry,
 } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
-import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
-import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
-import {
-  AgentInstanceSchema,
-  type AgentInstance,
-} from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
-import { AgentInstanceSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/spec_pb";
-import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import type { StigmerClient } from "../../../client/stigmer-client.js";
 import type { Config } from "../../../config.js";
 import type { ExecuteActivityInput } from "../../../shared/activity-input.js";
 import {
@@ -75,6 +64,8 @@ import {
   type HermeticEnvironment,
   type InvocationControls,
 } from "../../../__test-utils__/hermetic-activity.js";
+import { executionRecordFixture, type ExecutionRecordOptions } from "../../../__test-utils__/execution-record-fixture.js";
+import { FIXTURE_MODEL } from "../../../__test-utils__/model-registry-fixture.js";
 import { _resetAgentSessionCacheForTests } from "../agent-session-cache.js";
 import { _resetPricingCache } from "../model-pricing-data.js";
 import { resetCatalogCacheForTests } from "../service-tier.js";
@@ -92,8 +83,8 @@ export const FIXTURE = {
   agentInstanceId: "ain_hermetic_0001",
   agentId: "agt_hermetic_0001",
   agentName: "hermetic-agent",
-  /** The pinned model; in the registry stub AND the SDK catalog below. */
-  model: "composer-2.5",
+  /** The pinned model; in the registry fixture AND the SDK catalog below. */
+  model: FIXTURE_MODEL,
   cursorApiKey: "hermetic-cursor-api-key",
 } as const;
 
@@ -101,105 +92,29 @@ export const FIXTURE = {
 // The record
 // ---------------------------------------------------------------------------
 
-export interface CursorRecordOptions {
-  /** The user's message for this execution. */
-  readonly message: string;
-  /** The agent's instructions (system prompt body). */
-  readonly instructions?: string;
-  /** Session workspace entries (a `local_path` entry turns on capture mode). */
-  readonly workspaceEntries?: WorkspaceEntry[];
-  readonly modelName?: string;
-  readonly autoApproveAll?: boolean;
-}
+/** The record's knobs; the ids and the default model are this harness's fixture. */
+export type CursorRecordOptions = Omit<ExecutionRecordOptions, "ids">;
 
-/** The four resources of one execution, wired by id into a chain. */
+/** The four resources of one execution, wired by id into a chain, under the Cursor fixture ids. */
 export function cursorExecutionRecord(options: CursorRecordOptions): ExecutionRecord {
-  const execution: AgentExecution = create(AgentExecutionSchema, {
-    metadata: create(ApiResourceMetadataSchema, {
-      id: FIXTURE.executionId,
+  return executionRecordFixture({
+    ...options,
+    modelName: options.modelName ?? FIXTURE.model,
+    ids: {
       org: FIXTURE.org,
-      name: FIXTURE.executionId,
-    }),
-    spec: create(AgentExecutionSpecSchema, {
+      executionId: FIXTURE.executionId,
       sessionId: FIXTURE.sessionId,
-      message: options.message,
-      autoApproveAll: options.autoApproveAll ?? false,
-      executionConfig: create(ExecutionConfigSchema, {
-        modelName: options.modelName ?? FIXTURE.model,
-      }),
-    }),
-  });
-  const session: Session = create(SessionSchema, {
-    metadata: create(ApiResourceMetadataSchema, {
-      id: FIXTURE.sessionId,
-      org: FIXTURE.org,
-      name: FIXTURE.sessionId,
-    }),
-    spec: create(SessionSpecSchema, {
       agentInstanceId: FIXTURE.agentInstanceId,
-      workspaceEntries: options.workspaceEntries ?? [],
-    }),
-  });
-  const agentInstance: AgentInstance = create(AgentInstanceSchema, {
-    metadata: create(ApiResourceMetadataSchema, {
-      id: FIXTURE.agentInstanceId,
-      org: FIXTURE.org,
-      name: FIXTURE.agentInstanceId,
-    }),
-    spec: create(AgentInstanceSpecSchema, { agentId: FIXTURE.agentId }),
-  });
-  const agent: Agent = create(AgentSchema, {
-    metadata: create(ApiResourceMetadataSchema, {
-      id: FIXTURE.agentId,
-      org: FIXTURE.org,
-      name: FIXTURE.agentName,
-    }),
-    spec: create(AgentSpecSchema, {
-      description: "Hermetic fixture agent",
-      instructions: options.instructions ?? "You are the hermetic fixture agent. Answer briefly.",
-    }),
+      agentId: FIXTURE.agentId,
+      agentName: FIXTURE.agentName,
+    },
   });
-  return new ExecutionRecord({ execution, session, agentInstance, agent });
 }
 
 // ---------------------------------------------------------------------------
-// The registry document and the SDK catalog
+// The SDK catalog
 // ---------------------------------------------------------------------------
 
-/**
- * The model registry document both readers parse (`parsePricingTable` wants
- * `harness: "cursor"` + `pricing`; `parseRegistry` wants `id` + `provider` and
- * reads `capabilities.vision`). One entry, the fixture model, priced at round
- * numbers so the golden's `estimatedCostUsd` is legible.
- */
-export const REGISTRY_DOCUMENT = {
-  models: [
-    {
-      id: FIXTURE.model,
-      displayName: "Composer 2.5 (hermetic fixture)",
-      provider: "cursor",
-      harness: "cursor",
-      costTier: "standard",
-      featured: true,
-      capabilities: { vision: true },
-      pricing: {
-        inputPricePerMillion: 1.0,
-        outputPricePerMillion: 4.0,
-        cacheWritePricePerMillion: 1.0,
-        cacheReadPricePerMillion: 0.1,
-      },
-      pricingVariants: {
-        fast: {
-          inputPricePerMillion: 3.0,
-          outputPricePerMillion: 12.0,
-          cacheWritePricePerMillion: 3.0,
-          cacheReadPricePerMillion: 0.3,
-        },
-      },
-    },
-  ],
-} as const;
-
 /** The SDK catalog entry for the fixture model: both pinnable params declared. */
 export const SDK_CATALOG: readonly ModelListItem[] = [
   {
@@ -212,26 +127,6 @@ export const SDK_CATALOG: readonly ModelListItem[] = [
   },
 ];
 
-/**
- * Stub `fetch` to answer the registry document and refuse everything else.
- * Returns the URLs fetched, for the "no other network" assertion.
- */
-export function stubRegistryFetch(): { readonly urls: string[]; restore(): void } {
-  const urls: string[] = [];
-  vi.stubGlobal(
-    "fetch",
-    vi.fn(async (input: string | URL | Request) => {
-      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
-      urls.push(url);
-      if (!url.includes("/model-registry")) {
-        throw new Error(`hermetic run attempted a non-registry network call: ${url}`);
-      }
-      return { ok: true, status: 200, json: async () => REGISTRY_DOCUMENT } as unknown as Response;
-    }),
-  );
-  return { urls, restore: () => vi.unstubAllGlobals() };
-}
-
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -369,6 +264,8 @@ export interface CursorScenario {
   readonly clock: ScriptedClock;
   readonly record: ExecutionRecord;
   readonly sdk: ScriptedCursorSdk;
+  /** The runner this scenario runs on: the OSS posture plus the scenario's knobs. */
+  readonly config: Config;
 }
 
 export interface CursorScenarioOptions {
@@ -376,6 +273,19 @@ export interface CursorScenarioOptions {
   readonly clock: ScriptedClock;
   readonly record: ExecutionRecord;
   readonly sdk: ScriptedSdkOptions;
+  /**
+   * Control-plane facets the scenario opts INTO, or faults it injects, over
+   * the record's everyday answers (`ExecutionRecord.client`): a rejecting
+   * `getAgent` is how a blueprint-resolution failure is staged.
+   */
+  readonly clientOverrides?: Partial<StigmerClient>;
+  /**
+   * Runner knobs over {@link hermeticCursorConfig}: a scenario that needs the
+   * stall watchdog or the workspace-lock wait to expire states the window
+   * here. A property of the runner the scenario runs on, not of one turn, so
+   * it lives on the scenario and every turn of it sees the same `Config`.
+   */
+  readonly config?: Partial<Config>;
 }
 
 /** Bind the record and the SDK for a scenario; resets the harness caches first. */
@@ -383,8 +293,14 @@ export function beginCursorScenario(options: CursorScenarioOptions): CursorScena
   resetCursorModuleState();
   const sdk = new ScriptedCursorSdk(options.sdk);
   bindScriptedSdk(sdk);
-  bindHermeticClient(options.record.client());
-  return { env: options.env, clock: options.clock, record: options.record, sdk };
+  bindHermeticClient(options.record.client(options.clientOverrides));
+  return {
+    env: options.env,
+    clock: options.clock,
+    record: options.record,
+    sdk,
+    config: { ...hermeticCursorConfig(options.env), ...options.config },
+  };
 }
 
 export interface CursorTurnOptions {
@@ -396,26 +312,30 @@ export interface CursorTurnOptions {
 }
 
 /**
- * Run ONE `ExecuteCursor` invocation for the scenario. The activities are
- * constructed per invocation (the factory constructs its client, which is the
- * one bound at `beginCursorScenario`).
+ * Run ONE `ExecuteCursor` invocation for the scenario: the real Cursor
+ * adapter under the real turn runtime, as the composition roots wire them.
+ * Built per invocation (the registry constructs its client, which is the one
+ * bound at `beginCursorScenario`; the adapter boots on the scenario's config).
  */
 export async function runCursorTurn(
   scenario: CursorScenario,
   options: CursorTurnOptions = {},
 ): Promise<ActivityInvocation> {
   // Imported lazily so the scenario file's `vi.mock` declarations are in
-  // force before the activity module (and, through it, `@cursor/sdk` and the
-  // client) is loaded.
-  const { createCursorActivities } = await import("../index.js");
-  const activities = createCursorActivities(hermeticCursorConfig(scenario.env));
+  // force before the adapter module is loaded and before its `boot` loads
+  // `@cursor/sdk` (through `turn.ts`) and the registry loads the client.
+  const { createCursorAdapter } = await import("../adapter.js");
+  const { createHarnessActivities } = await import("../../../harness/registry.js");
+  const adapter = createCursorAdapter();
+  await adapter.boot(scenario.config);
+  const activities = await createHarnessActivities([{ harness: "cursor", adapter }], scenario.config);
   // The typed wire shape the control plane's workflow sends (activity-input.ts).
   const input: ExecuteActivityInput = {
     execution_id: scenario.record.executionId,
     thread_id: options.threadId ?? "",
     turn_seq: options.turnSeq ?? 0,
   };
-  return runActivityHermetically(activities.ExecuteCursor, [input], {
+  return runActivityHermetically(activities.ExecuteCursor!, [input], {
     taskQueue: "hermetic-test-queue",
     onControls: options.onControls,
   });

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

@@ -42,7 +42,11 @@
  *
  * 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.
+ * 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 {
@@ -284,6 +288,11 @@ export interface RecordedSend {
   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;
@@ -291,20 +300,37 @@ export class ScriptedCursorAgent implements SDKAgent {
   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.options.turns[this.nextTurn];
+    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.options.turns.length})`,
+          `(the scenario declared ${this.turns.length})`,
       );
     }
-    const runId = this.options.runIds?.[this.nextTurn] ?? `run-${this.agentId}-${this.nextTurn + 1}`;
+    const runId = this.nextRunId;
     this.nextTurn++;
     this.sends.push({ message, hasOnDelta: !!options?.onDelta });
     if (options?.model) this.model = options.model;

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

@@ -26,11 +26,18 @@
  * 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 NEXT unclaimed agent in `agents` (turn 1 of a
- *    fresh session; the fresh agent of a poisoned-handle recovery).
+ *  - `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`), else throws — `resolveAgent`
- *    then falls back to `create`, which is the production shape of a lost handle.
+ *    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.
  */
 
@@ -40,11 +47,29 @@ 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[];
 }
@@ -56,19 +81,47 @@ export interface RecordedResolution {
   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(
@@ -101,20 +154,55 @@ export class ScriptedCursorSdk {
   }
 }
 
+/** 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 two fields the classifier reads (`isRetryable`, `code`), 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 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;
-  constructor(message: string, opts: { isRetryable?: boolean; code?: string } = {}) {
+  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,
+    };
   }
 }
 

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([]);
+  });
+});