@stigmer/runner 3.12.3 → 3.12.5

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

@@ -0,0 +1,220 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  cacheSessionAgent,
+  closeAllCachedAgents,
+  computeAgentFingerprint,
+  evictSessionAgent,
+  takeCachedAgent,
+  _parkedAgentCountForTests,
+  _resetAgentSessionCacheForTests,
+  type CacheableAgent,
+} from "../agent-session-cache.js";
+
+function makeAgent(agentId = "agent-1"): CacheableAgent & { close: ReturnType<typeof vi.fn> } {
+  return { agentId, close: vi.fn() };
+}
+
+const FP = "fingerprint-a";
+const OTHER_FP = "fingerprint-b";
+
+describe("agent-session-cache", () => {
+  beforeEach(() => {
+    _resetAgentSessionCacheForTests();
+    delete process.env.STIGMER_CURSOR_AGENT_CACHE_TTL_MS;
+  });
+
+  afterEach(() => {
+    _resetAgentSessionCacheForTests();
+    vi.useRealTimers();
+  });
+
+  describe("checkout semantics", () => {
+    it("park then take returns the same agent without closing it", () => {
+      const agent = makeAgent();
+      cacheSessionAgent("ses-1", agent, FP);
+
+      const taken = takeCachedAgent("ses-1", FP, "agent-1");
+
+      expect(taken).toBe(agent);
+      expect(agent.close).not.toHaveBeenCalled();
+    });
+
+    it("checkout is exclusive — a second take misses", () => {
+      cacheSessionAgent("ses-1", makeAgent(), FP);
+
+      expect(takeCachedAgent("ses-1", FP, "agent-1")).toBeDefined();
+      expect(takeCachedAgent("ses-1", FP, "agent-1")).toBeUndefined();
+    });
+
+    it("an empty expectedAgentId (first-execution shape) still matches", () => {
+      const agent = makeAgent();
+      cacheSessionAgent("ses-1", agent, FP);
+
+      expect(takeCachedAgent("ses-1", FP, "")).toBe(agent);
+    });
+
+    it("misses for a different session", () => {
+      cacheSessionAgent("ses-1", makeAgent(), FP);
+
+      expect(takeCachedAgent("ses-2", FP, "agent-1")).toBeUndefined();
+      expect(_parkedAgentCountForTests()).toBe(1);
+    });
+  });
+
+  describe("reuse guards", () => {
+    it("fingerprint drift closes the parked agent and misses", () => {
+      const agent = makeAgent();
+      cacheSessionAgent("ses-1", agent, FP);
+
+      const taken = takeCachedAgent("ses-1", OTHER_FP, "agent-1");
+
+      expect(taken).toBeUndefined();
+      expect(agent.close).toHaveBeenCalledTimes(1);
+      expect(_parkedAgentCountForTests()).toBe(0);
+    });
+
+    it("agentId mismatch (harnessStateId replaced elsewhere) closes and misses", () => {
+      const agent = makeAgent("agent-old");
+      cacheSessionAgent("ses-1", agent, FP);
+
+      const taken = takeCachedAgent("ses-1", FP, "agent-new");
+
+      expect(taken).toBeUndefined();
+      expect(agent.close).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("lifetime bounds", () => {
+    it("re-parking a session closes the displaced agent", () => {
+      const first = makeAgent("agent-1");
+      const second = makeAgent("agent-2");
+      cacheSessionAgent("ses-1", first, FP);
+      cacheSessionAgent("ses-1", second, FP);
+
+      expect(first.close).toHaveBeenCalledTimes(1);
+      expect(takeCachedAgent("ses-1", FP, "agent-2")).toBe(second);
+    });
+
+    it("idle TTL evicts and closes", () => {
+      vi.useFakeTimers();
+      process.env.STIGMER_CURSOR_AGENT_CACHE_TTL_MS = "1000";
+      const agent = makeAgent();
+      cacheSessionAgent("ses-1", agent, FP);
+
+      vi.advanceTimersByTime(1001);
+
+      expect(agent.close).toHaveBeenCalledTimes(1);
+      expect(_parkedAgentCountForTests()).toBe(0);
+    });
+
+    it("checkout before the TTL fires disarms the eviction timer", () => {
+      vi.useFakeTimers();
+      process.env.STIGMER_CURSOR_AGENT_CACHE_TTL_MS = "1000";
+      const agent = makeAgent();
+      cacheSessionAgent("ses-1", agent, FP);
+
+      const taken = takeCachedAgent("ses-1", FP, "agent-1");
+      vi.advanceTimersByTime(5000);
+
+      expect(taken).toBe(agent);
+      expect(agent.close).not.toHaveBeenCalled();
+    });
+
+    it("the LRU cap closes the oldest parked agent", () => {
+      vi.useFakeTimers();
+      const first = makeAgent("agent-0");
+      cacheSessionAgent("ses-0", first, FP);
+      for (let i = 1; i < 32; i++) {
+        vi.advanceTimersByTime(1);
+        cacheSessionAgent(`ses-${i}`, makeAgent(`agent-${i}`), FP);
+      }
+
+      vi.advanceTimersByTime(1);
+      cacheSessionAgent("ses-32", makeAgent("agent-32"), FP);
+
+      expect(first.close).toHaveBeenCalledTimes(1);
+      expect(_parkedAgentCountForTests()).toBe(32);
+    });
+
+    it("an empty sessionId is never parked — the lease releases immediately", () => {
+      const agent = makeAgent();
+      cacheSessionAgent("", agent, FP);
+
+      expect(agent.close).toHaveBeenCalledTimes(1);
+      expect(_parkedAgentCountForTests()).toBe(0);
+    });
+  });
+
+  describe("explicit release", () => {
+    it("evictSessionAgent closes the parked agent", () => {
+      const agent = makeAgent();
+      cacheSessionAgent("ses-1", agent, FP);
+
+      evictSessionAgent("ses-1");
+
+      expect(agent.close).toHaveBeenCalledTimes(1);
+      expect(_parkedAgentCountForTests()).toBe(0);
+    });
+
+    it("closeAllCachedAgents closes everything (worker shutdown)", () => {
+      const a = makeAgent("agent-a");
+      const b = makeAgent("agent-b");
+      cacheSessionAgent("ses-a", a, FP);
+      cacheSessionAgent("ses-b", b, FP);
+
+      closeAllCachedAgents();
+
+      expect(a.close).toHaveBeenCalledTimes(1);
+      expect(b.close).toHaveBeenCalledTimes(1);
+      expect(_parkedAgentCountForTests()).toBe(0);
+    });
+
+    it("a close() that throws never breaks eviction", () => {
+      const agent = makeAgent();
+      agent.close.mockImplementation(() => {
+        throw new Error("already disposed");
+      });
+      cacheSessionAgent("ses-1", agent, FP);
+
+      expect(() => evictSessionAgent("ses-1")).not.toThrow();
+      expect(_parkedAgentCountForTests()).toBe(0);
+    });
+  });
+
+  describe("computeAgentFingerprint", () => {
+    const baseOptions = {
+      apiKey: "sk-secret-key",
+      model: "gpt-5",
+      modelParams: [{ key: "tier", value: "standard" }],
+      workspaceDirs: ["/workspace/app"],
+      mcpServers: { github: { command: "npx", env: { TOKEN: "t-1" } } },
+    };
+
+    it("is stable across key ordering", () => {
+      const reordered = {
+        mcpServers: { github: { env: { TOKEN: "t-1" }, command: "npx" } },
+        workspaceDirs: ["/workspace/app"],
+        modelParams: [{ key: "tier", value: "standard" }],
+        model: "gpt-5",
+        apiKey: "sk-secret-key",
+      };
+      expect(computeAgentFingerprint(baseOptions)).toBe(computeAgentFingerprint(reordered));
+    });
+
+    it("changes when any acquisition input changes", () => {
+      const base = computeAgentFingerprint(baseOptions);
+      expect(computeAgentFingerprint({ ...baseOptions, apiKey: "sk-rotated" })).not.toBe(base);
+      expect(computeAgentFingerprint({ ...baseOptions, model: "gpt-5-mini" })).not.toBe(base);
+      expect(
+        computeAgentFingerprint({
+          ...baseOptions,
+          mcpServers: { github: { command: "npx", env: { TOKEN: "t-2" } } },
+        }),
+      ).not.toBe(base);
+    });
+
+    it("never embeds the raw api key", () => {
+      expect(computeAgentFingerprint(baseOptions)).not.toContain("sk-secret-key");
+    });
+  });
+});

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -201,6 +201,56 @@ describe("buildPrompt", () => {
     expect(prompt).not.toContain("<session_context>");
   });
 
+  it("carries the declared preferences on the first execution, attributed per scope", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "created_first_execution"),
+        declaredPreferences: {
+          orgContext: "We deploy to us-east-1.",
+          userContext: "Keep answers terse.",
+        },
+      }),
+    );
+    expect(prompt).toContain("<declared_preferences>");
+    expect(prompt).toContain("Declared by the organization:\nWe deploy to us-east-1.");
+    expect(prompt).toContain("Declared by the user:\nKeep answers terse.");
+    // Preferences are CONTEXT like the bridge; the approval protocol keeps
+    // its pinned last-before-task slot.
+    expect(prompt.indexOf("<declared_preferences>"))
+      .toBeLessThan(prompt.indexOf("<tool_approval_protocol>"));
+  });
+
+  it("orders platform-declared preferences before the embedder's session context (DD-002 D3)", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "created_first_execution"),
+        declaredPreferences: { orgContext: "We deploy to us-east-1." },
+        sessionContext: "Role: platform admin",
+      }),
+    );
+    const preferences = prompt.indexOf("<declared_preferences>");
+    const context = prompt.indexOf("<session_context>");
+    expect(preferences).toBeGreaterThan(-1);
+    expect(context).toBeGreaterThan(preferences);
+  });
+
+  it("never re-sends the preferences to a successfully resumed agent — frozen per session by design (DD-002 D3)", () => {
+    const prompt = buildPrompt(
+      input({
+        resolution: resolution("local", "resumed_successfully"),
+        declaredPreferences: { orgContext: "We deploy to us-east-1." },
+      }),
+    );
+    expect(prompt).toBe(USER_MESSAGE);
+  });
+
+  it("omits the preferences section when the execution carries none", () => {
+    const prompt = buildPrompt(
+      input({ resolution: resolution("local", "created_first_execution") }),
+    );
+    expect(prompt).not.toContain("<declared_preferences>");
+  });
+
   it("uses the reinvocation prompt for a HITL reinvocation (human-meaningful, no opaque ids)", () => {
     const approvalDecisions = new Map<string, ApprovalAction>([
       ["tool-call-1", ApprovalAction.APPROVE],

package/src/activities/execute-cursor/__tests__/cursor-mcp-config.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest";
+import type { ResolvedMcpServer } from "../../../shared/mcp-resolver.js";
+import { toCursorMcpConfig, validateMcpServerEnv } from "../cursor-mcp-config.js";
+
+// Resolution behavior (enabled_tools threading, overrides scoping, the
+// transport guard) is pinned once on the single shared resolver
+// (shared/__tests__/mcp-resolver.test.ts — oss#387). These tests pin what is
+// genuinely Cursor-specific: the SDK config projection and the env pre-flight.
+
+function server(overrides: Partial<ResolvedMcpServer>): ResolvedMcpServer {
+  return {
+    slug: "github",
+    connectionType: "http",
+    url: "https://mcp.example.com/mcp",
+    toolApprovals: [],
+    pinnedToolApprovals: [],
+    discoveredCapabilitiesEmpty: false,
+    toolApprovalOverrides: [],
+    ...overrides,
+  };
+}
+
+function usage(slug: string) {
+  return { mcpServerRef: { slug, org: "test-org", kind: 0 } } as any;
+}
+
+describe("toCursorMcpConfig", () => {
+  it("projects an http server to a url config", () => {
+    const config = toCursorMcpConfig([
+      server({ headers: { Authorization: "Bearer x" } }),
+    ]);
+
+    expect(config.github).toEqual({
+      type: "http",
+      url: "https://mcp.example.com/mcp",
+      headers: { Authorization: "Bearer x" },
+    });
+  });
+
+  it("projects a stdio server to a command config", () => {
+    const config = toCursorMcpConfig([
+      server({
+        slug: "local-tool",
+        connectionType: "stdio",
+        url: undefined,
+        command: "npx",
+        args: ["-y", "tool"],
+        env: { API_KEY: "k" },
+        cwd: "/work",
+      }),
+    ]);
+
+    expect(config["local-tool"]).toEqual({
+      type: "stdio",
+      command: "npx",
+      args: ["-y", "tool"],
+      env: { API_KEY: "k" },
+      cwd: "/work",
+    });
+  });
+
+  it("skips servers missing their transport's required field", () => {
+    const config = toCursorMcpConfig([
+      server({ url: undefined }),
+      server({ slug: "no-cmd", connectionType: "stdio", url: undefined, command: undefined }),
+    ]);
+
+    expect(config).toEqual({});
+  });
+
+  it("never narrows the config for enabledTools — the SDK has no allow-list field; enforcement is the hook's disabled arm", () => {
+    const config = toCursorMcpConfig([server({ enabledTools: ["create_pr"] })]);
+
+    expect(config.github).toEqual({
+      type: "http",
+      url: "https://mcp.example.com/mcp",
+      headers: undefined,
+    });
+  });
+});
+
+describe("validateMcpServerEnv", () => {
+  it("warns for a usage whose server failed to resolve", () => {
+    const warnings = validateMcpServerEnv([], [usage("github")]);
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("'github'");
+    expect(warnings[0]).toContain("failed to resolve");
+  });
+
+  it("warns for a stdio server carrying empty env values", () => {
+    const warnings = validateMcpServerEnv(
+      [server({
+        connectionType: "stdio",
+        url: undefined,
+        command: "npx",
+        env: { API_KEY: "", OTHER: "set" },
+      })],
+      [usage("github")],
+    );
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("[API_KEY]");
+  });
+
+  it("stays quiet for healthy servers", () => {
+    const warnings = validateMcpServerEnv([server({})], [usage("github")]);
+
+    expect(warnings).toEqual([]);
+  });
+});

package/src/activities/execute-cursor/__tests__/service-tier.test.ts

@@ -19,10 +19,10 @@ vi.mock("@cursor/sdk", () => ({
 }));
 
 import {
-  resolveEffectiveServiceTier,
   resolveServiceTierParams,
   resetCatalogCacheForTests,
 } from "../service-tier.js";
+import { resolveEffectiveServiceTier } from "../../../shared/service-tier.js";
 
 const CATALOG = [
   {

package/src/activities/execute-cursor/__tests__/skill-resolver.test.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync } from "no
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { ConnectError, Code } from "@connectrpc/connect";
-import { resolveSkills, downloadArtifact } from "../skill-resolver.js";
+import { resolveSkills } from "../skill-resolver.js";
 import { buildZip } from "../../../__test-utils__/zip-fixtures.js";
 
 /** A server that predates the transfer lane (#675) answers the mint RPC
@@ -390,96 +390,5 @@ describe("resolveSkills — artifact extraction", () => {
   });
 });
 
-// ─── downloadArtifact — transfer lane routing (#675) ─────────────────────
-
-describe("downloadArtifact — transfer lane routing", () => {
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  function makeClient(overrides: Record<string, any> = {}) {
-    return {
-      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: new Uint8Array(0) }),
-      getSkillArtifactDownloadUrl: unimplementedMint(),
-      ...overrides,
-    } as any;
-  }
-
-  it("fetches bytes over HTTP when the server mints a download URL", async () => {
-    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
-    const client = makeClient({
-      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
-        url: "http://localhost:7234/v1/skill-artifacts/skills/abc.zip",
-        sizeBytes: 5n,
-        ttlSeconds: 0,
-      }),
-    });
-    const fetchMock = vi.fn().mockResolvedValue({
-      ok: true,
-      arrayBuffer: async () => bytes.buffer,
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const got = await downloadArtifact(client, "skills/abc.zip");
-
-    expect(got).toEqual(bytes);
-    expect(fetchMock).toHaveBeenCalledWith("http://localhost:7234/v1/skill-artifacts/skills/abc.zip");
-    // The unary lane (10MB-capped) must not be touched when the URL lane works.
-    expect(client.getSkillArtifact).not.toHaveBeenCalled();
-  });
-
-  it("falls back to the unary RPC when the server predates the lane", async () => {
-    const bytes = new Uint8Array([9, 9]);
-    const client = makeClient({
-      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: bytes }),
-    });
-    vi.stubGlobal("fetch", vi.fn()); // must never be called
-
-    const got = await downloadArtifact(client, "skills/abc.zip");
-
-    expect(got).toEqual(bytes);
-    expect(client.getSkillArtifact).toHaveBeenCalledWith("skills/abc.zip");
-    expect(fetch).not.toHaveBeenCalled();
-  });
-
-  it("does NOT fall back on non-Unimplemented mint failures", async () => {
-    const client = makeClient({
-      getSkillArtifactDownloadUrl: vi.fn().mockRejectedValue(
-        new ConnectError("boom", Code.Internal),
-      ),
-    });
-
-    await expect(downloadArtifact(client, "skills/abc.zip")).rejects.toThrow("boom");
-    // Falling back here would mask real server faults behind the capped lane.
-    expect(client.getSkillArtifact).not.toHaveBeenCalled();
-  });
-
-  it("rejects truncated fetches via the minted size", async () => {
-    const client = makeClient({
-      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
-        url: "http://localhost:7234/v1/skill-artifacts/skills/abc.zip",
-        sizeBytes: 100n,
-        ttlSeconds: 0,
-      }),
-    });
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
-      ok: true,
-      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
-    }));
-
-    await expect(downloadArtifact(client, "skills/abc.zip")).rejects.toThrow(/truncated/);
-  });
-
-  it("surfaces HTTP failures with the status code", async () => {
-    const client = makeClient({
-      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
-        url: "http://localhost:7234/v1/skill-artifacts/skills/gone.zip",
-        sizeBytes: 0n,
-        ttlSeconds: 0,
-      }),
-    });
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: false, status: 404 }));
-
-    await expect(downloadArtifact(client, "skills/gone.zip")).rejects.toThrow(/HTTP 404/);
-  });
-});
+// downloadArtifact's transfer-lane routing tests moved with the code to
+// shared/__tests__/skill-mount.test.ts (issue #337 extraction).