@stigmer/runner 3.22.0 → 3.22.1-dev.20260922095755

package/src/shared/checkpointer/__tests__/http-saver.test.ts

@@ -1,9 +1,19 @@
+/**
+ * HttpCheckpointSaver: the proxy wire shape ($binary transport, the routes,
+ * the header), the bounded retry loop and its classification, and the one
+ * thing that must never regress silently — the bearer credential is read
+ * from the shared ref on every request, so a rotation between two requests
+ * of one saver reaches the second (a pool member claimed for a session; a
+ * sandbox token renewed in place).
+ */
+
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { HttpCheckpointSaver } from "../http-saver.js";
+import type { TokenRef } from "../../../config.js";
 import type { Checkpoint, CheckpointMetadata } from "@langchain/langgraph-checkpoint";
 
 const PROXY = "https://proxy.test";
-const TOKEN = "test-token";
+const TOKEN: TokenRef = { current: "test-token" };
 
 function makeConfig(overrides: Record<string, string> = {}) {
   return {
@@ -71,6 +81,19 @@ describe("HttpCheckpointSaver", () => {
       expect(opts.headers.Authorization).toBe("Bearer test-token");
       expect(url).toContain("/v1/proxy/checkpoints/checkpoint");
     });
+
+    it("presents the credential the ref holds NOW: a rotation between two requests reaches the second", async () => {
+      const ref: TokenRef = { current: "boot-credential" };
+      const rotating = new HttpCheckpointSaver(PROXY, ref);
+      fetchSpy.mockResolvedValue({ status: 404, ok: false });
+
+      await rotating.getTuple(makeConfig());
+      ref.current = "session-credential";
+      await rotating.getTuple(makeConfig());
+
+      expect(fetchSpy.mock.calls[0][1].headers.Authorization).toBe("Bearer boot-credential");
+      expect(fetchSpy.mock.calls[1][1].headers.Authorization).toBe("Bearer session-credential");
+    });
   });
 
   describe("put", () => {
@@ -360,7 +383,7 @@ describe("HttpCheckpointSaver", () => {
 
   describe("URL construction", () => {
     it("strips trailing slashes from proxy endpoint", () => {
-      const s = new HttpCheckpointSaver("https://proxy.test///", "tok");
+      const s = new HttpCheckpointSaver("https://proxy.test///", { current: "tok" });
       fetchSpy.mockResolvedValue({ status: 404, ok: false });
       s.getTuple(makeConfig());
       const [url] = fetchSpy.mock.calls[0];

package/src/shared/checkpointer/factory.ts

@@ -68,7 +68,11 @@ export async function createCheckpointer(
           "proxyEndpoint is required for HTTP checkpointer",
         );
       }
-      if (!config.authToken) {
+      // The ref must be present AND hold a credential at open: a saver that
+      // opened without one would fail its first request with a bare 401
+      // instead of this named error, and a proxy-mode runner always has one
+      // (loadConfig refuses to boot without STIGMER_TOKEN).
+      if (!config.authToken?.current) {
         throw new CheckpointerCreationError(
           "http",
           "authToken is required for HTTP checkpointer",

package/src/shared/checkpointer/http-saver.ts

@@ -26,6 +26,14 @@
  * upserts. Budget exhaustion still fails loudly — checkpoints are not
  * lossy-tolerable (unlike status updates, see status.ts), and silently
  * dropping one would corrupt resume state.
+ *
+ * The bearer credential is a shared ref read on EVERY request, never a
+ * header frozen at construction: a saver lives for a whole turn, and the
+ * runner's control-plane credential rotates underneath it (a pool member
+ * claimed for a session, a sandbox token renewed in place). A frozen header
+ * kept presenting the boot credential and every read after the rotation
+ * was refused (config.ts header; ProxyArtifactStorage holds its credential
+ * the same way).
  */
 
 import type { RunnableConfig } from "@langchain/core/runnables";
@@ -38,6 +46,7 @@ import {
   type ChannelVersions,
 } from "@langchain/langgraph-checkpoint";
 import type { CheckpointMetadata, PendingWrite } from "@langchain/langgraph-checkpoint";
+import type { TokenRef } from "../../config.js";
 import type { RetryOptions } from "../grpc-retry.js";
 import { fetchWithRetry, type FetchRetryPolicy } from "../http-retry.js";
 
@@ -119,20 +128,17 @@ const DEFAULT_RETRY = {
 
 export class HttpCheckpointSaver extends BaseCheckpointSaver {
   private readonly baseUrl: string;
-  private readonly headers: Record<string, string>;
+  private readonly authToken: Readonly<TokenRef>;
   private readonly retryPolicy: FetchRetryPolicy;
 
   constructor(
     proxyEndpoint: string,
-    authToken: string,
+    authToken: Readonly<TokenRef>,
     options: HttpCheckpointSaverOptions = {},
   ) {
     super();
     this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/checkpoints`;
-    this.headers = {
-      Authorization: `Bearer ${authToken}`,
-      "Content-Type": "application/json",
-    };
+    this.authToken = authToken;
     this.retryPolicy = {
       label: "HttpCheckpointSaver",
       baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
@@ -143,6 +149,14 @@ export class HttpCheckpointSaver extends BaseCheckpointSaver {
     };
   }
 
+  /** The request headers as of now: the credential is resolved here, per request (the header). */
+  private get headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.authToken.current ?? ""}`,
+      "Content-Type": "application/json",
+    };
+  }
+
   private fetchWithRetry(url: string, init?: RequestInit): Promise<Response> {
     return fetchWithRetry(url, init, this.retryPolicy);
   }

package/src/shared/checkpointer/types.ts

@@ -6,11 +6,22 @@
  *   ExecuteDeepAgent invocations so HITL/pause/transient-recovery truly resume.
  * - http:   routes through the Stigmer Side-Channel Proxy (cloud / managed).
  * - memory: ephemeral in-process storage — explicit opt-in, used by tests.
+ *
+ * The http backend's credential is a shared ref, never a string: the saver
+ * reads it per request, so a rotation of the runner's control-plane
+ * credential (a pool claim, a sandbox-token renewal) reaches a checkpoint
+ * written after it — including mid-turn, since a saver lives for a whole
+ * turn (config.ts header; the artifact store holds its credential the same
+ * way).
  */
+
+import type { TokenRef } from "../../config.js";
+
 export interface CheckpointerConfig {
   readonly type: "memory" | "http" | "sqlite";
   readonly proxyEndpoint?: string;
-  readonly authToken?: string;
+  /** The credential the http saver presents, read per request. Required when type is "http". */
+  readonly authToken?: Readonly<TokenRef>;
   /** Absolute path to the SQLite database file. Required when type is "sqlite". */
   readonly sqlitePath?: string;
 }

package/src/shared/extract-structured-output.ts

@@ -60,7 +60,7 @@ export async function extractStructuredOutput(
   const { model: llm } = await buildChatModel({
     modelName: extractionModel,
     proxyEndpoint,
-    stigmerToken: config.stigmerToken ?? undefined,
+    stigmerToken: config.stigmerTokenRef.current ?? undefined,
     maxTokens: 4096,
   });
 

package/src/shared/filereview/__tests__/cas-substrate.test.ts

@@ -412,7 +412,7 @@ describe("casBlobReader — ProxyArtifactStorage presigned+fetch path (cloud)",
     });
     vi.stubGlobal("fetch", fetchMock);
     try {
-      const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+      const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
       const reader = casBlobReader(storage);
       const got = await reader(key);
       expect(got.equals(payload)).toBe(true);

package/src/shared/filereview/__tests__/proxy-reconcile.test.ts

@@ -186,7 +186,7 @@ describe("proxy-mode file-review reconcile (real ProxyArtifactStorage)", () => {
 
   beforeEach(async () => {
     proxy = await startMockProxy();
-    storage = new ProxyArtifactStorage(proxy.endpoint, "tok");
+    storage = new ProxyArtifactStorage(proxy.endpoint, { current: "tok" });
   });
   afterEach(async () => {
     await proxy.close();

package/src/workflow-engine/__tests__/tasks/emit-event.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
 import { emitEventAction, type EmitEventConfig, type SignalDeliveryTarget } from "../../../activities/emit-event.js";
+import type { StigmerClient } from "../../../client/stigmer-client.js";
 
 // ─── Server-mediated signal-delivery mocks ───────────────────────────────────
 // deliverSignal routes through StigmerClient.sendWorkflowSignal (the server's
@@ -12,25 +13,9 @@ const mockSendWorkflowSignal = vi.fn(async (
   _payload: unknown,
   _options?: { timeoutMs?: number },
 ) => ({}));
-const mockClientCtor = vi.fn((_opts: { endpoint: string; token?: string | null }) => ({
-  sendWorkflowSignal: mockSendWorkflowSignal,
-}));
-
-vi.mock("../../../client/stigmer-client.js", () => ({
-  StigmerClient: vi.fn().mockImplementation(
-    (opts: { endpoint: string; token?: string | null }) => mockClientCtor(opts),
-  ),
-}));
-
-// Mutable so each test can vary what config.ts resolves. deliverSignal builds
-// its client from the canonical stigmerBackendEndpoint resolution.
-let mockBackendEndpoint = "http://localhost:7234";
-vi.mock("../../../config.js", () => ({
-  loadConfig: () => ({
-    stigmerBackendEndpoint: mockBackendEndpoint,
-    stigmerToken: null,
-  }),
-}));
+// The client is the caller's (call-function.ts builds it from the runner's
+// Config); this module constructs none, so the test hands in a fake.
+const client = { sendWorkflowSignal: mockSendWorkflowSignal } as unknown as StigmerClient;
 
 describe("emitEventAction", () => {
   describe("envelope construction", () => {
@@ -39,7 +24,7 @@ describe("emitEventAction", () => {
         event: { type: "workflow.step.completed" },
       };
 
-      const result = await emitEventAction(config, "exec-123");
+      const result = await emitEventAction(config, "exec-123", undefined, client);
 
       expect(result.specversion).toBe("1.0");
       expect(result.type).toBe("workflow.step.completed");
@@ -55,7 +40,7 @@ describe("emitEventAction", () => {
         event: { type: "user.created", source: "/services/auth" },
       };
 
-      const result = await emitEventAction(config, "exec-456");
+      const result = await emitEventAction(config, "exec-456", undefined, client);
 
       expect(result.source).toBe("/services/auth");
     });
@@ -65,7 +50,7 @@ describe("emitEventAction", () => {
         event: { type: "order.shipped", subject: "order-789" },
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.subject).toBe("order-789");
     });
@@ -78,7 +63,7 @@ describe("emitEventAction", () => {
         },
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.data).toEqual({ build_id: "b-123", status: "success", duration_ms: 4500 });
     });
@@ -88,7 +73,7 @@ describe("emitEventAction", () => {
         event: { type: "ping", data: {} },
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.data).toBeUndefined();
     });
@@ -98,31 +83,31 @@ describe("emitEventAction", () => {
         event: { type: "test" },
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect("subject" in result).toBe(false);
     });
 
     it("throws when event field is missing", async () => {
       const config = {} as EmitEventConfig;
-      await expect(emitEventAction(config, "exec-1")).rejects.toThrow("'event' field is required");
+      await expect(emitEventAction(config, "exec-1", undefined, client)).rejects.toThrow("'event' field is required");
     });
 
     it("throws when event.type is missing", async () => {
       const config = { event: {} } as unknown as EmitEventConfig;
-      await expect(emitEventAction(config, "exec-1")).rejects.toThrow("'event.type' field is required");
+      await expect(emitEventAction(config, "exec-1", undefined, client)).rejects.toThrow("'event.type' field is required");
     });
 
     it("generates unique IDs for each invocation", async () => {
       const config: EmitEventConfig = { event: { type: "test" } };
-      const r1 = await emitEventAction(config, "e1");
-      const r2 = await emitEventAction(config, "e1");
+      const r1 = await emitEventAction(config, "e1", undefined, client);
+      const r2 = await emitEventAction(config, "e1", undefined, client);
       expect(r1.id).not.toBe(r2.id);
     });
 
     it("time field is a valid ISO 8601 string", async () => {
       const config: EmitEventConfig = { event: { type: "test" } };
-      const result = await emitEventAction(config, "e1");
+      const result = await emitEventAction(config, "e1", undefined, client);
       const parsed = new Date(result.time as string);
       expect(parsed.toISOString()).toBe(result.time);
     });
@@ -134,7 +119,7 @@ describe("emitEventAction", () => {
         event: { type: "test.event" },
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.type).toBe("test.event");
       expect(result.delivery_errors).toBeUndefined();
@@ -146,7 +131,7 @@ describe("emitEventAction", () => {
         delivery: [],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.type).toBe("test.event");
       expect(result.delivery_errors).toBeUndefined();
@@ -171,7 +156,7 @@ describe("emitEventAction", () => {
         delivery: [{ webhook: { url: "https://events.example.com/ingest" } }],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(fetchSpy).toHaveBeenCalledTimes(1);
       const call = fetchSpy.mock.calls[0] as unknown as [string, RequestInit];
@@ -202,7 +187,7 @@ describe("emitEventAction", () => {
         }],
       };
 
-      await emitEventAction(config, "exec-1", { API_TOKEN: "secret123" });
+      await emitEventAction(config, "exec-1", { API_TOKEN: "secret123" }, client);
 
       const call = fetchSpy.mock.calls[0] as unknown as [string, RequestInit];
       expect((call[1].headers as Record<string, string>)["Authorization"]).toBe("Bearer secret123");
@@ -218,7 +203,7 @@ describe("emitEventAction", () => {
         delivery: [{ webhook: { url: "https://down.example.com" } }],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.delivery_errors).toHaveLength(1);
       expect((result.delivery_errors as any)[0].target).toBe("webhook:https://down.example.com");
@@ -235,7 +220,7 @@ describe("emitEventAction", () => {
         delivery: [{ webhook: { url: "https://unreachable.example.com" } }],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.delivery_errors).toHaveLength(1);
       expect((result.delivery_errors as any)[0].error).toContain("ECONNREFUSED");
@@ -255,7 +240,7 @@ describe("emitEventAction", () => {
         ],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(fetchSpy).toHaveBeenCalledTimes(2);
       expect(result.delivery_errors).toBeUndefined();
@@ -265,13 +250,10 @@ describe("emitEventAction", () => {
   describe("signal delivery (server-mediated SendSignal lane)", () => {
     beforeEach(() => {
       mockSendWorkflowSignal.mockClear();
-      mockClientCtor.mockClear();
       mockSendWorkflowSignal.mockResolvedValue({});
-      mockBackendEndpoint = "http://localhost:7234";
     });
 
-    it("routes through the server resolved by config, addressed by execution_id", async () => {
-      mockBackendEndpoint = "https://api.stigmer.example.com";
+    it("routes through the client it is handed, addressed by execution_id", async () => {
 
       const config: EmitEventConfig = {
         event: { type: "approval.granted" },
@@ -280,11 +262,8 @@ describe("emitEventAction", () => {
         ],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
-      expect(mockClientCtor).toHaveBeenCalledWith(
-        expect.objectContaining({ endpoint: "https://api.stigmer.example.com" }),
-      );
       expect(mockSendWorkflowSignal).toHaveBeenCalledTimes(1);
       const [executionId, signalName, envelope, options] =
         mockSendWorkflowSignal.mock.calls[0] as unknown as [
@@ -314,7 +293,7 @@ describe("emitEventAction", () => {
         ],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(result.delivery_errors).toHaveLength(1);
       expect((result.delivery_errors as any)[0].target).toBe("signal:wfx_done/ping");
@@ -334,7 +313,7 @@ describe("emitEventAction", () => {
         ],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(mockSendWorkflowSignal).not.toHaveBeenCalled();
       expect(result.delivery_errors).toHaveLength(1);
@@ -354,14 +333,14 @@ describe("emitEventAction", () => {
         ],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
       expect(mockSendWorkflowSignal).not.toHaveBeenCalled();
       expect(result.delivery_errors).toHaveLength(1);
       expect((result.delivery_errors as any)[0].error).toContain("'signal_name'");
     });
 
-    it("reuses one client across multiple signal targets", async () => {
+    it("sends every signal target through the one client", async () => {
       const config: EmitEventConfig = {
         event: { type: "fanout" },
         delivery: [
@@ -370,14 +349,13 @@ describe("emitEventAction", () => {
         ],
       };
 
-      const result = await emitEventAction(config, "exec-1");
+      const result = await emitEventAction(config, "exec-1", undefined, client);
 
-      expect(mockClientCtor).toHaveBeenCalledTimes(1);
       expect(mockSendWorkflowSignal).toHaveBeenCalledTimes(2);
       expect(result.delivery_errors).toBeUndefined();
     });
 
-    it("constructs no client for webhook-only delivery", async () => {
+    it("never touches the client for webhook-only delivery", async () => {
       const originalFetch = globalThis.fetch;
       globalThis.fetch = vi.fn(() =>
         Promise.resolve(new Response(null, { status: 200 })),
@@ -389,9 +367,9 @@ describe("emitEventAction", () => {
           delivery: [{ webhook: { url: "https://events.example.com" } }],
         };
 
-        await emitEventAction(config, "exec-1");
+        await emitEventAction(config, "exec-1", undefined, client);
 
-        expect(mockClientCtor).not.toHaveBeenCalled();
+        expect(mockSendWorkflowSignal).not.toHaveBeenCalled();
       } finally {
         globalThis.fetch = originalFetch;
       }