@stigmer/runner 3.0.1

package/src/__tests__/bootstrap.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect, vi } from "vitest";
+import { resolveRunnerBootstrap, refreshRunnerAccessToken } from "../bootstrap.js";
+import type { BootstrapClientFactory } from "../bootstrap.js";
+
+/**
+ * Unit tests for runner Temporal coordinate self-discovery.
+ *
+ * The resolver is the heart of token-only embedding: it decides whether to use
+ * an explicit address, discover one from the control plane, or fall back to
+ * localhost — and it must fail loudly once it commits to discovery.
+ */
+
+/** A factory whose client fails the test if discovery is ever attempted. */
+const failIfCalled: BootstrapClientFactory = async () => ({
+  getRunnerBootstrapConfig: () => {
+    throw new Error("discovery must not be attempted in this scenario");
+  },
+});
+
+describe("resolveRunnerBootstrap", () => {
+  it("uses an explicit address verbatim and never discovers", async () => {
+    const coords = await resolveRunnerBootstrap(
+      {
+        explicitAddress: "temporal.prod:7233",
+        explicitNamespace: "prod",
+        token: "tok_should_be_ignored",
+        stigmerEndpoint: "https://api.stigmer.ai",
+      },
+      failIfCalled,
+    );
+
+    expect(coords).toEqual({
+      temporalAddress: "temporal.prod:7233",
+      temporalNamespace: "prod",
+    });
+  });
+
+  it("falls back to localhost when neither an address nor a token is present", async () => {
+    const coords = await resolveRunnerBootstrap(
+      { stigmerEndpoint: "http://localhost:7234" },
+      failIfCalled,
+    );
+
+    expect(coords).toEqual({
+      temporalAddress: "localhost:7233",
+      temporalNamespace: "default",
+    });
+  });
+
+  it("discovers from the control plane when a token is present and no explicit address", async () => {
+    const getRunnerBootstrapConfig = vi.fn().mockResolvedValue({
+      temporalAddress: "stigmer-temporal.example:7233",
+      temporalNamespace: "tenant-ns",
+    });
+    const factory: BootstrapClientFactory = async (endpoint, token) => {
+      expect(endpoint).toBe("https://api.stigmer.ai");
+      expect(token).toBe("tok_abc");
+      return { getRunnerBootstrapConfig };
+    };
+
+    const coords = await resolveRunnerBootstrap(
+      { token: "tok_abc", stigmerEndpoint: "https://api.stigmer.ai" },
+      factory,
+    );
+
+    expect(getRunnerBootstrapConfig).toHaveBeenCalledOnce();
+    expect(coords).toEqual({
+      temporalAddress: "stigmer-temporal.example:7233",
+      temporalNamespace: "tenant-ns",
+    });
+  });
+
+  it("discovered namespace wins, defaulting to 'default' when blank", async () => {
+    const factory: BootstrapClientFactory = async () => ({
+      getRunnerBootstrapConfig: () =>
+        Promise.resolve({ temporalAddress: "t:7233", temporalNamespace: "" }),
+    });
+
+    const coords = await resolveRunnerBootstrap(
+      { token: "tok", stigmerEndpoint: "https://api.stigmer.ai" },
+      factory,
+    );
+
+    expect(coords.temporalNamespace).toBe("default");
+  });
+
+  it("throws an actionable error when discovery fails (e.g. server too old)", async () => {
+    const factory: BootstrapClientFactory = async () => ({
+      getRunnerBootstrapConfig: () =>
+        Promise.reject(new Error("unimplemented")),
+    });
+
+    await expect(
+      resolveRunnerBootstrap(
+        { token: "tok", stigmerEndpoint: "https://api.stigmer.ai" },
+        factory,
+      ),
+    ).rejects.toThrow(/Failed to discover Temporal coordinates from https:\/\/api\.stigmer\.ai.*TEMPORAL_SERVICE_ADDRESS/s);
+  });
+
+  it("throws when discovery returns an empty address (no silent localhost fallback)", async () => {
+    const factory: BootstrapClientFactory = async () => ({
+      getRunnerBootstrapConfig: () =>
+        Promise.resolve({ temporalAddress: "  ", temporalNamespace: "default" }),
+    });
+
+    await expect(
+      resolveRunnerBootstrap(
+        { token: "tok", stigmerEndpoint: "https://api.stigmer.ai" },
+        factory,
+      ),
+    ).rejects.toThrow(/empty Temporal address/);
+  });
+
+  it("treats a whitespace-only explicit address as unset and discovers", async () => {
+    const getRunnerBootstrapConfig = vi
+      .fn()
+      .mockResolvedValue({ temporalAddress: "t:7233", temporalNamespace: "default" });
+
+    const coords = await resolveRunnerBootstrap(
+      {
+        explicitAddress: "   ",
+        token: "tok",
+        stigmerEndpoint: "https://api.stigmer.ai",
+      },
+      async () => ({ getRunnerBootstrapConfig }),
+    );
+
+    expect(getRunnerBootstrapConfig).toHaveBeenCalledOnce();
+    expect(coords.temporalAddress).toBe("t:7233");
+  });
+
+  it("surfaces the minted runner token from the discovery branch", async () => {
+    const factory: BootstrapClientFactory = async () => ({
+      getRunnerBootstrapConfig: () =>
+        Promise.resolve({
+          temporalAddress: "t:7233",
+          temporalNamespace: "default",
+          runnerAccessToken: "rt_minted",
+          runnerAccessTokenExpiresInSeconds: 3600,
+        }),
+    });
+
+    const result = await resolveRunnerBootstrap(
+      { token: "tok", stigmerEndpoint: "https://api.stigmer.ai" },
+      factory,
+    );
+
+    expect(result.runnerAccessToken).toBe("rt_minted");
+    expect(result.runnerAccessTokenExpiresInSeconds).toBe(3600);
+  });
+
+  it("returns no token from the explicit-address branch (no RPC, so nothing minted)", async () => {
+    const result = await resolveRunnerBootstrap(
+      {
+        explicitAddress: "temporal.prod:7233",
+        token: "tok",
+        stigmerEndpoint: "https://api.stigmer.ai",
+      },
+      failIfCalled,
+    );
+
+    expect(result.runnerAccessToken).toBeUndefined();
+  });
+});
+
+describe("refreshRunnerAccessToken", () => {
+  it("re-mints the proxy token using the current control-plane token", async () => {
+    const getRunnerBootstrapConfig = vi.fn().mockResolvedValue({
+      temporalAddress: "ignored:7233",
+      temporalNamespace: "ignored",
+      runnerAccessToken: "rt_refreshed",
+      runnerAccessTokenExpiresInSeconds: 7200,
+    });
+    const factory: BootstrapClientFactory = async (endpoint, token) => {
+      expect(endpoint).toBe("https://api.stigmer.ai");
+      expect(token).toBe("cp_token_fresh");
+      return { getRunnerBootstrapConfig };
+    };
+
+    const refreshed = await refreshRunnerAccessToken(
+      { token: "cp_token_fresh", stigmerEndpoint: "https://api.stigmer.ai" },
+      factory,
+    );
+
+    expect(refreshed).toEqual({ token: "rt_refreshed", expiresInSeconds: 7200 });
+  });
+
+  it("returns undefined when there is no control-plane token to authenticate with", async () => {
+    const refreshed = await refreshRunnerAccessToken(
+      { token: null, stigmerEndpoint: "https://api.stigmer.ai" },
+      failIfCalled,
+    );
+    expect(refreshed).toBeUndefined();
+  });
+
+  it("returns undefined (not throw) when the server mints no token", async () => {
+    const factory: BootstrapClientFactory = async () => ({
+      getRunnerBootstrapConfig: () =>
+        Promise.resolve({ temporalAddress: "t:7233", temporalNamespace: "default" }),
+    });
+
+    const refreshed = await refreshRunnerAccessToken(
+      { token: "cp", stigmerEndpoint: "https://api.stigmer.ai" },
+      factory,
+    );
+    expect(refreshed).toBeUndefined();
+  });
+
+  it("returns undefined (not throw) when the refresh call fails", async () => {
+    const factory: BootstrapClientFactory = async () => ({
+      getRunnerBootstrapConfig: () => Promise.reject(new Error("network down")),
+    });
+
+    const refreshed = await refreshRunnerAccessToken(
+      { token: "cp", stigmerEndpoint: "https://api.stigmer.ai" },
+      factory,
+    );
+    expect(refreshed).toBeUndefined();
+  });
+});

package/src/__tests__/claimcheck-codec.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { ClaimcheckPayloadCodec } from "../claimcheck/payload-codec.js";
+import { compress } from "../claimcheck/compressor.js";
+import type { ClaimcheckConfig } from "../claimcheck/config.js";
+import type { ArtifactStorage } from "../shared/artifact-storage.js";
+import type { Payload } from "@temporalio/common";
+
+function makeConfig(overrides: Partial<ClaimcheckConfig> = {}): ClaimcheckConfig {
+  return {
+    enabled: true,
+    thresholdBytes: 1024,
+    compressionEnabled: true,
+    keyPrefix: "claimcheck/",
+    ...overrides,
+  };
+}
+
+function makeStorage(): ArtifactStorage & {
+  uploads: Map<string, Buffer>;
+} {
+  const uploads = new Map<string, Buffer>();
+  return {
+    uploads,
+    async upload(key: string, content: Buffer) {
+      uploads.set(key, content);
+      return key;
+    },
+    async getDownloadUrl(key: string) {
+      return `mock://storage/${key}`;
+    },
+    async exists(key: string) {
+      return uploads.has(key);
+    },
+  };
+}
+
+function makePayload(data: string | Buffer): Payload {
+  const buf = typeof data === "string" ? Buffer.from(data) : data;
+  return {
+    metadata: { encoding: Buffer.from("binary/plain") },
+    data: buf,
+  };
+}
+
+function makeLargePayload(sizeBytes: number): Payload {
+  const buf = Buffer.alloc(sizeBytes, "x");
+  return {
+    metadata: { encoding: Buffer.from("binary/plain") },
+    data: buf,
+  };
+}
+
+describe("ClaimcheckPayloadCodec", () => {
+  let storage: ReturnType<typeof makeStorage>;
+  let codec: ClaimcheckPayloadCodec;
+
+  beforeEach(() => {
+    storage = makeStorage();
+    codec = new ClaimcheckPayloadCodec(storage, makeConfig());
+  });
+
+  describe("encode", () => {
+    it("passes through payloads below threshold unchanged", async () => {
+      const payload = makePayload("small data");
+      const [result] = await codec.encode([payload]);
+      expect(result).toBe(payload);
+      expect(storage.uploads.size).toBe(0);
+    });
+
+    it("passes through empty payloads", async () => {
+      const payload: Payload = { metadata: {}, data: undefined };
+      const [result] = await codec.encode([payload]);
+      expect(result).toBe(payload);
+    });
+
+    it("offloads payloads at or above threshold", async () => {
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+
+      expect(result).not.toBe(payload);
+      expect(storage.uploads.size).toBe(1);
+
+      const markerMeta = result.metadata?.["encoding"];
+      expect(Buffer.from(markerMeta!).toString()).toBe("binary/claimcheck");
+
+      const marker = JSON.parse(Buffer.from(result.data!).toString());
+      expect(marker.key).toMatch(/^claimcheck\//);
+      expect(marker.size).toBe(1024);
+      expect(marker.compressed).toBe(true);
+    });
+
+    it("skips compression when it does not reduce size", async () => {
+      const randomBuf = Buffer.from(
+        Array.from({ length: 1024 }, () => Math.floor(Math.random() * 256)),
+      );
+      const payload: Payload = {
+        metadata: { encoding: Buffer.from("binary/plain") },
+        data: randomBuf,
+      };
+
+      const compressedSize = compress(randomBuf).length;
+      if (compressedSize >= randomBuf.length) {
+        const [result] = await codec.encode([payload]);
+        const marker = JSON.parse(Buffer.from(result.data!).toString());
+        expect(marker.compressed).toBe(false);
+
+        const uploaded = storage.uploads.values().next().value!;
+        expect(uploaded.length).toBe(randomBuf.length);
+      }
+    });
+
+    it("does not compress when compression is disabled", async () => {
+      codec = new ClaimcheckPayloadCodec(
+        storage,
+        makeConfig({ compressionEnabled: false }),
+      );
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+
+      const marker = JSON.parse(Buffer.from(result.data!).toString());
+      expect(marker.compressed).toBe(false);
+
+      const uploaded = storage.uploads.values().next().value!;
+      expect(uploaded.length).toBe(1024);
+    });
+
+    it("handles multiple payloads in a batch", async () => {
+      const small = makePayload("tiny");
+      const large = makeLargePayload(2048);
+
+      const results = await codec.encode([small, large]);
+      expect(results[0]).toBe(small);
+      expect(results[1]).not.toBe(large);
+      expect(storage.uploads.size).toBe(1);
+    });
+
+    it("uses configured key prefix", async () => {
+      codec = new ClaimcheckPayloadCodec(
+        storage,
+        makeConfig({ keyPrefix: "custom-prefix/" }),
+      );
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+
+      const marker = JSON.parse(Buffer.from(result.data!).toString());
+      expect(marker.key).toMatch(/^custom-prefix\//);
+    });
+  });
+
+  describe("decode", () => {
+    it("passes through non-claimcheck payloads unchanged", async () => {
+      const payload = makePayload("normal data");
+      const [result] = await codec.decode([payload]);
+      expect(result).toBe(payload);
+    });
+
+    it("retrieves and decompresses offloaded payloads (round-trip)", async () => {
+      const original = makeLargePayload(2048);
+      const [encoded] = await codec.encode([original]);
+
+      const marker = JSON.parse(Buffer.from(encoded.data!).toString());
+      const storedData = storage.uploads.get(marker.key)!;
+
+      vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+        ok: true,
+        arrayBuffer: () => Promise.resolve(storedData.buffer.slice(
+          storedData.byteOffset,
+          storedData.byteOffset + storedData.byteLength,
+        )),
+      }));
+
+      const [decoded] = await codec.decode([encoded]);
+      expect(Buffer.from(decoded.data!)).toEqual(original.data);
+
+      vi.unstubAllGlobals();
+    });
+
+    it("retrieves uncompressed payloads correctly", async () => {
+      codec = new ClaimcheckPayloadCodec(
+        storage,
+        makeConfig({ compressionEnabled: false }),
+      );
+
+      const original = makeLargePayload(1500);
+      const [encoded] = await codec.encode([original]);
+
+      const marker = JSON.parse(Buffer.from(encoded.data!).toString());
+      const storedData = storage.uploads.get(marker.key)!;
+
+      vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+        ok: true,
+        arrayBuffer: () => Promise.resolve(storedData.buffer.slice(
+          storedData.byteOffset,
+          storedData.byteOffset + storedData.byteLength,
+        )),
+      }));
+
+      const [decoded] = await codec.decode([encoded]);
+      expect(Buffer.from(decoded.data!)).toEqual(original.data);
+
+      vi.unstubAllGlobals();
+    });
+
+    it("throws on download failure", async () => {
+      const encoded: Payload = {
+        metadata: { encoding: Buffer.from("binary/claimcheck") },
+        data: Buffer.from(JSON.stringify({
+          key: "claimcheck/missing",
+          size: 100,
+          compressed: false,
+        })),
+      };
+
+      vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+        ok: false,
+        status: 404,
+      }));
+
+      await expect(codec.decode([encoded])).rejects.toThrow(
+        /Claimcheck retrieve failed.*HTTP 404/,
+      );
+
+      vi.unstubAllGlobals();
+    });
+  });
+
+  describe("threshold boundary", () => {
+    it("does NOT offload at threshold - 1", async () => {
+      const payload = makeLargePayload(1023);
+      const [result] = await codec.encode([payload]);
+      expect(result).toBe(payload);
+    });
+
+    it("offloads at exactly threshold", async () => {
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+      expect(result).not.toBe(payload);
+    });
+
+    it("offloads above threshold", async () => {
+      const payload = makeLargePayload(1025);
+      const [result] = await codec.encode([payload]);
+      expect(result).not.toBe(payload);
+    });
+  });
+
+  describe("compressor", () => {
+    it("compresses and decompresses correctly", async () => {
+      const { compress: c, decompress: d } = await import("../claimcheck/compressor.js");
+      const input = Buffer.from("hello world ".repeat(100));
+      const compressed = c(input);
+      expect(compressed.length).toBeLessThan(input.length);
+      const decompressed = d(compressed);
+      expect(decompressed).toEqual(input);
+    });
+  });
+});

package/src/__tests__/config.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { loadConfig } from "../config.js";
+
+describe("loadConfig", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = {
+      HOME: originalEnv.HOME,
+      PATH: originalEnv.PATH,
+      WORKSPACE_ROOT_DIR: "/tmp/test-workspace",
+    };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it("loads defaults in local mode", () => {
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.mode).toBe("local");
+    expect(config.taskQueue).toBe("stigmer_runner");
+    // temporalAddress is left empty by loadConfig now — it is resolved later by
+    // the factory (resolveRunnerBootstrap), which falls back to localhost
+    // for a tokenless local runner. loadConfig no longer hardcodes the default.
+    expect(config.temporalAddress).toBe("");
+    expect(config.temporalNamespace).toBe("default");
+    expect(config.stigmerBackendEndpoint).toBe("http://localhost:7234");
+    expect(config.stigmerToken).toBeNull();
+    expect(config.cursorApiKey).toBe("test-key");
+    expect(config.proxyEndpoint).toBeNull();
+    expect(config.maxConcurrentActivities).toBe(5);
+  });
+
+  it("respects STIGMER_TASK_QUEUE", () => {
+    process.env.STIGMER_TASK_QUEUE = "runner:abc123";
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.taskQueue).toBe("runner:abc123");
+  });
+
+  it("respects TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE as fallback", () => {
+    process.env.TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE = "custom-queue";
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.taskQueue).toBe("custom-queue");
+  });
+
+  it("no longer requires TEMPORAL_SERVICE_ADDRESS up front in cloud mode", () => {
+    // Token-only embedding: the address is discovered from the control plane at
+    // boot, so loadConfig must NOT fail when it is absent. It is left empty for
+    // the factory to resolve (or throw with an actionable error if discovery
+    // fails). The token + backend endpoint remain required in cloud mode.
+    process.env.MODE = "cloud";
+    process.env.STIGMER_TOKEN = "token";
+    process.env.STIGMER_BACKEND_ENDPOINT = "https://api.example.com";
+
+    const config = loadConfig();
+    expect(config.temporalAddress).toBe("");
+    expect(config.stigmerToken).toBe("token");
+  });
+
+  it("requires STIGMER_TOKEN in cloud mode", () => {
+    process.env.MODE = "cloud";
+    process.env.TEMPORAL_SERVICE_ADDRESS = "temporal:7233";
+    process.env.STIGMER_BACKEND_ENDPOINT = "https://api.example.com";
+
+    expect(() => loadConfig()).toThrow("STIGMER_TOKEN");
+  });
+
+  it("activates proxy mode when STIGMER_PROXY_ENDPOINT is set", () => {
+    process.env.STIGMER_PROXY_ENDPOINT = "https://proxy.example.com";
+    process.env.STIGMER_TOKEN = "token";
+    const config = loadConfig();
+
+    expect(config.proxyEndpoint).toBe("https://proxy.example.com");
+    expect(config.stigmerToken).toBe("token");
+  });
+
+  it("uses STIGMER_TOKEN as cursorApiKey in proxy mode for BiDi proxy auth", () => {
+    process.env.STIGMER_PROXY_ENDPOINT = "https://api.stigmer.ai";
+    process.env.STIGMER_TOKEN = "eyJhbGciOiJSUzI1NiJ9.test-jwt-token";
+    const config = loadConfig();
+
+    expect(config.cursorApiKey).toBe("eyJhbGciOiJSUzI1NiJ9.test-jwt-token");
+  });
+
+  it("prefers explicit CURSOR_API_KEY over STIGMER_TOKEN in proxy mode", () => {
+    process.env.STIGMER_PROXY_ENDPOINT = "https://api.stigmer.ai";
+    process.env.STIGMER_TOKEN = "stigmer-jwt";
+    process.env.CURSOR_API_KEY = "explicit-cursor-key";
+    const config = loadConfig();
+
+    expect(config.cursorApiKey).toBe("explicit-cursor-key");
+  });
+
+  it("falls back to proxy-managed when no token in proxy mode", () => {
+    process.env.MODE = "local";
+    process.env.STIGMER_PROXY_ENDPOINT = "http://localhost:9090";
+    process.env.STIGMER_TOKEN = "token";
+    const config = loadConfig();
+
+    // With STIGMER_TOKEN present, cursorApiKey should be the token
+    expect(config.cursorApiKey).toBe("token");
+  });
+
+  it("normalizes bare host:port to http://", () => {
+    process.env.STIGMER_BACKEND_ENDPOINT = "backend:7234";
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.stigmerBackendEndpoint).toBe("http://backend:7234");
+  });
+
+  it("normalizes :443 endpoints to https://", () => {
+    process.env.STIGMER_BACKEND_ENDPOINT = "api.stigmer.ai:443";
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.stigmerBackendEndpoint).toBe("https://api.stigmer.ai:443");
+  });
+
+  it("preserves existing http:// scheme", () => {
+    process.env.STIGMER_BACKEND_ENDPOINT = "http://localhost:7234";
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.stigmerBackendEndpoint).toBe("http://localhost:7234");
+  });
+
+  it("parses maxConcurrentActivities from env", () => {
+    process.env.TEMPORAL_MAX_CONCURRENCY = "10";
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.maxConcurrentActivities).toBe(10);
+  });
+
+  it("reads cloudModeEnabled flag", () => {
+    process.env.STIGMER_CURSOR_CLOUD_MODE_ENABLED = "true";
+    process.env.CURSOR_API_KEY = "test-key";
+    const config = loadConfig();
+
+    expect(config.cloudModeEnabled).toBe(true);
+  });
+});