@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/activities/execute-cursor/__tests__/cursor-baseurl-routing.live.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Test that the SDK works correctly when CURSOR_BACKEND_URL is unset.
+ *
+ * In proxy mode, only CURSOR_API_BASE_URL is set (for Connect RPC).
+ * CURSOR_BACKEND_URL is left unset so the SDK uses its built-in defaults:
+ *   - CloudApiClient → api.cursor.com (REST: /v1/models, CRUD)
+ *   - Token exchange → api2.cursor.sh (/auth/exchange_user_api_key)
+ *
+ * This test verifies:
+ *   1. Model validation (GET /v1/models) works with real API key when
+ *      CURSOR_BACKEND_URL is unset (routes to api.cursor.com by default)
+ *   2. Agent execution works end-to-end (token exchange + Connect RPC)
+ *
+ * NOTE: CURSOR_API_BASE_URL routing cannot be tested from vitest because
+ * the native SDK binary reads it at process startup, not at import time.
+ * That routing is validated by the production code in main.ts which sets
+ * the env var BEFORE any SDK import.
+ *
+ * The model is `composer-2.5`, the one the other live instruments and the
+ * hermetic fixture pin: the arms prove routing, which no model choice changes.
+ *
+ * Live class (`*.live.test.ts`): runs only through `npm run test:live`, by
+ * hand or in the live lane; skips without `CURSOR_API_KEY` outside the lane
+ * (`src/__test-utils__/live-gate.ts`). Each arm is one short turn with no
+ * product cost cap (the SDK is driven directly, not through an execution).
+ */
+
+import { describe, it, expect, beforeAll } from "vitest";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { liveSecret } from "../../../__test-utils__/live-gate.js";
+
+const CURSOR_API_KEY = liveSecret("CURSOR_API_KEY") ?? "";
+
+describe.skipIf(!liveSecret("CURSOR_API_KEY"))("SDK routing with CURSOR_BACKEND_URL unset", () => {
+  beforeAll(() => {
+    // Ensure CURSOR_BACKEND_URL is unset — the SDK should use its built-in
+    // defaults for REST calls (model validation → api.cursor.com, token
+    // exchange → api2.cursor.sh).
+    delete process.env.CURSOR_BACKEND_URL;
+  });
+
+  it("Agent.create() with explicit model succeeds (model validation via default api.cursor.com)", async () => {
+    const stateRoot = join(tmpdir(), `cursor-routing-test-${Date.now()}`);
+    mkdirSync(stateRoot, { recursive: true });
+
+    const { Agent } = await import("@cursor/sdk");
+    const { SqliteLocalAgentStore } = await import("@cursor/sdk/sqlite");
+
+    const agent = await Agent.create({
+      apiKey: CURSOR_API_KEY,
+      model: { id: "composer-2.5" },
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `routing-test-${Date.now()}`, stateRoot }),
+      },
+    });
+
+    expect(agent).toBeDefined();
+    expect(agent.agentId).toBeTruthy();
+    console.log(`Agent created with model validation: agentId=${agent.agentId}`);
+  }, 30_000);
+
+  it("agent.send() succeeds (token exchange + Connect RPC round-trip)", async () => {
+    const stateRoot = join(tmpdir(), `cursor-routing-send-${Date.now()}`);
+    mkdirSync(stateRoot, { recursive: true });
+
+    const { Agent } = await import("@cursor/sdk");
+    const { SqliteLocalAgentStore } = await import("@cursor/sdk/sqlite");
+
+    const agent = await Agent.create({
+      apiKey: CURSOR_API_KEY,
+      model: { id: "composer-2.5" },
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `routing-send-test-${Date.now()}`, stateRoot }),
+      },
+    });
+
+    const run = await agent.send("Reply with exactly: routing-test-ok");
+    const result = await run.wait();
+
+    expect(result).toBeDefined();
+    expect(["completed", "finished"]).toContain(result.status);
+    console.log(
+      `Full round-trip succeeded: runId=${result.id}, status=${result.status}, ` +
+      `durationMs=${result.durationMs}`,
+    );
+  }, 120_000);
+});

package/src/activities/execute-cursor/__tests__/cursor-event-recorder.test.ts

@@ -0,0 +1,142 @@
+/**
+ * The Cursor event recorder's contract (`cursor-event-recorder.ts`): off when
+ * no directory is named; both SDK channels in ONE file under ONE arrival
+ * counter, each line saying which channel it came from; the file named by the
+ * execution; a cyclic payload recorded as a marker rather than failing the
+ * flush. The native recorder's `v3-event-recorder.test.ts` is the sibling.
+ *
+ * The ordering arm is the reason the recorder exists in this shape: a delta
+ * that arrives between two stream events must read between them in the file,
+ * because "does `tool-call-completed` precede the stream's own completion" is
+ * a question only the arrival order can answer.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtemp, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { InteractionUpdate, SDKMessage } from "@cursor/sdk";
+import { createCursorEventRecorder } from "../cursor-event-recorder.js";
+
+/** A stream event carrying only what the recorder reads; the rest is payload. */
+function streamEvent(type: string, extra: Record<string, unknown> = {}): SDKMessage {
+  return { type, agent_id: "agent-1", run_id: "run-1", ...extra } as unknown as SDKMessage;
+}
+
+function delta(type: string, extra: Record<string, unknown> = {}): InteractionUpdate {
+  return { type, ...extra } as unknown as InteractionUpdate;
+}
+
+interface RecordedLine {
+  readonly seq: number;
+  readonly capturedAt: string;
+  readonly channel: "stream" | "delta";
+  readonly type: string;
+  readonly agent_id?: string;
+  readonly run_id?: string;
+  readonly event?: Record<string, unknown>;
+  readonly update?: Record<string, unknown>;
+}
+
+async function readLines(dir: string, executionId: string): Promise<RecordedLine[]> {
+  const content = await readFile(join(dir, `${executionId}.cursor-events.jsonl`), "utf-8");
+  return content
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as RecordedLine);
+}
+
+describe("createCursorEventRecorder", () => {
+  it("returns undefined when no directory is named (recording off)", () => {
+    expect(createCursorEventRecorder("exec-1", undefined)).toBeUndefined();
+    expect(createCursorEventRecorder("exec-1", "")).toBeUndefined();
+  });
+
+  it("returns a recorder with both channels and a flush when a directory is named", () => {
+    const recorder = createCursorEventRecorder("exec-1", "/tmp/unused");
+    expect(recorder).toBeDefined();
+    expect(recorder!.record).toBeInstanceOf(Function);
+    expect(recorder!.recordDelta).toBeInstanceOf(Function);
+    expect(recorder!.flush).toBeInstanceOf(Function);
+  });
+});
+
+describe("CursorEventRecorder", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-recorder-test-"));
+  });
+
+  it("flush writes nothing when nothing was recorded", async () => {
+    const recorder = createCursorEventRecorder("exec-empty", dir)!;
+    await recorder.flush();
+    expect(await readdir(dir)).toHaveLength(0);
+  });
+
+  it("sequences both channels in ONE file in arrival order, each line naming its channel", async () => {
+    const recorder = createCursorEventRecorder("exec-order", dir)!;
+
+    recorder.record(streamEvent("tool_call", { subtype: "started", call_id: "c1" }));
+    recorder.recordDelta(delta("shell-output-delta", { event: { chunk: "hook probe\n" } }));
+    recorder.recordDelta(delta("tool-call-completed", { toolCall: { id: "c1" } }));
+    recorder.record(streamEvent("tool_call", { subtype: "completed", call_id: "c1" }));
+    recorder.record(streamEvent("result"));
+
+    await recorder.flush();
+    const lines = await readLines(dir, "exec-order");
+
+    expect(lines.map((l) => l.seq)).toEqual([0, 1, 2, 3, 4]);
+    expect(lines.map((l) => `${l.channel}:${l.type}`)).toEqual([
+      "stream:tool_call",
+      "delta:shell-output-delta",
+      "delta:tool-call-completed",
+      "stream:tool_call",
+      "stream:result",
+    ]);
+    for (const line of lines) expect(line.capturedAt).toBeTruthy();
+  });
+
+  it("a stream line carries the event's agent and run ids and the whole event; a delta line the whole update", async () => {
+    const recorder = createCursorEventRecorder("exec-shape", dir)!;
+
+    recorder.record(streamEvent("assistant", { content: "hi" }));
+    recorder.recordDelta(delta("turn-ended", { usage: { inputTokens: 12 } }));
+
+    await recorder.flush();
+    const [stream, deltaLine] = await readLines(dir, "exec-shape");
+
+    expect(stream!.agent_id).toBe("agent-1");
+    expect(stream!.run_id).toBe("run-1");
+    expect(stream!.event).toMatchObject({ type: "assistant", content: "hi" });
+    expect(stream!.update).toBeUndefined();
+
+    expect(deltaLine!.update).toEqual({ type: "turn-ended", usage: { inputTokens: 12 } });
+    expect(deltaLine!.event).toBeUndefined();
+    expect(deltaLine!.agent_id).toBeUndefined();
+  });
+
+  it("names the file by execution id and creates the directory if it does not exist", async () => {
+    const nested = join(dir, "nested", "deep");
+    const recorder = createCursorEventRecorder("exec-mkdir", nested)!;
+
+    recorder.record(streamEvent("system"));
+    await recorder.flush();
+
+    expect(await readdir(nested)).toEqual(["exec-mkdir.cursor-events.jsonl"]);
+  });
+
+  it("records a cyclic payload as a serialization marker instead of failing the flush", async () => {
+    const recorder = createCursorEventRecorder("exec-cyclic", dir)!;
+
+    const cyclic: Record<string, unknown> = { type: "custom", a: 1 };
+    cyclic.self = cyclic;
+    recorder.record(cyclic as unknown as SDKMessage);
+
+    await recorder.flush();
+    const [line] = await readLines(dir, "exec-cyclic");
+
+    expect(line!.type).toBe("custom");
+    expect(line!.event).toMatchObject({ _serializationError: true });
+    expect((line!.event as { keys: string[] }).keys).toContain("a");
+  });
+});

package/src/activities/execute-cursor/__tests__/cursor-fetch-interceptor-bypass.live.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Live probe: which of the SDK's calls a `globalThis.fetch` interceptor can
+ * see. A fetch wrapper that notes any call to a cursor.sh / cursor.com URL is
+ * installed, then `Agent.create()` runs (local mode, no model named).
+ *
+ * What the one arm proves: `Agent.create()` completes WITHOUT a global-fetch
+ * call to a Cursor URL — its transport is connect-node over Node's HTTP/2, so
+ * a fetch-level interceptor alone cannot rewrite it. That is why the adapter
+ * installs BOTH interceptors in proxy mode (`fetch-interceptor.ts` and
+ * `http2-interceptor.ts`). Measured true at SDK 1.0.31 on 2026-09-16 (#1097's
+ * live run, 1/1).
+ *
+ * What it does NOT prove: that the fetch interceptor is useless. A reading of
+ * the 1.0.31 bundle the same day found the SDK's cloud-api client and its
+ * token exchange on global `fetch`, on paths this arm never exercises; the
+ * fetch interceptor exists for those.
+ *
+ * Live class (`*.live.test.ts`): runs only through `npm run test:live`, by
+ * hand or in the live lane; skips without `CURSOR_API_KEY` outside the lane
+ * (`src/__test-utils__/live-gate.ts`). The arm creates an agent and sends no
+ * message, so it spends nothing beyond the key exchange.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { liveSecret } from "../../../__test-utils__/live-gate.js";
+
+const CURSOR_API_KEY = liveSecret("CURSOR_API_KEY") ?? "";
+
+describe.skipIf(!liveSecret("CURSOR_API_KEY"))("Fetch Interceptor vs Connect-Node Transport", () => {
+  let interceptCalled = false;
+  const originalFetch = globalThis.fetch;
+
+  beforeAll(() => {
+    interceptCalled = false;
+    globalThis.fetch = (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      if (url.includes("cursor.sh") || url.includes("cursor.com")) {
+        interceptCalled = true;
+        console.log(`[INTERCEPTOR HIT] ${url}`);
+      }
+      return originalFetch(input, init);
+    }) as typeof fetch;
+  });
+
+  afterAll(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("Agent.create() completes without a globalThis.fetch call to a Cursor URL", async () => {
+    const { Agent } = await import("@cursor/sdk");
+    const { SqliteLocalAgentStore } = await import("@cursor/sdk/sqlite");
+
+    const stateRoot = join(tmpdir(), `cursor-intercept-test-${Date.now()}`);
+    mkdirSync(stateRoot, { recursive: true });
+
+    const agent = await Agent.create({
+      apiKey: CURSOR_API_KEY,
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `intercept-test-${Date.now()}`, stateRoot }),
+      },
+    });
+
+    expect(agent.agentId).toBeTruthy();
+    console.log(`Agent created: ${agent.agentId}, interceptCalled=${interceptCalled}`);
+
+    // The create path is connect-node over Node's HTTP/2, not globalThis.fetch;
+    // see the header for what this does and does not say about proxy mode.
+    expect(interceptCalled).toBe(false);
+  }, 30_000);
+});

package/src/activities/execute-cursor/__tests__/cursor-generate-image.live.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Live ground-truth capture for Cursor's native `generateImage` tool (issue
+ * #965) — the ground-truth capture discipline of cursor_hitl_test.go applied to the
+ * interaction-channel tool family.
+ *
+ * WHY THIS EXISTS. Production incident aex_01m1a6ww3nmp4952ar5v0g4g85: an
+ * agent invoked `generateImage`, the call hung twice and settled
+ * TOOL_CALL_INTERRUPTED, and the model told the user a write approval was
+ * pending — an approval the platform never held (the run had
+ * auto_approve_all ON, so nothing was ever denied). The block happened
+ * inside the Cursor agent runtime, in a layer no Stigmer seam touches:
+ * `generateImage` rides the SDK's interaction-query channel
+ * (generateImageRequestQuery), not the ordinary tool path, and the SDK
+ * exposes no public interaction-listener seam the runner could answer it
+ * from. This test is the standing instrument that answers, against the REAL
+ * SDK the runner ships:
+ *
+ *  1. Does `generateImage` complete AT ALL in the runner's headless local
+ *     arrangement (Agent.create({ local }), project setting sources)?
+ *  2. Does the `preToolUse` hook fire for it — i.e. CAN the Stigmer HITL
+ *     gate see it — and under which `tool_name`?
+ *  3. What exact error/result does the model see when it fails?
+ *
+ * The answers decide the #965 fix shape: hook visible + capability works →
+ * classify + gate behind the standard write approval; otherwise → the
+ * honest-unavailability posture (there is no seam to gate or deny it).
+ *
+ * Live class (`*.live.test.ts`): runs only through `npm run test:live`, by
+ * hand or in the live lane; skips without `CURSOR_API_KEY` outside the lane
+ * (`src/__test-utils__/live-gate.ts`). It spends real credits for one short
+ * turn, with no product cost cap (the SDK is driven directly, not through an
+ * execution). Findings are PRINTED, not asserted: like that earlier capture,
+ * this documents upstream behavior we do not own; the only hard assertion is
+ * that the run itself reaches a terminal outcome (no infinite hang at the SDK
+ * boundary), which is a promise worth a release check.
+ */
+
+import { describe, it, expect } from "vitest";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { liveSecret } from "../../../__test-utils__/live-gate.js";
+
+const CURSOR_API_KEY = liveSecret("CURSOR_API_KEY") ?? "";
+
+/**
+ * A minimal observation-only preToolUse/beforeMCPExecution hook: appends every
+ * invocation's stdin JSON to a log file and ALLOWS everything. Proves whether
+ * the hook layer sees `generateImage` at all (question 2) without gating the
+ * run — the capability question (1) needs the tool to actually attempt.
+ */
+function installObservationHook(workspaceRoot: string, logPath: string): void {
+  const hooksDir = join(workspaceRoot, ".cursor");
+  mkdirSync(hooksDir, { recursive: true });
+  const scriptPath = join(hooksDir, "observe-hook.sh");
+  writeFileSync(
+    scriptPath,
+    `#!/bin/bash\nINPUT=$(cat)\nprintf '%s\\n' "$INPUT" >> "${logPath}" 2>/dev/null || true\necho '{"permission":"allow"}'\n`,
+    "utf-8",
+  );
+  chmodSync(scriptPath, 0o755);
+  writeFileSync(
+    join(hooksDir, "hooks.json"),
+    JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [{ command: scriptPath }],
+        beforeMCPExecution: [{ command: scriptPath }],
+      },
+    }),
+    "utf-8",
+  );
+}
+
+describe.skipIf(!liveSecret("CURSOR_API_KEY"))("generateImage live ground truth (issue #965)", () => {
+  it("captures whether generateImage completes headless and whether preToolUse sees it", async () => {
+    const { Agent } = await import("@cursor/sdk");
+
+    const workspaceRoot = mkdtempSync(join(tmpdir(), "stigmer-genimage-spike-"));
+    const stateRoot = join(workspaceRoot, ".sdk-state");
+    mkdirSync(stateRoot, { recursive: true });
+    const hookLog = join(workspaceRoot, "hook-invocations.jsonl");
+    installObservationHook(workspaceRoot, hookLog);
+
+    // Mirror the runner's arrangement (session-lifecycle.ts createAgent):
+    // local cwd + the "project" setting source that loads .cursor/hooks.json.
+    // The model is pinned to the incident's (aex_01m1a6ww billed composer-2.5).
+    const agent = await Agent.create({
+      apiKey: CURSOR_API_KEY,
+      model: { id: "composer-2.5" },
+      local: {
+        cwd: workspaceRoot,
+        settingSources: ["project"],
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `genimage-spike-${Date.now()}`, stateRoot }),
+      },
+    });
+
+    // The runner's exact consumption shape (index.ts / turn-stream.ts):
+    // send() registers the run; run.stream() is the event source; run.wait()
+    // is the terminal result.
+    const run = await agent.send(
+      "Use your generateImage tool to generate a simple image of a solid red " +
+        "circle on a white background and save it to red-circle.png in the " +
+        "workspace. Do not ask questions; invoke the tool directly. If the " +
+        "tool fails, state the exact error text you received and stop.",
+    );
+
+    const events: Array<Record<string, unknown>> = [];
+    for await (const event of run.stream()) {
+      const e = event as unknown as Record<string, unknown>;
+      if (e && typeof e === "object" && "type" in e) events.push(e);
+    }
+    const result = await run.wait();
+
+    // ---- Findings dump (the deliverable of this instrument) ----
+    console.log(`[genimage-spike] run status: ${result.status} (durationMs=${result.durationMs})`);
+
+    for (const ev of events) {
+      if (ev.type === "tool_call" || ev.type === "status") {
+        console.log(`[genimage-spike] event: ${JSON.stringify(ev).slice(0, 800)}`);
+      }
+    }
+    const finalAssistant = events.filter((e) => e.type === "assistant").at(-1);
+    if (finalAssistant) {
+      console.log(`[genimage-spike] final assistant: ${JSON.stringify(finalAssistant).slice(0, 800)}`);
+    }
+
+    const hookInvocations: Array<Record<string, unknown>> = [];
+    if (existsSync(hookLog)) {
+      for (const line of readFileSync(hookLog, "utf-8").split("\n")) {
+        if (!line.trim()) continue;
+        try { hookInvocations.push(JSON.parse(line)); } catch { /* partial line */ }
+      }
+    }
+    console.log(
+      `[genimage-spike] hook invocations: ${hookInvocations.length} — tool_names=` +
+        JSON.stringify(hookInvocations.map((h) => `${h.hook_event_name}:${h.tool_name}`)),
+    );
+    const hookSawGenerateImage = hookInvocations.some(
+      (h) => typeof h.tool_name === "string" && /generate.?image/i.test(h.tool_name),
+    );
+    console.log(`[genimage-spike] preToolUse saw generateImage: ${hookSawGenerateImage}`);
+
+    const imageOnDisk = readdirSync(workspaceRoot).filter((f) => f.endsWith(".png"));
+    console.log(`[genimage-spike] png files in workspace: ${JSON.stringify(imageOnDisk)}`);
+
+    // The one hard assertion: the SDK boundary itself must not hang — a
+    // terminal run outcome is required for the findings above to be trustable.
+    expect(["finished", "error", "cancelled"]).toContain(result.status);
+  }, 300_000);
+});