@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

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

@@ -13,7 +13,7 @@
  * 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
+ * (since #1070), and the fake's runtime-side half runs in
  * `harness/__tests__/run-turn.test.ts`.
  */
 

package/src/__tests__/run-credential-e2e.test.ts

@@ -0,0 +1,233 @@
+/**
+ * The run credential end to end through a real Temporal
+ * (`TestWorkflowEnvironment`, the golden E2E's harness): a credential on the
+ * `execute-from-execution` workflow input reaches EVERY activity the run
+ * schedules — the remote hydrate and the engine's local activities alike —
+ * as the activity's current run credential, and a credential-less input
+ * reaches none of them. This is the property the whole carrier exists for
+ * (`shared/run-credential.ts`): no activity of a member's run ever runs as
+ * the operator, and no activity of a credential-less run changes.
+ *
+ * Both ends are registered exactly as the worker roots register them: the
+ * activity interceptor on the worker, the workflow interceptor module in the
+ * bundle. Skipped, like the golden E2E, when a local Temporal cannot boot.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadWorkflowFromYaml } from "../workflow-engine/loader.js";
+import { evaluateExpressionBatch } from "../workflow-engine/expression.js";
+import type { ExecuteFromExecutionInput } from "../workflows/execute-from-execution.js";
+import { EXECUTE_FROM_EXECUTION_WORKFLOW_TYPE } from "../workflows/execute-from-execution.js";
+import { runCredentialActivityInterceptor } from "../interceptors/run-credential-activity.js";
+import { currentRunCredential } from "../shared/run-credential-store.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WORKFLOWS_PATH = join(__dirname, "../workflows/index.ts");
+const RUN_CREDENTIAL_WORKFLOW_INTERCEPTOR = join(
+  __dirname,
+  "../workflows/interceptors/run-credential.ts",
+);
+const GOLDEN_MODEL = readFileSync(
+  join(__dirname, "../../test/golden/01-operation-basic.yaml"),
+  "utf-8",
+);
+const TASK_QUEUE = "run-credential-e2e-test";
+
+type TestWorkflowEnvironment =
+  import("@temporalio/testing").TestWorkflowEnvironment;
+type Worker = import("@temporalio/worker").Worker;
+
+let env: TestWorkflowEnvironment | null = null;
+let worker: Worker | null = null;
+let workerRunPromise: Promise<void> | null = null;
+let envReady = false;
+
+/**
+ * What each activity saw as its run credential, in the order they ran, with
+ * the execution it was working on (the hydrate's input object; the engine's
+ * positional first argument).
+ */
+const observed: Array<{
+  activity: string;
+  executionId: string;
+  credential: string | undefined;
+}> = [];
+
+function observing<T extends (...args: never[]) => unknown>(
+  activity: string,
+  body: T,
+): T {
+  return ((...args: never[]) => {
+    const first: unknown = args[0];
+    const executionId =
+      typeof first === "string"
+        ? first
+        : typeof first === "object" && first !== null && "execution_id" in first
+          ? String((first as { execution_id: unknown }).execution_id)
+          : "";
+    observed.push({
+      activity,
+      executionId,
+      credential: currentRunCredential(),
+    });
+    return body(...args);
+  }) as T;
+}
+
+function createObservingActivities() {
+  return {
+    HydrateWorkflowExecution: observing(
+      "HydrateWorkflowExecution",
+      async (input: ExecuteFromExecutionInput) => ({
+        model: loadWorkflowFromYaml(GOLDEN_MODEL),
+        workflow_input: null,
+        env: {},
+        metadata: { execution_id: input.execution_id },
+      }),
+    ),
+    ResetEventSequence: observing(
+      "ResetEventSequence",
+      async (): Promise<number> => 0,
+    ),
+    LoadRecoveryContext: observing(
+      "LoadRecoveryContext",
+      async (): Promise<unknown[]> => [],
+    ),
+    EmitWorkflowEvents: observing(
+      "EmitWorkflowEvents",
+      async (): Promise<void> => {},
+    ),
+    PromoteTaskOutput: observing(
+      "PromoteTaskOutput",
+      async (): Promise<void> => {},
+    ),
+    EvaluateExpressions: observing(
+      "EvaluateExpressions",
+      async (
+        expressions: Record<string, string>,
+        input: unknown,
+        stateVars: Record<string, unknown>,
+      ) => evaluateExpressionBatch(expressions, input, stateVars),
+    ),
+  };
+}
+
+async function runOnce(credential: string | undefined): Promise<string> {
+  if (!env) throw new Error("TestWorkflowEnvironment not initialized");
+  const executionId = `wex_e2e_${Math.random().toString(36).slice(2)}`;
+  const input: ExecuteFromExecutionInput = {
+    execution_id: executionId,
+    workflow_instance_id: "wfi_1",
+    workflow_id: "wf_1",
+    org_id: "org_1",
+    ...(credential !== undefined
+      ? { execution_context_token: credential }
+      : {}),
+  };
+  await env.client.workflow.execute(EXECUTE_FROM_EXECUTION_WORKFLOW_TYPE, {
+    taskQueue: TASK_QUEUE,
+    workflowId: `run-credential-e2e-${executionId}`,
+    args: [input],
+    workflowExecutionTimeout: "30s",
+  });
+  return executionId;
+}
+
+describe("run credential E2E — Temporal TestWorkflowEnvironment", () => {
+  beforeAll(async () => {
+    try {
+      const { TestWorkflowEnvironment: TWE } =
+        await import("@temporalio/testing");
+      const { Worker: W } = await import("@temporalio/worker");
+
+      env = await TWE.createLocal();
+      worker = await W.create({
+        connection: env.nativeConnection,
+        taskQueue: TASK_QUEUE,
+        workflowsPath: WORKFLOWS_PATH,
+        activities: createObservingActivities(),
+        interceptors: {
+          activity: [runCredentialActivityInterceptor],
+          workflowModules: [RUN_CREDENTIAL_WORKFLOW_INTERCEPTOR],
+        },
+      });
+      workerRunPromise = worker.run();
+      await runOnce(undefined);
+      observed.length = 0;
+      envReady = true;
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(
+        `Temporal E2E smoke test failed (tests will be skipped): ${msg}`,
+      );
+      envReady = false;
+    }
+  }, 90_000);
+
+  afterAll(async () => {
+    if (worker) {
+      worker.shutdown();
+      await workerRunPromise;
+    }
+    await env?.teardown();
+  });
+
+  it("every activity of a run whose input carries a credential runs with that credential current", async (testCtx) => {
+    if (!envReady) return testCtx.skip();
+    observed.length = 0;
+
+    await runOnce("run-cred-e2e");
+
+    const activities = new Set(observed.map((o) => o.activity));
+    expect(activities).toContain("HydrateWorkflowExecution");
+    expect(activities).toContain("ResetEventSequence");
+    expect(activities).toContain("EmitWorkflowEvents");
+    expect(observed.length).toBeGreaterThan(3);
+    expect(
+      observed.every((o) => o.credential === "run-cred-e2e"),
+      JSON.stringify(observed),
+    ).toBe(true);
+  }, 60_000);
+
+  it("no activity of a credential-less run sees a credential — an older server's dispatch is unchanged", async (testCtx) => {
+    if (!envReady) return testCtx.skip();
+    observed.length = 0;
+
+    await runOnce(undefined);
+
+    expect(observed.length).toBeGreaterThan(3);
+    expect(
+      observed.every((o) => o.credential === undefined),
+      JSON.stringify(observed),
+    ).toBe(true);
+  }, 60_000);
+
+  it("two runs in flight at once each see their own credential", async (testCtx) => {
+    if (!envReady) return testCtx.skip();
+    observed.length = 0;
+
+    const [one, two] = await Promise.all([
+      runOnce("run-cred-one"),
+      runOnce("run-cred-two"),
+    ]);
+    const expected = new Map([
+      [one, "run-cred-one"],
+      [two, "run-cred-two"],
+    ]);
+
+    const identified = observed.filter((o) => o.executionId !== "");
+    expect(identified.length).toBeGreaterThan(6);
+    expect(new Set(identified.map((o) => o.executionId))).toEqual(
+      new Set([one, two]),
+    );
+    for (const o of identified) {
+      expect(o.credential, `${o.activity} on ${o.executionId}`).toBe(
+        expected.get(o.executionId),
+      );
+    }
+  }, 60_000);
+});

package/src/__tests__/run-credential-registration.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Pins that every place a worker is composed registers BOTH ends of the run
+ * credential (`shared/run-credential.ts`): the activity inbound interceptor
+ * in the two roots that create workers, and the workflow interceptor module
+ * in the two runtime-bundling roots and the pre-built bundle script.
+ *
+ * Why a fence and not a comment: a root that forgot the activity end would
+ * present the operator's API key on every member's run — the failure this
+ * whole design exists to end — and on the desktop (the manager root) it
+ * would be invisible, because a person's own runner works for that person
+ * either way. The roots are read off the TypeScript syntax tree
+ * (`__test-utils__/module-specifiers.ts`) for the imports and off the source
+ * for the one call each import must make; the build script is JavaScript
+ * and is read as text.
+ */
+
+import { describe, expect, it } from "vitest";
+import { fileURLToPath } from "node:url";
+
+import {
+  moduleSpecifiers,
+  readSource,
+} from "../__test-utils__/module-specifiers.js";
+
+const SRC_ROOT = fileURLToPath(new URL("../", import.meta.url));
+const RUNNER_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+
+const ACTIVITY_END = "./interceptors/run-credential-activity.js";
+const WORKFLOW_END_RESOLVER = "runCredentialWorkflowInterceptorModule";
+
+function root(file: string): {
+  file: string;
+  source: string;
+  specifiers: string[];
+} {
+  const path = `${SRC_ROOT}${file}`;
+  const source = readSource(path);
+  return { file, source, specifiers: moduleSpecifiers(path, source) };
+}
+
+describe("run-credential registration", () => {
+  for (const file of ["worker.ts", "runner-manager.ts"]) {
+    it(`${file} registers the activity end and resolves the workflow end`, () => {
+      const { specifiers, source } = root(file);
+      expect(
+        specifiers,
+        `${file} must import the activity interceptor`,
+      ).toContain(ACTIVITY_END);
+      expect(
+        source,
+        `${file} must place runCredentialActivityInterceptor in its activity interceptors`,
+      ).toMatch(
+        /ActivityInterceptorsFactory\[\]\s*=\s*\[runCredentialActivityInterceptor\]/,
+      );
+      expect(
+        source,
+        `${file} must resolve the workflow interceptor module`,
+      ).toContain(`${WORKFLOW_END_RESOLVER}()`);
+    });
+  }
+
+  it("scripts/bundle-slim.mjs bakes the workflow end into the pre-built bundle", () => {
+    const source = readSource(`${RUNNER_ROOT}scripts/bundle-slim.mjs`);
+    expect(source).toMatch(
+      new RegExp(
+        `workflowInterceptorModules:\\s*\\[\\s*${WORKFLOW_END_RESOLVER}\\(\\)`,
+      ),
+    );
+  });
+
+  it("the workflow end is a sandbox module: it imports nothing from Node", () => {
+    const path = `${SRC_ROOT}workflows/interceptors/run-credential.ts`;
+    const nodeImports = moduleSpecifiers(path, readSource(path)).filter((s) =>
+      s.startsWith("node:"),
+    );
+    expect(nodeImports).toEqual([]);
+    const wirePath = `${SRC_ROOT}shared/run-credential.ts`;
+    expect(moduleSpecifiers(wirePath, readSource(wirePath))).toEqual([]);
+  });
+});

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

@@ -33,7 +33,7 @@ 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)", () => {
+  it("binds the proxy credential to the runner-token ref, never the control-plane ref", () => {
     const tokenRef = { current: "control-plane-token" };
     const runnerTokenRef = { current: "control-plane-token" };
     const config = mapManagerOptionsToConfig(

package/src/activities/__tests__/generate-session-subject-wire.test.ts

@@ -0,0 +1,119 @@
+/**
+ * The GenerateSessionSubject activity's wire contract: one argument in one of
+ * two shapes — the positional execution id every server has sent, and the
+ * typed object a server sends when the dispatch carries the run credential.
+ * Both reach the same core with the same execution id; the credential is the
+ * activity boundary's business, not this activity's (the header explains).
+ *
+ * The client is the hermetic module seam (`__test-utils__/hermetic-activity.ts`)
+ * because the factory constructs its own `StigmerClient`; the LLM seam is
+ * module-mocked to return a fixed title.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { StigmerClient } from "../../client/stigmer-client.js";
+import { bindHermeticClient } from "../../__test-utils__/hermetic-activity.js";
+import { mockStigmerClient } from "../../__test-utils__/mock-client.js";
+
+vi.mock("../../client/stigmer-client.js", async () =>
+  (
+    await import("../../__test-utils__/hermetic-activity.js")
+  ).hermeticStigmerClientModule(),
+);
+vi.mock("../../shared/model-registry.js", () => ({
+  getSummarizationModel: vi.fn(async (primary: string) => primary),
+}));
+vi.mock("../../shared/model-client.js", () => ({
+  buildChatModel: vi.fn(async () => ({
+    model: { invoke: vi.fn(async () => ({ content: "Indexing Basics" })) },
+  })),
+}));
+vi.mock("../../shared/llm-backend.js", () => ({
+  checkDirectCredentials: vi.fn(() => null),
+}));
+vi.mock("../../shared/llm-proxy.js", () => ({
+  tryInferProvider: vi.fn(() => "anthropic"),
+}));
+
+import {
+  AUTO_CREATED_SUBJECT,
+  createGenerateSessionSubjectActivities,
+} from "../generate-session-subject.js";
+import type { Config } from "../../config.js";
+
+const EXECUTION_ID = "aex_wire_1";
+
+function clientReadingExecution(): {
+  client: StigmerClient;
+  reads: string[];
+  titled: string[];
+} {
+  const reads: string[] = [];
+  const titled: string[] = [];
+  const client = mockStigmerClient({
+    getExecution: vi.fn(async (executionId: string) => {
+      reads.push(executionId);
+      return {
+        spec: {
+          sessionId: "ses_1",
+          agentId: "agt_1",
+          message: "How do indexes work?",
+        },
+      } as never;
+    }),
+    getSession: vi.fn(
+      async () =>
+        ({
+          spec: { subject: AUTO_CREATED_SUBJECT, agentInstanceId: "" },
+        }) as never,
+    ),
+    getAgent: vi.fn(
+      async () =>
+        ({ metadata: { name: "a" }, spec: { description: "" } }) as never,
+    ),
+    updateSessionSubject: vi.fn(async (_sessionId: string, subject: string) => {
+      titled.push(subject);
+      return {} as never;
+    }),
+  });
+  return { client, reads, titled };
+}
+
+function activityUnderTest() {
+  const { client, reads, titled } = clientReadingExecution();
+  bindHermeticClient(client);
+  const config = {
+    stigmerBackendEndpoint: "http://localhost:0",
+    stigmerToken: null,
+    proxyEndpoint: null,
+    primaryModel: "claude-sonnet-4.5",
+  } as unknown as Config;
+  const { GenerateSessionSubject } =
+    createGenerateSessionSubjectActivities(config);
+  return { GenerateSessionSubject, reads, titled };
+}
+
+describe("GenerateSessionSubject wire shapes", () => {
+  it("accepts the positional execution id — every earlier server's shape", async () => {
+    const { GenerateSessionSubject, reads, titled } = activityUnderTest();
+    await GenerateSessionSubject(EXECUTION_ID);
+    expect(reads).toEqual([EXECUTION_ID]);
+    expect(titled).toEqual(["Indexing Basics"]);
+  });
+
+  it("accepts the typed object carrying the run credential and reads the same execution", async () => {
+    const { GenerateSessionSubject, reads, titled } = activityUnderTest();
+    await GenerateSessionSubject({
+      execution_id: EXECUTION_ID,
+      execution_context_token: "run-cred",
+    });
+    expect(reads).toEqual([EXECUTION_ID]);
+    expect(titled).toEqual(["Indexing Basics"]);
+  });
+
+  it("accepts the typed object without a credential", async () => {
+    const { GenerateSessionSubject, reads } = activityUnderTest();
+    await GenerateSessionSubject({ execution_id: EXECUTION_ID });
+    expect(reads).toEqual([EXECUTION_ID]);
+  });
+});

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

@@ -1,6 +1,6 @@
 /**
  * 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
+ * contract kit's Cursor subject drives, added in #1070 beside the golden
  * scenarios' declared-up-front surface (which the seventeen goldens prove).
  *
  *  - `arrangeNextTurn` writes the slot the NEXT `send()` consumes, replaces a

package/src/activities/execute-cursor/__test-utils__/contract-subject.ts

@@ -1,7 +1,7 @@
 /**
  * The Cursor harness as a `HarnessContractSubject` — the REAL `createCursorAdapter()`
  * driven through the harness contract kit, with the kit's engine-neutral
- * scenario vocabulary translated onto S0's scripted `@cursor/sdk` double.
+ * scenario vocabulary translated onto the scripted `@cursor/sdk` double (#1048).
  *
  * The sibling of `gateway-substrate.ts` (the Cursor side of the approval
  * contract kit): the kit owns the invariants and the runtime stand-in, this
@@ -59,7 +59,7 @@
  * Every script that does not end in `fail`, `cancelled` or `hang` closes with
  * `finished({ result: <last say> })` so `run.wait()` has an answer.
  *
- * ── Two modelling decisions (S2 M4, Q-M4-4) ─────────────────────────────────
+ * ── Two modelling decisions (#1070) ─────────────────────────────────────────
  * A `propose` for an id this subject has already seen the hook ALLOW emits
  * nothing: the real SDK does not re-run a completed tool on resume — the parked
  * agent's conversation already holds the tool's result. A `propose` whose id

package/src/activities/execute-cursor/__test-utils__/fold.ts

@@ -0,0 +1,116 @@
+/**
+ * Drive Cursor SDK events through the REAL pair the harness runs in production
+ * — `CursorTranslator` into `TranscriptBuilder` over an `AgentExecutionStatus`
+ * — and hand back what they built. The unit-test seam that replaced
+ * `new <accumulator>(messages, options)` in #1097 (the accumulator folded
+ * rows itself; now the translator emits events and the shared builder folds
+ * them), so the arms that read a row's shape after a sequence of SDK events
+ * keep their shape while the module under them changed.
+ *
+ * The same shape as the native translator's local `feedAll` in
+ * `execute-deep-agent/__tests__/translator-through-builder.test.ts`, shared
+ * here because seven Cursor test files read through it.
+ *
+ * Deltas follow the loop's discipline (`turn-stream.ts`): `observeDelta`
+ * queues, and the queue is drained into the builder after the NEXT stream
+ * event — or at {@link CursorFold.drain} for a caller that wants them applied
+ * now, the settle's own last drain before `finalize()`.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { InteractionUpdate, SDKMessage } from "@cursor/sdk";
+import { AgentExecutionStatusSchema, type AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { TranscriptBuilder } from "../../../harness/transcript/builder.js";
+import { CursorTranslator, type CursorTranslatorOptions } from "../translator.js";
+
+export interface CursorFoldOptions {
+  /** The status to build into; a fresh empty one when omitted. Its `messages` are the translator's seed. */
+  readonly status?: AgentExecutionStatus;
+  /**
+   * An existing `messages` array to build into BY REFERENCE (a test that
+   * hand-built its seeded rows and keeps asserting on the same objects). Wins
+   * over `status`'s own array.
+   */
+  readonly messages?: AgentMessage[];
+  readonly policies?: CursorTranslatorOptions["policies"];
+  readonly leases?: CursorTranslatorOptions["leases"];
+}
+
+export class CursorFold {
+  readonly status: AgentExecutionStatus;
+  readonly translator: CursorTranslator;
+  readonly builder: TranscriptBuilder;
+
+  constructor(options: CursorFoldOptions = {}) {
+    this.status = options.status ?? create(AgentExecutionStatusSchema, {});
+    if (options.messages) this.status.messages = options.messages;
+    this.translator = new CursorTranslator({
+      policies: options.policies ?? new Map(),
+      leases: options.leases ?? { global: false, categories: new Set() },
+      seeded: this.status.messages,
+    });
+    this.builder = new TranscriptBuilder("exec-fold", this.status);
+  }
+
+  /** One stream event, translated and folded, then the deltas queued so far — the loop's order. */
+  event(event: SDKMessage): this {
+    for (const e of this.translator.translate(event)) this.builder.apply(e);
+    this.drain();
+    return this;
+  }
+
+  events(...events: SDKMessage[]): this {
+    for (const e of events) this.event(e);
+    return this;
+  }
+
+  /** One delta, queued — applied at the next {@link event} or {@link drain}. */
+  delta(update: InteractionUpdate): this {
+    this.translator.observeDelta(update);
+    return this;
+  }
+
+  drain(): this {
+    for (const e of this.translator.drainDeltas()) this.builder.apply(e);
+    return this;
+  }
+
+  finalize(): this {
+    this.drain();
+    this.builder.finalize();
+    return this;
+  }
+
+  get messages(): AgentMessage[] {
+    return this.status.messages;
+  }
+
+  /** Every root row, in transcript order. */
+  rows(): ToolCall[] {
+    return this.status.messages.flatMap((m) => m.toolCalls);
+  }
+
+  row(callId: string): ToolCall {
+    const found = this.rows().find((tc) => tc.id === callId);
+    if (!found) throw new Error(`CursorFold: no row ${callId}`);
+    return found;
+  }
+}
+
+/** Fold a sequence of stream events into a fresh transcript; the common one-liner. */
+export function foldCursorEvents(events: readonly SDKMessage[], options: CursorFoldOptions = {}): CursorFold {
+  return new CursorFold(options).events(...events);
+}
+
+/**
+ * A builder over an existing `messages` array, kept BY REFERENCE (the status
+ * is given the array itself, never a copy), so a boundary test that built its
+ * rows by hand can hand them to `reconcileDeniedToolCalls` and keep asserting
+ * on the same objects.
+ */
+export function builderOver(messages: AgentMessage[], executionId = "exec-boundary"): TranscriptBuilder {
+  const status = create(AgentExecutionStatusSchema, {});
+  status.messages = messages;
+  return new TranscriptBuilder(executionId, status);
+}

package/src/activities/execute-cursor/__test-utils__/gateway-substrate.ts

@@ -80,7 +80,7 @@ export function createCursorSubstrate(): GatewaySubstrate {
       enforcesExactContent: true,
       appliesRunLifetimeLease: true,
       // The Cursor hook's deny decision does not carry approval_policy_source;
-      // provenance is projected at message-reconstruction time (message-translator)
+      // provenance is projected at translation time (the Cursor translator)
       // and asserted by the corpus + resolveApprovalProvenance suites instead.
       surfacesGatePolicySource: false,
     },