@stigmer/runner 3.14.1 → 3.15.0

package/src/__test-utils__/turn-input-fixture.ts

@@ -0,0 +1,155 @@
+/**
+ * A whole `TurnInput` for tests that stand in for the runtime.
+ *
+ * The contract's input is the runtime's entire resolved record (`harness/
+ * types.ts`): the execution and session protos, the blueprint, the
+ * environment, the workspace, the tool surface, the attachments, the model
+ * preferences, the standing context. A test that drives an adapter WITHOUT
+ * the runtime — the harness contract kit's `ExecutionDriver`, a unit test of
+ * one adapter step — needs a record that type-checks and is inert: empty
+ * protos, an empty tool surface, a workspace under the OS temp dir, a memory
+ * selection that answers nothing. Everything here is the neutral value;
+ * `overrides` deep-merges one level (a test states the fields it is about
+ * and nothing else), the way `testConfig()` does for `Config`.
+ *
+ * Nothing here is Cursor's or native's: the vision profile, the file-review
+ * identity and the state id source are the ADAPTER's capabilities, not
+ * input facts, so they do not appear.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  AgentExecutionSchema,
+  type AgentExecution,
+  type AgentExecutionStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SessionSchema, type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+import type { TurnInput } from "../harness/types.js";
+import type { ResolvedBlueprint } from "../shared/blueprint-resolver.js";
+import { mockWorkspaceBackend } from "./mock-workspace.js";
+
+/** The ids a fixture record carries when a test does not name its own. */
+export const TURN_INPUT_FIXTURE_IDS = {
+  executionId: "aex_fixture_0001",
+  sessionId: "ses_fixture_0001",
+  agentId: "agt_fixture_0001",
+  org: "fixture-org",
+} as const;
+
+export interface TurnInputFixtureOverrides extends Partial<Omit<TurnInput, "execution" | "session" | "blueprint">> {
+  readonly execution?: AgentExecution;
+  readonly session?: Session;
+  readonly blueprint?: Partial<ResolvedBlueprint>;
+  /**
+   * The user's message on the default execution's spec (ignored when a whole
+   * `execution` is given). Empty by default: the neutral record asks nothing.
+   */
+  readonly message?: string;
+  /**
+   * The status the default execution carries — what the control plane
+   * persisted at the end of the previous invocation, on a reinvocation. The
+   * runtime seeds the turn's in-progress status from a clone of it
+   * (`seedTranscriptFromExecution`) and an adapter may read the record's own
+   * copy for its facts, so a test standing in for the runtime hands both.
+   */
+  readonly persistedStatus?: AgentExecutionStatus;
+  /**
+   * Where the default workspace lives (ignored when a whole `workspace` is
+   * given). A test that only needs "my workspace is here" — because its
+   * engine writes into it — states the directory and nothing else of the
+   * provision record.
+   */
+  readonly workspaceDir?: string;
+}
+
+/**
+ * The neutral record, with `overrides` laid over it one level deep. The
+ * `session` and `blueprint.session` are the SAME object, as the runtime
+ * guarantees (`bindHarnessState` writes it).
+ */
+export function turnInputFixture(overrides: TurnInputFixtureOverrides = {}): TurnInput {
+  const executionId = overrides.executionId ?? TURN_INPUT_FIXTURE_IDS.executionId;
+  const sessionId = overrides.sessionId ?? TURN_INPUT_FIXTURE_IDS.sessionId;
+  const session =
+    overrides.session ??
+    create(SessionSchema, {
+      metadata: create(ApiResourceMetadataSchema, { id: sessionId, org: TURN_INPUT_FIXTURE_IDS.org, name: sessionId }),
+      spec: create(SessionSpecSchema, {}),
+    });
+  const execution =
+    overrides.execution ??
+    create(AgentExecutionSchema, {
+      metadata: create(ApiResourceMetadataSchema, { id: executionId, org: TURN_INPUT_FIXTURE_IDS.org, name: executionId }),
+      spec: create(AgentExecutionSpecSchema, { sessionId, message: overrides.message ?? "" }),
+      status: overrides.persistedStatus,
+    });
+  const agent = create(AgentSchema, {
+    metadata: create(ApiResourceMetadataSchema, {
+      id: TURN_INPUT_FIXTURE_IDS.agentId,
+      org: TURN_INPUT_FIXTURE_IDS.org,
+      name: "fixture-agent",
+    }),
+    spec: create(AgentSpecSchema, { instructions: "You are the fixture agent." }),
+  });
+  const workspaceDir = overrides.workspaceDir ?? join(tmpdir(), "stigmer-runner-turn-input-fixture");
+  const blueprint: ResolvedBlueprint = {
+    agent,
+    agentSpec: agent.spec!,
+    session,
+    sessionSpec: session.spec!,
+    instructions: agent.spec!.instructions,
+    subAgents: [],
+    mergedMcpServerUsages: [],
+    mergedSkillRefs: [],
+    cloudRepos: [],
+    ...overrides.blueprint,
+  };
+  return {
+    executionId,
+    threadId: overrides.threadId ?? "",
+    turnSeq: overrides.turnSeq ?? 0,
+    sessionId,
+    approvalDecisions: overrides.approvalDecisions ?? new Map(),
+    execution,
+    session,
+    blueprint,
+    environment: overrides.environment ?? { envVars: {}, secretKeys: new Set() },
+    workspace: overrides.workspace ?? {
+      dirs: [workspaceDir],
+      primaryDir: workspaceDir,
+      gitWorkspace: false,
+      captureMode: false,
+      changeSetId: `${executionId}:${overrides.turnSeq ?? 0}`,
+      provision: { workspaceDirs: [workspaceDir], provisionResults: [], workspaceBackend: mockWorkspaceBackend() },
+    },
+    mcp: overrides.mcp ?? {
+      servers: [],
+      channelMessaging: [],
+      leases: { global: false, categories: new Set(), servers: new Set() },
+      policies: new Map(),
+    },
+    skills: overrides.skills ?? [],
+    attachments: overrides.attachments ?? { results: [], visionImages: [], visionNotViewable: [] },
+    appliedToolCallIds: overrides.appliedToolCallIds ?? new Set(),
+    model: overrides.model ?? { requested: "default", serviceTier: ServiceTier.STANDARD, thinkingMode: ThinkingMode.DISABLED },
+    structuredOutputSchema: overrides.structuredOutputSchema,
+    standing: overrides.standing ?? {
+      contextBridge: undefined,
+      senderIdentity: undefined,
+      sessionContext: undefined,
+      declaredPreferences: undefined,
+      conversationCatchup: undefined,
+      selectRecalledMemories: async () => undefined,
+    },
+    artifactStorage: overrides.artifactStorage,
+  };
+}

package/src/__tests__/harness-boot-order.test.ts

@@ -0,0 +1,77 @@
+/**
+ * The harness boot order, proven in a fresh process.
+ *
+ * The contract (`harness/types.ts` `boot`, `http2-interceptor.ts` header):
+ * the composition roots import `harness-adapters.js` and `harness/registry.js`
+ * BEFORE bootstrap, the Cursor adapter's `boot` installs the proxy
+ * interceptors — the HTTP/2 one patches `node:http2`, whose ESM facade is
+ * snapshotted at its first import by `@connectrpc/connect-node` — proves the
+ * patch reached the facade, and only then loads `@cursor/sdk`. Every module
+ * on the pre-boot path must therefore be connect-free, and the adapter's
+ * static graph SDK-free.
+ *
+ * Nothing in-process can test the positive arm: a vitest worker has imported
+ * `node:http2` long before any test runs, so the facade is frozen to the
+ * unpatched `connect` no matter what a test installs
+ * (`http2-interceptor.test.ts` covers only the two deterministic negatives
+ * for that reason). So each arm here spawns ONE fresh Node process
+ * (`__test-utils__/harness-boot-order-child.ts`) that does exactly what the
+ * roots do, and reads its one-line verdict. A static SDK import anywhere on
+ * `adapter.ts`'s graph, or a static client import on the registry's, fails
+ * the first arm; a `boot` that stopped asserting fails the second.
+ *
+ * `HOME` points at a temp dir so an SDK import-time side effect cannot touch
+ * the developer's home; the proxy endpoint is an inert loopback; nothing is
+ * dialled. Two spawns, a few seconds: the SDK is imported for real once.
+ */
+
+import { describe, it, expect } from "vitest";
+import { execFile } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const CHILD = fileURLToPath(new URL("../__test-utils__/harness-boot-order-child.ts", import.meta.url));
+
+interface ChildVerdict {
+  readonly exitCode: number;
+  readonly line: string;
+}
+
+async function runChild(arm: "boot" | "boot-after-connect-node"): Promise<ChildVerdict> {
+  const home = mkdtempSync(join(tmpdir(), "stigmer-boot-order-"));
+  try {
+    const { stdout } = await execFileAsync(process.execPath, ["--import", "tsx", CHILD, arm], {
+      env: { ...process.env, HOME: home },
+      timeout: 25_000,
+    });
+    return { exitCode: 0, line: lastLine(stdout) };
+  } catch (err) {
+    const failure = err as { code?: number; stdout?: string; stderr?: string };
+    return { exitCode: failure.code ?? -1, line: lastLine(`${failure.stdout ?? ""}${failure.stderr ?? ""}`) };
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
+function lastLine(text: string): string {
+  const lines = text.trim().split("\n");
+  return lines[lines.length - 1] ?? "";
+}
+
+describe("harness boot order (fresh process)", () => {
+  it("booting the harnesses on a proxy-mode config, the way the roots do, installs the interceptors, patches the facade, and loads the SDK", async () => {
+    const verdict = await runChild("boot");
+    expect(verdict.line, "the child's verdict").toBe("harness-boot-order: ok");
+    expect(verdict.exitCode).toBe(0);
+  });
+
+  it("the same boot after connect-node was imported first fails loudly on the facade (the guard is live inside boot)", async () => {
+    const verdict = await runChild("boot-after-connect-node");
+    expect(verdict.exitCode).toBe(1);
+    expect(verdict.line).toMatch(/node:http2 ESM facade is unpatched/);
+  });
+});

package/src/__tests__/harness-contract.test.ts

@@ -8,11 +8,13 @@
  * deterministic id. Neither the kit nor the fake branches on the pause
  * primitive — running both is what proves it.
  *
- * This is the consolidation home for what every harness owes the turn
- * runtime. A real adapter joins the net by implementing
- * `HarnessContractSubject` for its own SDK double and adding one line below;
- * the runtime extraction (S2 of the program) adds the Cursor adapter here
- * and runs the runtime-side half through the hermetic activity driver.
+ * This is the fake's home in the net. A real adapter joins by implementing
+ * `HarnessContractSubject` over its own SDK double and registering both
+ * halves in its own hermetic file, where the mocks its double needs can be
+ * hoisted: the Cursor adapter does so in
+ * `activities/execute-cursor/__tests__/hermetic/harness-contract.test.ts`
+ * (S2 M4), and the fake's runtime-side half runs in
+ * `harness/__tests__/run-turn.test.ts`.
  */
 
 import { describeHarnessContract } from "../__test-utils__/harness-contract/contract.js";

package/src/__tests__/runner-manager.test.ts

@@ -33,6 +33,24 @@ describe("mapManagerOptionsToConfig", () => {
     expect(config.checkpointerType).toBe("http");
   });
 
+  it("binds the proxy credential to the runner-token ref, never the control-plane ref (Q-S2-7)", () => {
+    const tokenRef = { current: "control-plane-token" };
+    const runnerTokenRef = { current: "control-plane-token" };
+    const config = mapManagerOptionsToConfig(
+      { ...base, proxyEndpoint: "https://localhost:9090", stigmerToken: "control-plane-token" },
+      tokenRef,
+      runnerTokenRef,
+    );
+    expect(config.proxyTokenRef).toBe(runnerTokenRef);
+    expect(config.stigmerRunnerTokenRef).toBe(runnerTokenRef);
+    expect(config.stigmerTokenRef).toBe(tokenRef);
+
+    // After the mint the two refs diverge; the proxy credential follows the mint.
+    runnerTokenRef.current = "minted-runner-token";
+    expect(config.proxyTokenRef?.current).toBe("minted-runner-token");
+    expect(config.stigmerTokenRef?.current).toBe("control-plane-token");
+  });
+
   it("uses cloud only when executionMode is explicitly cloud", () => {
     const config = mapManagerOptionsToConfig({
       ...base,

package/src/activities/execute-cursor/__test-utils__/__tests__/scripted-double.test.ts

@@ -0,0 +1,102 @@
+/**
+ * The scripted `@cursor/sdk` double's own arms — the surface the harness
+ * contract kit's Cursor subject drives, added at S2 M4 beside the golden
+ * scenarios' declared-up-front surface (which the seventeen goldens prove).
+ *
+ *  - `arrangeNextTurn` writes the slot the NEXT `send()` consumes, replaces a
+ *    slot already arranged, and never touches a slot already consumed or one
+ *    declared for a later send.
+ *  - `nextRunId` names the run the next send will be given, so a script can be
+ *    built with matching event ids before the send happens.
+ *  - `agentForWorkspaceRef` hands `Agent.create` the agent declared for the
+ *    session the create names (via `platform.workspaceRef`), consulted before
+ *    the ordered list and registered for `Agent.resume` by id; a create with no
+ *    session, or a session the resolver does not know, falls through to the
+ *    list as before.
+ */
+
+import { describe, it, expect } from "vitest";
+import type { AgentOptions, SDKMessage } from "@cursor/sdk";
+
+import { ScriptedCursorAgent, defaultRunId, sdkEvents, step } from "../scripted-agent.js";
+import { ScriptedCursorSdk } from "../scripted-sdk.js";
+
+/** An agent whose declared turns each play the given events and finish. */
+function agent(id: string, turns: SDKMessage[][] = []): ScriptedCursorAgent {
+  return new ScriptedCursorAgent({ agentId: id, turns: turns.map((events) => [...events.map((e) => step.event(e)), step.finished()]) });
+}
+
+async function drain(a: ScriptedCursorAgent): Promise<string[]> {
+  const run = await a.send("go");
+  const texts: string[] = [];
+  for await (const event of run.stream()) {
+    if (event.type === "assistant") texts.push(event.message.content.map((c) => (c.type === "text" ? c.text : "")).join(""));
+  }
+  await run.wait();
+  return texts;
+}
+
+describe("ScriptedCursorAgent.arrangeNextTurn", () => {
+  it("writes the slot the next send consumes and replaces an arrangement not yet played", async () => {
+    const a = agent("a1");
+    const ev = sdkEvents("a1", a.nextRunId);
+    a.arrangeNextTurn([step.event(ev.assistant("first arrangement")), step.finished()]);
+    a.arrangeNextTurn([step.event(ev.assistant("replaced")), step.finished()]);
+
+    expect(await drain(a)).toEqual(["replaced"]);
+  });
+
+  it("leaves a consumed slot and a later declared slot where they are", async () => {
+    const ev1 = sdkEvents("a2", defaultRunId("a2", 0));
+    const ev3 = sdkEvents("a2", defaultRunId("a2", 2));
+    const a = agent("a2", [[ev1.assistant("declared one")], [ev1.assistant("declared two")], [ev3.assistant("declared three")]]);
+
+    expect(await drain(a)).toEqual(["declared one"]);
+    a.arrangeNextTurn([step.event(sdkEvents("a2", a.nextRunId).assistant("arranged two")), step.finished()]);
+    expect(await drain(a)).toEqual(["arranged two"]);
+    expect(await drain(a), "the third slot was declared up front and stands").toEqual(["declared three"]);
+  });
+
+  it("a send with no slot is a test bug and throws", async () => {
+    const a = agent("a3");
+    await expect(a.send("go")).rejects.toThrow(/send\(\) #1 has no script/);
+  });
+});
+
+describe("ScriptedCursorAgent.nextRunId", () => {
+  it("is the id the next send is given — the declared one, else the default", async () => {
+    const declared = new ScriptedCursorAgent({ agentId: "a4", runIds: ["run-x"], turns: [[step.finished()], [step.finished()]] });
+    expect(declared.nextRunId).toBe("run-x");
+    const run1 = await declared.send("go");
+    expect(run1.id).toBe("run-x");
+    expect(declared.nextRunId, "no second id declared: the default, counting sends from 1").toBe(defaultRunId("a4", 1));
+    const run2 = await declared.send("go");
+    expect(run2.id).toBe("run-a4-2");
+  });
+});
+
+describe("ScriptedCursorSdk.agentForWorkspaceRef", () => {
+  const createFor = (workspaceRef: string | undefined): AgentOptions =>
+    ({ apiKey: "k", ...(workspaceRef !== undefined ? { platform: { workspaceRef, stateRoot: "/tmp/x" } } : {}) }) as unknown as AgentOptions;
+
+  it("hands out the session's agent before the ordered list and registers it for resume", () => {
+    const forSession = agent("session-agent");
+    const listed = agent("listed-agent");
+    const sdk = new ScriptedCursorSdk({
+      agents: [listed],
+      catalog: [],
+      agentForWorkspaceRef: (ref) => (ref === "stigmer-session:ses-1" ? forSession : undefined),
+    });
+
+    expect(sdk.create(createFor("stigmer-session:ses-1"))).toBe(forSession);
+    expect(sdk.resume("session-agent", undefined)).toBe(forSession);
+    expect(sdk.create(createFor("stigmer-session:unknown")), "an unknown session falls through to the list").toBe(listed);
+    expect(sdk.resolutions.map((r) => `${r.kind}:${r.agentId}`)).toEqual(["create:session-agent", "resume:session-agent", "create:listed-agent"]);
+  });
+
+  it("a create without a platform ref falls through to the ordered list", () => {
+    const listed = agent("listed-only");
+    const sdk = new ScriptedCursorSdk({ agents: [listed], catalog: [], agentForWorkspaceRef: () => agent("never") });
+    expect(sdk.create(createFor(undefined))).toBe(listed);
+  });
+});