@stigmer/runner 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

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

@@ -41,14 +41,15 @@ describeWithCursorKey("SDK routing with CURSOR_BACKEND_URL unset", () => {
     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: "claude-sonnet-4" },
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `routing-test-${Date.now()}`,
-        stateRoot,
+      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 }),
       },
     });
 
@@ -62,14 +63,15 @@ describeWithCursorKey("SDK routing with CURSOR_BACKEND_URL unset", () => {
     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: "claude-sonnet-4" },
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `routing-send-test-${Date.now()}`,
-        stateRoot,
+      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 }),
       },
     });
 

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.test.ts

@@ -1,11 +1,22 @@
 /**
- * Test that reproduces the desktop runner's EXACT execution path.
+ * 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).
  *
- * Simulates proxy mode: fetch interceptor installed, apiKey="proxy-managed",
- * to verify whether the proxy rewriting actually intercepts @cursor/sdk calls.
+ * 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).
  *
- * Expected result: THIS TEST WILL FAIL because @cursor/sdk uses connect-node
- * (Node.js native HTTP), not globalThis.fetch. The fetch interceptor never fires.
+ * 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.
+ *
+ * Skipped without `CURSOR_API_KEY`; the suite never runs it. Run it by hand:
+ *   CURSOR_API_KEY=<key> npx vitest run src/activities/execute-cursor/__tests__/cursor-fetch-interceptor-bypass.test.ts
  */
 
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
@@ -39,26 +50,27 @@ describeWithCursorKey("Fetch Interceptor vs Connect-Node Transport", () => {
     globalThis.fetch = originalFetch;
   });
 
-  it("Agent.create() does NOT go through globalThis.fetch (proving interceptor is useless)", async () => {
+  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 },
-      platform: {
-        workspaceRef: `intercept-test-${Date.now()}`,
-        stateRoot,
+      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}`);
 
-    // This assertion proves the fetch interceptor pattern is broken:
-    // connect-node uses Node.js http module, NOT globalThis.fetch
+    // 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

@@ -35,6 +35,7 @@
  */
 
 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";
@@ -87,8 +88,12 @@ describeWithCursorKey("generateImage live ground truth (issue #965)", () => {
     const agent = await Agent.create({
       apiKey: CURSOR_API_KEY,
       model: { id: "composer-2.5" },
-      local: { cwd: workspaceRoot, settingSources: ["project"] },
-      platform: { workspaceRef: `genimage-spike-${Date.now()}`, stateRoot },
+      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):

package/src/activities/execute-cursor/__tests__/cursor-hook-protocol-live.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Live ground truth for the hook protocol the approval gate rides on — the
+ * standing instrument an `@cursor/sdk` bump runs before it is trusted
+ * (stigmer/stigmer#1053, the first bump; every later one inherits this).
+ *
+ * WHY THIS EXISTS. The Stigmer HITL gate on the Cursor harness is a
+ * `.cursor/hooks.json` `preToolUse` hook (`hook-script.ts`) that reads the
+ * SDK's stdin payload and answers `{"permission": "allow" | "deny"}`. Three
+ * facts about that payload are load-bearing and none is a TypeScript type:
+ *
+ *  1. `tool_name` is the HOOK taxonomy, PascalCase (`Write`, `Shell`, `Delete`;
+ *     the stream taxonomy is lowercase `edit`, `shell`, `delete`) — the gated
+ *     set `BUILT_IN_GATED` (`approval-policy.ts`) is spelled in it.
+ *  2. `tool_input` is an OBJECT for built-in tools (a JSON STRING for MCP
+ *     tools under `beforeMCPExecution`) — the hook's identity token and the
+ *     denial ledger's captured args are computed from it.
+ *  3. `hook_event_name` discriminates `preToolUse` from `beforeMCPExecution`.
+ *
+ * The hermetic tests prove the runner's handling of the shapes CAPTURED at
+ * 1.0.13 (`cursor-hook-harness.ts` `hookWrite`, `hookShell`, ...). They cannot
+ * see the SDK move. This test runs one real turn that edits a file and runs a
+ * shell command under an allow-everything observation hook, then asserts the
+ * three facts on what the real SDK sent. A `tool_name` outside the gated set
+ * for a write-, shell- or delete-class action is the one outcome that must
+ * stop a bump: the gate would let it through.
+ *
+ * Skipped without CURSOR_API_KEY (the cursor-sdk-auth-smoke.test.ts
+ * convention) — it spends real credits for one short turn. Findings are
+ * PRINTED as well as asserted, so a bump's PR can quote the shapes seen.
+ *
+ * Run with: CURSOR_API_KEY=<key> npx vitest run cursor-hook-protocol-live
+ */
+import { describe, it, expect } from "vitest";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { approvalCategory } from "../approval-policy.js";
+
+const CURSOR_API_KEY = process.env.CURSOR_API_KEY ?? "";
+const describeWithCursorKey = CURSOR_API_KEY ? describe : describe.skip;
+
+/** One hook invocation as the SDK wrote it to the hook's stdin. */
+interface HookInvocation {
+  readonly hook_event_name?: unknown;
+  readonly tool_name?: unknown;
+  readonly tool_input?: unknown;
+}
+
+/**
+ * An observation-only preToolUse/beforeMCPExecution hook: appends every
+ * invocation's stdin JSON to a log file and ALLOWS everything, so the turn
+ * runs to completion and every gated action is seen exactly as the gate would
+ * see it.
+ */
+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",
+  );
+}
+
+function readInvocations(logPath: string): HookInvocation[] {
+  if (!existsSync(logPath)) return [];
+  const invocations: HookInvocation[] = [];
+  for (const line of readFileSync(logPath, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      invocations.push(JSON.parse(line) as HookInvocation);
+    } catch {
+      /* a partial line from a hook the SDK cut off; nothing to read */
+    }
+  }
+  return invocations;
+}
+
+describeWithCursorKey("Cursor SDK hook protocol (live ground truth)", () => {
+  it("delivers PascalCase tool_name, an object tool_input and hook_event_name for a file edit and a shell command", async () => {
+    const { Agent } = await import("@cursor/sdk");
+    const { SqliteLocalAgentStore } = await import("@cursor/sdk/sqlite");
+
+    const workspaceRoot = mkdtempSync(join(tmpdir(), "stigmer-hook-protocol-"));
+    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): local cwd, the
+    // "project" setting source that loads .cursor/hooks.json, the session's
+    // own store, the SDK's retries off.
+    const agent = await Agent.create({
+      apiKey: CURSOR_API_KEY,
+      model: { id: "composer-2.5" },
+      local: {
+        cwd: workspaceRoot,
+        settingSources: ["project"],
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `hook-protocol-${Date.now()}`, stateRoot }),
+        enableAgentRetries: false,
+      },
+    });
+
+    const run = await agent.send(
+      "Do exactly two things, in order, without asking questions: " +
+        "(1) create a file named probe.txt in the workspace containing the single line 'hook probe'; " +
+        "(2) run the shell command `cat probe.txt`. Then reply with the word done.",
+    );
+    for await (const _event of run.stream()) {
+      /* drain: the hook log is the evidence, not the stream */
+    }
+    const result = await run.wait();
+    agent.close();
+
+    const invocations = readInvocations(hookLog);
+
+    // ---- Findings dump (what a bump's PR quotes) ----
+    console.log(`[hook-protocol] run status: ${result.status}`);
+    for (const inv of invocations) {
+      console.log(
+        `[hook-protocol] ${String(inv.hook_event_name)}:${String(inv.tool_name)} ` +
+          `tool_input=${typeof inv.tool_input} ${JSON.stringify(inv.tool_input).slice(0, 200)}`,
+      );
+    }
+
+    // The SDK boundary must not hang, and the turn must have reached the hook.
+    expect(["finished", "error", "cancelled"]).toContain(result.status);
+    expect(invocations.length, "the observation hook saw no tool call — hooks.json was not loaded").toBeGreaterThan(0);
+
+    const builtIns = invocations.filter((inv) => inv.hook_event_name === "preToolUse");
+    expect(builtIns.length, "no preToolUse invocation: the built-in tools did not reach the hook").toBeGreaterThan(0);
+    for (const inv of builtIns) {
+      // Fact 3: the discriminator is present and spelled as the script branches on it.
+      expect(inv.hook_event_name).toBe("preToolUse");
+      // Fact 1: the hook taxonomy is PascalCase.
+      expect(typeof inv.tool_name).toBe("string");
+      expect(inv.tool_name as string).toMatch(/^[A-Z]/);
+      // Fact 2: built-in tool_input is an object, not a JSON string.
+      expect(typeof inv.tool_input).toBe("object");
+      expect(inv.tool_input).not.toBeNull();
+    }
+
+    // The gate's reach: the write and the shell the prompt forced must have
+    // arrived under names the gate classifies. A write- or shell-class action
+    // under an unclassified name is the outcome that stops a bump.
+    const categories = builtIns.map((inv) => approvalCategory(inv.tool_name as string));
+    expect(categories, "the file write reached the hook under a name the gate classifies as write").toContain("write");
+    expect(categories, "the shell command reached the hook under a name the gate classifies as shell").toContain("shell");
+  }, 300_000);
+});

package/src/activities/execute-cursor/__tests__/cursor-sdk-auth-smoke.test.ts

@@ -1,17 +1,20 @@
 /**
- * Minimal smoke test to verify Cursor SDK authentication works with a real API key.
+ * Live smoke: the Cursor SDK authenticates and completes a round trip on a
+ * real member key. Three arms, each isolating one fact:
+ *  1. `Agent.create()` with a model named succeeds — the key is valid;
+ *  2. `agent.send()` runs to a completed result — the agent executes and the
+ *     transport completes the round trip;
+ *  3. `Agent.create()` with no model named succeeds — the catalog default
+ *     resolves.
  *
- * Tests three things in isolation:
- * 1. Agent.create() succeeds (proves the API key is valid)
- * 2. agent.send() produces a response (proves the agent can execute)
- * 3. The connect-node transport works end-to-end
- *
- * Run with: CURSOR_API_KEY=<key> npx tsx --test this-file.ts
- * Or via the test script: npm run test:cursor-auth
+ * Skipped without `CURSOR_API_KEY`; the suite never runs it. Run it by hand:
+ *   CURSOR_API_KEY=<key> npx vitest run src/activities/execute-cursor/__tests__/cursor-sdk-auth-smoke.test.ts
+ * Last run green 3/3 on 2026-09-16 at SDK 1.0.31 (#1097's live run).
  */
 
 import { describe, it, expect } from "vitest";
 import { Agent } from "@cursor/sdk";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -31,10 +34,10 @@ describeWithCursorKey("Cursor SDK Authentication Smoke Test", () => {
     const agent = await Agent.create({
       apiKey: CURSOR_API_KEY,
       model: { id: "claude-sonnet-4" },
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `auth-test-${Date.now()}`,
-        stateRoot,
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `auth-test-${Date.now()}`, stateRoot }),
       },
     });
 
@@ -50,10 +53,10 @@ describeWithCursorKey("Cursor SDK Authentication Smoke Test", () => {
     const agent = await Agent.create({
       apiKey: CURSOR_API_KEY,
       model: { id: "claude-sonnet-4" },
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `send-test-${Date.now()}`,
-        stateRoot,
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `send-test-${Date.now()}`, stateRoot }),
       },
     });
 
@@ -76,10 +79,10 @@ describeWithCursorKey("Cursor SDK Authentication Smoke Test", () => {
 
     const agent = await Agent.create({
       apiKey: CURSOR_API_KEY,
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `default-model-test-${Date.now()}`,
-        stateRoot,
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `default-model-test-${Date.now()}`, stateRoot }),
       },
     });