@stigmer/runner 3.14.0 → 3.14.1

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

@@ -0,0 +1,342 @@
+/**
+ * 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.
+ */
+
+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;
+}
+
+export class ScriptedCursorAgent implements SDKAgent {
+  readonly agentId: string;
+  model: ModelSelection | undefined = undefined;
+  readonly sends: RecordedSend[] = [];
+  readonly runs: ScriptedRun[] = [];
+  closeCalls = 0;
+  private nextTurn = 0;
+
+  constructor(private readonly options: ScriptedAgentOptions) {
+    this.agentId = options.agentId;
+  }
+
+  async send(message: string | SDKUserMessage, options?: SendOptions): Promise<Run> {
+    const script = this.options.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})`,
+      );
+    }
+    const runId = this.options.runIds?.[this.nextTurn] ?? `run-${this.agentId}-${this.nextTurn + 1}`;
+    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,166 @@
+/**
+ * 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 NEXT unclaimed agent in `agents` (turn 1 of a
+ *    fresh session; the fresh agent of a poisoned-handle recovery).
+ *  - `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.
+ *  - `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[];
+  /**
+   * 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[];
+  /** 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;
+}
+
+export class ScriptedCursorSdk {
+  readonly resolutions: RecordedResolution[] = [];
+  readonly archived: string[] = [];
+  private nextCreate = 0;
+  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);
+    }
+  }
+
+  create(options: AgentOptions): SDKAgent {
+    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 `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.
+ */
+export class ScriptedCursorSdkError extends Error {
+  readonly isRetryable: boolean;
+  readonly code: string | undefined;
+  constructor(message: string, opts: { isRetryable?: boolean; code?: string } = {}) {
+    super(message);
+    this.name = "CursorSdkError";
+    this.isRetryable = opts.isRetryable ?? false;
+    this.code = opts.code;
+  }
+}
+
+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,
+  };
+}