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

package/src/activities/execute-cursor/__tests__/session-lifecycle.test.ts

@@ -1,10 +1,15 @@
 /**
- * Unit tests for resolvePlatformOptions — the Cursor SDK stateRoot derivation.
+ * Unit tests for the local agent's create/resume options and the
+ * transport-recovery wrapper (`session-lifecycle.ts`).
  *
- * stateRoot is keyed by sessionId and rooted at the durable workspace volume so
- * native Agent.resume() survives restart/snapshot-restore and so sessions that
- * share one volume (e.g. a workflow sandbox's child agent executions) never
- * collide. These invariants are correctness-critical, hence the explicit tests.
+ * The SDK module is a `vi.fn` stub so the assertions read the exact options
+ * the adapter hands `Agent.create` / `Agent.resume`. The SDK's sqlite entry is
+ * NOT mocked here on purpose: `createAgent` opens the session's REAL
+ * `SqliteLocalAgentStore` (`node:sqlite`, no network) under a temp workspace
+ * volume, so this file is also where the store the runner ships with is
+ * proven to open, be reused, and dispose — the hermetic goldens double it.
+ * The store's keying and lifetime rules have their own arms in
+ * `session-store.test.ts`.
  */
 
 import { describe, it, expect, afterEach, vi } from "vitest";
@@ -20,13 +25,15 @@ vi.mock("@cursor/sdk", () => ({
 }));
 
 import { Agent } from "@cursor/sdk";
+import type { AgentOptions } from "@cursor/sdk";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
 import {
-  resolvePlatformOptions,
   createAgent,
   resumeAgent,
   resolveAgentWithTransportRecovery,
 } from "../session-lifecycle.js";
 import type { CreateAgentOptions } from "../session-lifecycle.js";
+import { releaseAllSessionStores } from "../session-store.js";
 
 const tempRoots: string[] = [];
 
@@ -36,50 +43,25 @@ function freshWorkspaceRoot(): string {
   return dir;
 }
 
-afterEach(() => {
+afterEach(async () => {
+  // Release every store before its directory goes, so the sqlite handles are
+  // closed when the temp roots are removed (and no test inherits a store).
+  await releaseAllSessionStores();
   for (const dir of tempRoots.splice(0)) {
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
-describe("resolvePlatformOptions", () => {
-  it("derives stateRoot under the workspace volume (not $HOME)", () => {
-    const workspaceRootDir = freshWorkspaceRoot();
-    const opts = resolvePlatformOptions("ses-123", workspaceRootDir);
-
-    expect(opts.stateRoot).toBe(
-      join(workspaceRootDir, ".stigmer", "cursor-sdk-state", "ses-123"),
-    );
-    expect(opts.stateRoot.startsWith(workspaceRootDir)).toBe(true);
-    // Created eagerly to prevent ENOENT on first SDK write.
-    expect(existsSync(opts.stateRoot!)).toBe(true);
-    expect(opts.workspaceRef).toBe("stigmer-session:ses-123");
-  });
-
-  it("isolates two sessions sharing one workspace volume into distinct stores", () => {
-    const workspaceRootDir = freshWorkspaceRoot();
-    const a = resolvePlatformOptions("ses-aaa", workspaceRootDir);
-    const b = resolvePlatformOptions("ses-bbb", workspaceRootDir);
-
-    expect(a.stateRoot).not.toBe(b.stateRoot);
-    expect(a.workspaceRef).not.toBe(b.workspaceRef);
-    // Both live under the same shared volume but in session-keyed subdirs.
-    expect(a.stateRoot!.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
-    expect(b.stateRoot!.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
-  });
-
-  it("throws on an empty sessionId (would collide across sessions on a shared volume)", () => {
-    const workspaceRootDir = freshWorkspaceRoot();
-    expect(() => resolvePlatformOptions("", workspaceRootDir)).toThrow(/sessionId is required/);
-  });
+function lastCreateOptions(): AgentOptions {
+  return vi.mocked(Agent.create).mock.calls.at(-1)![0];
+}
 
-  it("throws on an empty workspaceRootDir (state must live on the durable volume)", () => {
-    expect(() => resolvePlatformOptions("ses-123", "")).toThrow(/workspaceRootDir is required/);
-  });
-});
+function lastResumeCall(): [string, Partial<AgentOptions> | undefined] {
+  return vi.mocked(Agent.resume).mock.calls.at(-1)! as [string, Partial<AgentOptions> | undefined];
+}
 
 // ---------------------------------------------------------------------------
-// Workspace binding across create/resume
+// The local options across create/resume
 //
 // Regression: Agent.resume() does not persist local.cwd. When resumeAgent()
 // omitted it, the SDK fell back to process.cwd() — re-rooting the resumed
@@ -87,17 +69,33 @@ describe("resolvePlatformOptions", () => {
 // setting source (the .cursor/hooks.json carrying the HITL approval hook)
 // from that wrong directory. Result: on every resumed turn, file edits and
 // shell commands ran unguarded with no approval card (observed in production
-// execution aex_01ktr5na07f5xtmn0dz3mfjtdp).
+// execution aex_01ktr5na07f5xtmn0dz3mfjtdp). The same rule now covers the
+// store (#1053): a resume without it would look the agent up in a default
+// store derived from cwd, not the one the session's records are in.
 // ---------------------------------------------------------------------------
 
-describe("workspace binding on create/resume", () => {
+describe("local options on create/resume", () => {
   const baseOptions = {
     apiKey: "key",
     sessionId: "ses-cwd-test",
     model: "gpt-test",
   };
 
-  it("createAgent passes the single workspace dir as local.cwd", async () => {
+  it("createAgent passes the single workspace dir as local.cwd, with no dirs", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    await createAgent({
+      ...baseOptions,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    const { local } = lastCreateOptions();
+    expect(local?.cwd).toBe("/work/repo-a");
+    expect(local).not.toHaveProperty("dirs");
+    expect(local?.settingSources).toContain("project");
+  });
+
+  it("createAgent opens the session's real SQLite store under the workspace volume and passes it as local.store", async () => {
     const workspaceRootDir = freshWorkspaceRoot();
     await createAgent({
       ...baseOptions,
@@ -105,13 +103,37 @@ describe("workspace binding on create/resume", () => {
       workspaceRootDir,
     });
 
-    const callOptions = vi.mocked(Agent.create).mock.calls.at(-1)![0] as any;
-    expect(callOptions.local.cwd).toBe("/work/repo-a");
-    expect(callOptions.local.settingSources).toContain("project");
+    const store = lastCreateOptions().local?.store;
+    expect(store).toBeInstanceOf(SqliteLocalAgentStore);
+    const sqlite = store as SqliteLocalAgentStore;
+    expect(sqlite.workspaceRef).toBe("stigmer-session:ses-cwd-test");
+    expect(sqlite.stateRoot).toBe(join(workspaceRootDir, ".stigmer", "cursor-sdk-state", "ses-cwd-test"));
+    // The SDK's layout lands where the runner said, not under $HOME.
+    expect(existsSync(sqlite.stateRoot)).toBe(true);
   });
 
-  it("resumeAgent re-supplies local.cwd (not persisted by Agent.resume)", async () => {
+  it("createAgent pins the SDK's own retries off (the runner is the retry authority)", async () => {
     const workspaceRootDir = freshWorkspaceRoot();
+    await createAgent({
+      ...baseOptions,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    // 1.0.31 defaults this to true for headless embedders; an absent field
+    // would silently stack the SDK's transport retries under the runner's.
+    expect(lastCreateOptions().local?.enableAgentRetries).toBe(false);
+  });
+
+  it("resumeAgent re-supplies cwd, settingSources, store and the retry pin (nothing under local survives Agent.resume)", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    await createAgent({
+      ...baseOptions,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+    const createdWith = lastCreateOptions().local?.store;
+
     await resumeAgent({
       ...baseOptions,
       agentId: "agent-123",
@@ -119,25 +141,31 @@ describe("workspace binding on create/resume", () => {
       workspaceRootDir,
     });
 
-    const [agentId, callOptions] = vi.mocked(Agent.resume).mock.calls.at(-1)! as [string, any];
+    const [agentId, callOptions] = lastResumeCall();
     expect(agentId).toBe("agent-123");
-    // The load-bearing assertion: without cwd the SDK re-roots the agent at
-    // process.cwd() and the project HITL hook never loads on resumed turns.
-    expect(callOptions.local.cwd).toBe("/work/repo-a");
-    expect(callOptions.local.settingSources).toContain("project");
+    // The load-bearing assertions: without cwd the SDK re-roots the agent at
+    // process.cwd() and the project HITL hook never loads on resumed turns;
+    // without the SAME store it looks the agent up somewhere else.
+    expect(callOptions?.local?.cwd).toBe("/work/repo-a");
+    expect(callOptions?.local?.settingSources).toContain("project");
+    expect(callOptions?.local?.store).toBe(createdWith);
+    expect(callOptions?.local?.enableAgentRetries).toBe(false);
   });
 
-  it("resumeAgent passes multiple workspace dirs as an array cwd", async () => {
+  it("passes a multi-root workspace as cwd (the first dir) plus dirs (the rest)", async () => {
     const workspaceRootDir = freshWorkspaceRoot();
     await resumeAgent({
       ...baseOptions,
       agentId: "agent-456",
-      workspaceDirs: ["/work/repo-a", "/work/repo-b"],
+      workspaceDirs: ["/work/repo-a", "/work/repo-b", "/work/repo-c"],
       workspaceRootDir,
     });
 
-    const callOptions = vi.mocked(Agent.resume).mock.calls.at(-1)![1] as any;
-    expect(callOptions.local.cwd).toEqual(["/work/repo-a", "/work/repo-b"]);
+    const [, callOptions] = lastResumeCall();
+    // The SDK merges cwd-first with duplicates dropped, so this is the array
+    // the SDK took whole at 1.0.13, in the same order.
+    expect(callOptions?.local?.cwd).toBe("/work/repo-a");
+    expect(callOptions?.local?.dirs).toEqual(["/work/repo-b", "/work/repo-c"]);
   });
 });
 

package/src/activities/execute-cursor/__tests__/session-store.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Unit tests for `session-store.ts`: where a session's Cursor SDK store lives,
+ * and the lifetime the runner owns for it (stigmer/stigmer#1053).
+ *
+ * The location rules are correctness-critical: the state root is keyed by
+ * sessionId and rooted at the durable workspace volume so native
+ * Agent.resume() survives restart/snapshot-restore and so sessions that share
+ * one volume (a workflow sandbox's child agent executions) never collide.
+ *
+ * The lifetime rules are what a revert of the adapter's release hooks would
+ * break: one open per session however many activities ask, the SAME instance
+ * on every ask, a release that disposes and forgets so the next ask reopens, a
+ * failed open that is not remembered, and a re-acquire under a different root
+ * that releases the store it held. `SessionStores` takes the opener, so these
+ * run against a recording fake and no SQLite file.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { SessionStores, resolveSessionStoreLocation, type ReleasableStore, type SessionStoreLocation } from "../session-store.js";
+
+const tempRoots: string[] = [];
+
+function freshWorkspaceRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "stigmer-session-store-test-"));
+  tempRoots.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempRoots.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("resolveSessionStoreLocation", () => {
+  it("derives the state root under the workspace volume (not $HOME), created eagerly", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const location = resolveSessionStoreLocation("ses-123", workspaceRootDir);
+
+    expect(location.stateRoot).toBe(join(workspaceRootDir, ".stigmer", "cursor-sdk-state", "ses-123"));
+    expect(location.stateRoot.startsWith(workspaceRootDir)).toBe(true);
+    // Created eagerly to prevent ENOENT on the SDK's first write.
+    expect(existsSync(location.stateRoot)).toBe(true);
+    expect(location.workspaceRef).toBe("stigmer-session:ses-123");
+  });
+
+  it("isolates two sessions sharing one workspace volume into distinct stores", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const a = resolveSessionStoreLocation("ses-aaa", workspaceRootDir);
+    const b = resolveSessionStoreLocation("ses-bbb", workspaceRootDir);
+
+    expect(a.stateRoot).not.toBe(b.stateRoot);
+    expect(a.workspaceRef).not.toBe(b.workspaceRef);
+    expect(a.stateRoot.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
+    expect(b.stateRoot.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
+  });
+
+  it("throws on an empty sessionId (would collide across sessions on a shared volume)", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    expect(() => resolveSessionStoreLocation("", workspaceRootDir)).toThrow(/sessionId is required/);
+  });
+
+  it("throws on an empty workspaceRootDir (state must live on the durable volume)", () => {
+    expect(() => resolveSessionStoreLocation("ses-123", "")).toThrow(/workspaceRootDir is required/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The lifetime
+// ---------------------------------------------------------------------------
+
+class FakeStore implements ReleasableStore {
+  disposeCalls = 0;
+  constructor(readonly location: SessionStoreLocation) {}
+  get stateRoot(): string {
+    return this.location.stateRoot;
+  }
+  async dispose(): Promise<void> {
+    this.disposeCalls++;
+  }
+}
+
+/** A recording opener; `failNext` makes the next open reject once. */
+function recordingOpener() {
+  const opened: FakeStore[] = [];
+  let failNext: Error | undefined;
+  const open = async (location: SessionStoreLocation): Promise<FakeStore> => {
+    if (failNext) {
+      const err = failNext;
+      failNext = undefined;
+      throw err;
+    }
+    const store = new FakeStore(location);
+    opened.push(store);
+    return store;
+  };
+  return { open, opened, fail: (err: Error) => (failNext = err) };
+}
+
+describe("SessionStores", () => {
+  it("opens once per session and hands the same instance to every later acquire, concurrent ones included", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    // Two activities racing on one session (the agent cache's documented race).
+    const [a, b] = await Promise.all([
+      stores.acquire("ses-1", workspaceRootDir),
+      stores.acquire("ses-1", workspaceRootDir),
+    ]);
+    const c = await stores.acquire("ses-1", workspaceRootDir);
+
+    expect(opened).toHaveLength(1);
+    expect(a).toBe(b);
+    expect(b).toBe(c);
+    expect(a.location.workspaceRef).toBe("stigmer-session:ses-1");
+    expect(stores.size).toBe(1);
+  });
+
+  it("keeps one store per session, not one per process", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    const a = await stores.acquire("ses-a", workspaceRootDir);
+    const b = await stores.acquire("ses-b", workspaceRootDir);
+
+    expect(opened).toHaveLength(2);
+    expect(a).not.toBe(b);
+    expect(stores.size).toBe(2);
+  });
+
+  it("release disposes the session's store and forgets it, so a later acquire reopens", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    const first = await stores.acquire("ses-1", workspaceRootDir);
+    await stores.release("ses-1");
+
+    expect(first.disposeCalls).toBe(1);
+    expect(stores.size).toBe(0);
+
+    const second = await stores.acquire("ses-1", workspaceRootDir);
+    expect(second).not.toBe(first);
+    expect(opened).toHaveLength(2);
+  });
+
+  it("release of a session with no store is a no-op", async () => {
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    await expect(stores.release("ses-unknown")).resolves.toBeUndefined();
+    expect(opened).toHaveLength(0);
+  });
+
+  it("releaseAll disposes every held store and empties the map (worker shutdown)", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    await stores.acquire("ses-a", workspaceRootDir);
+    await stores.acquire("ses-b", workspaceRootDir);
+    await stores.releaseAll();
+
+    expect(opened.map((s) => s.disposeCalls)).toEqual([1, 1]);
+    expect(stores.size).toBe(0);
+  });
+
+  it("does not remember a failed open: the next acquire retries", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened, fail } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    fail(new Error("disk full"));
+    await expect(stores.acquire("ses-1", workspaceRootDir)).rejects.toThrow("disk full");
+    expect(stores.size).toBe(0);
+
+    const store = await stores.acquire("ses-1", workspaceRootDir);
+    expect(opened).toEqual([store]);
+    expect(stores.size).toBe(1);
+  });
+
+  it("a re-acquire under a different workspace volume releases the held store and opens the new one", async () => {
+    const rootA = freshWorkspaceRoot();
+    const rootB = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    const onA = await stores.acquire("ses-1", rootA);
+    const onB = await stores.acquire("ses-1", rootB);
+
+    // The handle for the old binding can never serve the new one (the same
+    // rule the agent cache applies to a fingerprint mismatch).
+    expect(onB).not.toBe(onA);
+    expect(onA.disposeCalls).toBe(1);
+    expect(onB.stateRoot.startsWith(rootB)).toBe(true);
+    expect(opened).toHaveLength(2);
+    expect(stores.size).toBe(1);
+  });
+
+  it("a dispose that throws is swallowed: the store is forgotten either way", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const stores = new SessionStores(async (location) => {
+      const store = new FakeStore(location);
+      store.dispose = async () => {
+        throw new Error("handle already closed");
+      };
+      return store;
+    });
+
+    await stores.acquire("ses-1", workspaceRootDir);
+    await expect(stores.release("ses-1")).resolves.toBeUndefined();
+    expect(stores.size).toBe(0);
+  });
+});

package/src/activities/execute-cursor/__tests__/tool-result-image.test.ts

@@ -23,7 +23,7 @@
  * shape) is guarded in shared/__tests__/status-offload.
  */
 
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect } from "vitest";
 import { create } from "@bufbuild/protobuf";
 import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
@@ -33,13 +33,8 @@ import {
   offloadOversizedToolOutputs,
   detectImagePayload,
 } from "../../../shared/status-offload.js";
-import {
-  toResultString,
-  canonicalizeImageResult,
-  buildToolCallProto,
-  MessageAccumulator,
-} from "../message-translator.js";
-import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { toResultString, canonicalizeImageResult } from "../tool-result.js";
+import { foldCursorEvents } from "../__test-utils__/fold.js";
 
 // PNG signature + a little payload. PNG_BYTES is how the Cursor SDK delivers
 // image data at runtime (Node Buffer-JSON); PNG_BASE64 is its base64 form, used
@@ -143,7 +138,7 @@ describe("toResultString", () => {
   });
 });
 
-describe("buildToolCallProto image normalization", () => {
+describe("stream row image normalization (through the translator and the builder)", () => {
   it("produces a result the shared offload detector recognizes as an image", () => {
     const event = {
       type: "tool_call",
@@ -156,7 +151,7 @@ describe("buildToolCallProto image normalization", () => {
       result: cursorImageEnvelope(),
     } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
 
-    const tc = buildToolCallProto(event);
+    const tc = foldCursorEvents([event]).rows()[0];
     expect(tc.name).toBe("get_app_state");
     const img = detectImagePayload(tc.result);
     expect(img).not.toBeNull();
@@ -188,7 +183,7 @@ describe("cursor image flows through the persist-time offload", () => {
       result: cursorImageEnvelope(),
     } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
 
-    const tc = buildToolCallProto(event);
+    const tc = foldCursorEvents([event]).rows()[0];
     const status = create(AgentExecutionStatusSchema, {
       messages: [create(AgentMessageSchema, { toolCalls: [tc] })],
     });
@@ -207,11 +202,8 @@ describe("cursor image flows through the persist-time offload", () => {
   });
 });
 
-describe("sub-agent image normalization (extractConversationSteps)", () => {
+describe("sub-agent image normalization (sub-agent-steps)", () => {
   it("normalizes a screenshot returned inside a sub-agent toolCall step", () => {
-    const messages: AgentMessage[] = [];
-    const acc = new MessageAccumulator(messages);
-
     const running = {
       type: "tool_call",
       agent_id: "a1",
@@ -221,9 +213,6 @@ describe("sub-agent image normalization (extractConversationSteps)", () => {
       status: "running",
       args: { description: "screenshot", prompt: "capture" },
     } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
-    acc.processEvent(running);
-    acc.trackSubAgentExecution(running);
-
     const completed = {
       type: "tool_call",
       agent_id: "a1",
@@ -254,10 +243,7 @@ describe("sub-agent image normalization (extractConversationSteps)", () => {
       },
     } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
 
-    acc.processEvent(completed);
-    acc.trackSubAgentExecution(completed);
-
-    const sub = acc.subAgentExecutions[0];
+    const sub = foldCursorEvents([running, completed]).status.subAgentExecutions[0];
     const subToolResult = sub.messages[0].toolCalls[0].result;
     const img = detectImagePayload(subToolResult);
     expect(img?.base64).toBe(PNG_BASE64);