@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/shared/__tests__/prompt-sections.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The shared prompt glue (`shared/prompt-sections.ts`): the standing order
+ * and the input-files lines. What each harness renders AROUND these is pinned whole by
+ * the two builders' prompt goldens (`execute-deep-agent/__tests__/
+ * prompt-goldens.test.ts`, `execute-cursor/__tests__/prompt-goldens.test.ts`);
+ * this file pins the glue's own contract, harness-free.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  inputFileLines,
+  standingContextSections,
+  visionPromptInfoOf,
+  type StandingSectionKind,
+} from "../prompt-sections.js";
+import { DOWNLOAD_URL_DISCLOSURE } from "../attachment-download-urls.js";
+import type { ResolvedAttachment } from "../attachment-resolver.js";
+import { formatDeclaredPreferencesText } from "../declared-preferences.js";
+
+describe("standingContextSections", () => {
+  const ORDER: readonly StandingSectionKind[] = [
+    "conversation-sender",
+    "declared-preferences",
+    "recalled-memories",
+    "session-context",
+    "previous-conversation",
+  ];
+
+  it("renders every present section in the one ruled order, whatever order the fields arrive in", () => {
+    const sections = standingContextSections({
+      contextBridge: "bridge",
+      sessionContext: "session",
+      recalledMemories: { facts: ["fact"] },
+      declaredPreferences: { orgContext: "org" },
+      senderIdentity: { value: "15550001111", kind: "whatsapp_phone" },
+    });
+    expect(sections.map((s) => s.kind)).toEqual(ORDER);
+  });
+
+  it("omits an absent section and keeps the relative order of the rest", () => {
+    const sections = standingContextSections({ contextBridge: "bridge", senderIdentity: { value: "U1", kind: "slack_user_id" } });
+    expect(sections.map((s) => s.kind)).toEqual(["conversation-sender", "previous-conversation"]);
+  });
+
+  it("renders nothing for an empty context", () => {
+    expect(standingContextSections({})).toEqual([]);
+  });
+
+  it("carries each body from the fact's own module, unframed", () => {
+    const [section] = standingContextSections({ declaredPreferences: { userContext: "Keep answers terse." } });
+    expect(section?.body).toBe(formatDeclaredPreferencesText({ userContext: "Keep answers terse." }));
+    expect(section?.body.startsWith("<")).toBe(false);
+    expect(section?.body.startsWith("#")).toBe(false);
+  });
+});
+
+describe("inputFileLines", () => {
+  const file = (relativePath: string, extra: Partial<ResolvedAttachment> = {}): ResolvedAttachment => ({
+    filename: relativePath.split("/").pop()!,
+    relativePath,
+    sizeBytes: 1024,
+    ...extra,
+  });
+
+  it("one bullet per file with the size, the rename disclosure and the download URL", () => {
+    const { entries } = inputFileLines(
+      [
+        file(".stigmer/inputs/spec.pdf"),
+        file(".stigmer/inputs/report-2.pdf", { renamedFrom: "report.pdf" }),
+        file(".stigmer/inputs/diagram.png", { downloadUrl: "https://r2.example/d?sig=1" }),
+      ],
+      undefined,
+    );
+    expect(entries).toEqual([
+      "- `.stigmer/inputs/spec.pdf` (1024 bytes)",
+      "- `.stigmer/inputs/report-2.pdf` (1024 bytes) (renamed from duplicate 'report.pdf')",
+      "- `.stigmer/inputs/diagram.png` (1024 bytes) — download URL: https://r2.example/d?sig=1",
+    ]);
+  });
+
+  it("renders the URL hand-off line only when a listed file carries a URL", () => {
+    const withUrl = [file("a.pdf", { downloadUrl: "https://r2.example/a" })];
+    expect(inputFileLines(withUrl, undefined).urlHandoff).toBe(DOWNLOAD_URL_DISCLOSURE);
+    expect(inputFileLines([file("a.pdf")], undefined).urlHandoff).toBeUndefined();
+  });
+
+  it("renders the vision lines only when the turn carries vision facts", () => {
+    expect(inputFileLines([file("a.png")], undefined).vision).toEqual([]);
+    const { vision } = inputFileLines(
+      [file("a.png")],
+      { inlineFilenames: ["a.png"], notViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }] },
+    );
+    expect(vision.some((l) => l.includes("a.png"))).toBe(true);
+    expect(vision.some((l) => l.includes("big.png"))).toBe(true);
+  });
+});
+
+describe("visionPromptInfoOf", () => {
+  it("is undefined when the turn has neither inline images nor degraded ones", () => {
+    expect(visionPromptInfoOf({ visionImages: [], visionNotViewable: [] })).toBeUndefined();
+  });
+
+  it("names the inline images in send order and carries the degraded entries", () => {
+    const info = visionPromptInfoOf({
+      visionImages: [{ filename: "b.png" }, { filename: "a.jpg" }],
+      visionNotViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }],
+    });
+    expect(info).toEqual({
+      inlineFilenames: ["b.png", "a.jpg"],
+      notViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }],
+    });
+  });
+});

package/src/shared/__tests__/recalled-memories.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Unit tests for the recalled-memories module (stigmer/stigmer#293). Like
+ * declared-preferences there is no string key to mirror-guard —
+ * the value rides the typed `RunStatus.recalled_memories` proto
+ * field, so codegen enforces the cross-repo contract. What IS pinned here:
+ * the render-only-when-something-to-say read semantics (disabled OR empty
+ * renders nothing — the enabled bit with zero facts is the remember tool's
+ * signal, not this module's concern), the server-composed fact order,
+ * the content-only rendering (memory_id never reaches the prompt), and the
+ * framing's behavioral contract.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { RecalledMemoriesSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/spec_pb";
+
+import {
+  formatRecalledMemoriesText,
+  readRecalledMemories,
+} from "../recalled-memories.js";
+
+const FACT_OLDER = "Deploys to us-east-1.";
+const FACT_NEWER = "Prefers OpenTofu over Terraform.";
+
+describe("readRecalledMemories", () => {
+  it("reads the facts in server-composed order (oldest-first in both editions)", () => {
+    const recalled = create(RecalledMemoriesSchema, {
+      enabled: true,
+      facts: [
+        { memoryId: "mem_older", content: FACT_OLDER },
+        { memoryId: "mem_newer", content: FACT_NEWER },
+      ],
+    });
+    expect(readRecalledMemories(recalled)).toEqual({
+      facts: [FACT_OLDER, FACT_NEWER],
+    });
+  });
+
+  it("answers undefined when the field is absent (executions from before the field)", () => {
+    expect(readRecalledMemories(undefined)).toBeUndefined();
+  });
+
+  it("answers undefined when recall is disabled — facts on a disabled snapshot are never rendered", () => {
+    const recalled = create(RecalledMemoriesSchema, {
+      enabled: false,
+      facts: [{ memoryId: "mem_1", content: FACT_OLDER }],
+    });
+    expect(readRecalledMemories(recalled)).toBeUndefined();
+  });
+
+  it("answers undefined for enabled-with-zero-facts — a meaningful snapshot state (the remember-tool signal) that renders nothing", () => {
+    const recalled = create(RecalledMemoriesSchema, { enabled: true });
+    expect(readRecalledMemories(recalled)).toBeUndefined();
+  });
+
+  it("drops blank facts defensively and trims the rest — the server never stamps them (write-time min_len)", () => {
+    const recalled = create(RecalledMemoriesSchema, {
+      enabled: true,
+      facts: [
+        { memoryId: "mem_1", content: `  ${FACT_OLDER}  ` },
+        { memoryId: "mem_2", content: "   " },
+      ],
+    });
+    expect(readRecalledMemories(recalled)).toEqual({ facts: [FACT_OLDER] });
+  });
+});
+
+describe("formatRecalledMemoriesText", () => {
+  it("frames the facts as user-confirmed, user-controlled background — never authority", () => {
+    const framed = formatRecalledMemoriesText({ facts: [FACT_OLDER] });
+
+    expect(framed).toContain("this user previously confirmed");
+    expect(framed).toContain("not instructions");
+    expect(framed).toContain("do not override your task or safety rules");
+    expect(framed).toContain("review and delete them at any time");
+  });
+
+  it("renders one list item per fact, preserving the snapshot's order", () => {
+    const framed = formatRecalledMemoriesText({
+      facts: [FACT_OLDER, FACT_NEWER],
+    });
+
+    expect(framed).toContain(`- ${FACT_OLDER}`);
+    expect(framed).toContain(`- ${FACT_NEWER}`);
+    expect(framed.indexOf(FACT_OLDER)).toBeLessThan(framed.indexOf(FACT_NEWER));
+    expect(framed.endsWith(FACT_NEWER)).toBe(true);
+  });
+});

package/src/shared/__tests__/registry-endpoint.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import {
+  resolveRegistryBaseUrl,
+  resolveModelRegistryUrl,
+  buildRegistryHeaders,
+  resetRegistryRouteForTests,
+  routeRegistryThrough,
+} from "../registry-endpoint.js";
+
+describe("resolveRegistryBaseUrl", () => {
+  it("prefers STIGMER_CLOUD_API_URL over everything (explicit override)", () => {
+    const env = {
+      STIGMER_CLOUD_API_URL: "https://override.example.com",
+      STIGMER_PROXY_ENDPOINT: "https://proxy.example.com",
+      STIGMER_BACKEND_ENDPOINT: "http://localhost:7234",
+    };
+    expect(resolveRegistryBaseUrl(env)).toBe("https://override.example.com");
+  });
+
+  it("uses the proxy origin in proxy mode (it serves /v1/proxy/model-registry)", () => {
+    const env = {
+      STIGMER_PROXY_ENDPOINT: "https://api.stigmer.ai",
+      STIGMER_BACKEND_ENDPOINT: "http://localhost:7234",
+    };
+    expect(resolveRegistryBaseUrl(env)).toBe("https://api.stigmer.ai");
+  });
+
+  it("uses the backend endpoint in direct/local mode (no proxy, no override)", () => {
+    const env = { STIGMER_BACKEND_ENDPOINT: "http://localhost:7234" };
+    expect(resolveRegistryBaseUrl(env)).toBe("http://localhost:7234");
+  });
+
+  it("defaults to the local stigmer-server when nothing is set", () => {
+    expect(resolveRegistryBaseUrl({})).toBe("http://localhost:7234");
+  });
+
+  it("normalizes bare host:port endpoints (443 implies TLS)", () => {
+    expect(resolveRegistryBaseUrl({ STIGMER_BACKEND_ENDPOINT: "api.stigmer.ai:443" }))
+      .toBe("https://api.stigmer.ai:443");
+    expect(resolveRegistryBaseUrl({ STIGMER_BACKEND_ENDPOINT: "backend:7234" }))
+      .toBe("http://backend:7234");
+    expect(resolveRegistryBaseUrl({ STIGMER_PROXY_ENDPOINT: "proxy.internal:443" }))
+      .toBe("https://proxy.internal:443");
+  });
+
+  it("treats empty-string env values as unset", () => {
+    const env = {
+      STIGMER_CLOUD_API_URL: "",
+      STIGMER_PROXY_ENDPOINT: "",
+      STIGMER_BACKEND_ENDPOINT: "http://localhost:9999",
+    };
+    expect(resolveRegistryBaseUrl(env)).toBe("http://localhost:9999");
+  });
+});
+
+describe("resolveModelRegistryUrl", () => {
+  it("appends the model registry path to the resolved base", () => {
+    const env = { STIGMER_BACKEND_ENDPOINT: "http://localhost:7234" };
+    expect(resolveModelRegistryUrl(env)).toBe("http://localhost:7234/v1/proxy/model-registry");
+  });
+});
+
+describe("buildRegistryHeaders", () => {
+  it("returns bearer auth when STIGMER_TOKEN is set", () => {
+    expect(buildRegistryHeaders({ STIGMER_TOKEN: "tok-1" }))
+      .toEqual({ Authorization: "Bearer tok-1" });
+  });
+
+  it("falls back to STIGMER_AUTH_TOKEN", () => {
+    expect(buildRegistryHeaders({ STIGMER_AUTH_TOKEN: "tok-2" }))
+      .toEqual({ Authorization: "Bearer tok-2" });
+  });
+
+  it("prefers STIGMER_TOKEN over STIGMER_AUTH_TOKEN", () => {
+    expect(buildRegistryHeaders({ STIGMER_TOKEN: "tok-1", STIGMER_AUTH_TOKEN: "tok-2" }))
+      .toEqual({ Authorization: "Bearer tok-1" });
+  });
+
+  it("returns no headers when tokenless (local server needs none)", () => {
+    expect(buildRegistryHeaders({})).toEqual({});
+  });
+});
+
+describe("the agent host's route", () => {
+  it("outranks every tier and carries the host's token, until it is reset", () => {
+    const env = { STIGMER_CLOUD_API_URL: "https://override.example.com", STIGMER_TOKEN: "runner-token" };
+    routeRegistryThrough("127.0.0.1:4321", "host-token");
+    try {
+      expect(resolveRegistryBaseUrl(env)).toBe("http://127.0.0.1:4321");
+      expect(buildRegistryHeaders(env)).toEqual({ Authorization: "Bearer host-token" });
+    } finally {
+      resetRegistryRouteForTests();
+    }
+    expect(resolveRegistryBaseUrl(env)).toBe("https://override.example.com");
+  });
+});

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

@@ -0,0 +1,109 @@
+/**
+ * The run credential's wire reader and its store (`run-credential.ts`,
+ * `run-credential-store.ts`).
+ *
+ * The property that matters is the last arm: two activities whose awaits
+ * interleave in one process each see their own credential and never the
+ * other's. That is what lets one shared `StigmerClient` — one per worker for
+ * the turn activities — present the right run's credential per request.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  RUN_CREDENTIAL_INPUT_KEY,
+  readRunCredentialFromInput,
+} from "../run-credential.js";
+import {
+  currentRunCredential,
+  withRunCredential,
+} from "../run-credential-store.js";
+
+describe("readRunCredentialFromInput", () => {
+  it("reads a non-empty string under the wire key", () => {
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: "cred-1" }),
+    ).toBe("cred-1");
+  });
+
+  it("answers undefined for the positional string shape the turn activities also accept", () => {
+    expect(readRunCredentialFromInput("aex_123")).toBeUndefined();
+  });
+
+  it("answers undefined for a credential-less object — an older server's dispatch", () => {
+    expect(
+      readRunCredentialFromInput({ execution_id: "aex_123", thread_id: "" }),
+    ).toBeUndefined();
+  });
+
+  it("answers undefined for an empty string, null, undefined and a non-string value", () => {
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: "" }),
+    ).toBeUndefined();
+    expect(readRunCredentialFromInput(null)).toBeUndefined();
+    expect(readRunCredentialFromInput(undefined)).toBeUndefined();
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: 42 }),
+    ).toBeUndefined();
+  });
+
+  it("does not read the connect lane's camelCase per-call token", () => {
+    expect(
+      readRunCredentialFromInput({ executionContextToken: "connect-token" }),
+    ).toBeUndefined();
+  });
+
+  it("pins the wire key as bytes", () => {
+    expect(RUN_CREDENTIAL_INPUT_KEY).toBe("execution_context_token");
+  });
+});
+
+describe("run-credential store", () => {
+  it("is empty outside any activity", () => {
+    expect(currentRunCredential()).toBeUndefined();
+  });
+
+  it("is visible to everything the wrapped function awaits, and gone after", async () => {
+    let inner: string | undefined;
+    await withRunCredential("cred-a", async () => {
+      await Promise.resolve();
+      inner = await (async () => currentRunCredential())();
+    });
+    expect(inner).toBe("cred-a");
+    expect(currentRunCredential()).toBeUndefined();
+  });
+
+  it("is inherited by a promise created inside the scope and settled after it", async () => {
+    let detached: Promise<string | undefined> | undefined;
+    await withRunCredential("cred-b", async () => {
+      detached = new Promise((resolve) =>
+        setTimeout(() => resolve(currentRunCredential()), 5),
+      );
+    });
+    expect(await detached).toBe("cred-b");
+  });
+
+  it("never crosses between two activities whose awaits interleave", async () => {
+    const seen: Array<[string, string | undefined]> = [];
+    const activity = async (name: string, ticks: number) => {
+      for (let i = 0; i < ticks; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        seen.push([name, currentRunCredential()]);
+      }
+    };
+    await Promise.all([
+      withRunCredential("cred-1", () => activity("one", 4)),
+      withRunCredential("cred-2", () => activity("two", 4)),
+      activity("none", 4),
+    ]);
+    expect(seen.filter(([name]) => name === "one").map(([, c]) => c)).toEqual(
+      Array(4).fill("cred-1"),
+    );
+    expect(seen.filter(([name]) => name === "two").map(([, c]) => c)).toEqual(
+      Array(4).fill("cred-2"),
+    );
+    expect(seen.filter(([name]) => name === "none").map(([, c]) => c)).toEqual(
+      Array(4).fill(undefined),
+    );
+  });
+});

package/src/shared/__tests__/run-values.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Pins how a turn receives its values (run-values.ts): the fetch's answer
+ * kept per declarer (a tool's group keyed by its plugin and its server's
+ * name there, a plugin's hook values by plugin id), a repository's token matched by its entry's name and
+ * URL together, a refusal the person fixes kept apart from every other
+ * failure, and the turn's credential presented on the fetch with no
+ * fallback to a read without one.
+ */
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { ExecutionValuesSchema } from "@stigmer/apis/ai/stigmer/agentic/vault/v1/values_pb";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { mockStigmerClient } from "../../__test-utils__/mock-client.js";
+import {
+  fetchRunValues,
+  fetchTurnValues,
+  repositoryTokenFor,
+  RunValuesRefusedError,
+  runValuesOf,
+  toolValuesKey,
+} from "../run-values.js";
+
+const ANSWER = create(ExecutionValuesSchema, {
+  agent: { AGENT_KEY: "agent-secret", LOG_LEVEL: "debug" },
+  tools: [
+    { pluginId: "plg_linear", server: "api", url: "https://mcp.linear.app/mcp", values: { LINEAR_TOKEN: "lin" } },
+    { pluginId: "plg_other", server: "api", url: "", values: { OTHER_TOKEN: "oth" } },
+    { agentId: "plg_other", server: "api", url: "https://zd.example.com/mcp", values: { ZD_KEY: "zd" } },
+  ],
+  plugins: [{ pluginId: "plg_linear", values: { HOOK_KEY: "hook" } }],
+  repositories: [{ name: "app", url: "https://github.com/acme/app.git", token: "ghp_app" }],
+});
+
+beforeEach(() => {
+  vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+describe("runValuesOf", () => {
+  it("keeps each declarer's values in its own group", () => {
+    const values = runValuesOf(ANSWER);
+    expect(values.agent).toEqual({ AGENT_KEY: "agent-secret", LOG_LEVEL: "debug" });
+    expect(values.tools.get(toolValuesKey("plugin", "plg_linear", "api"))).toEqual({ url: "https://mcp.linear.app/mcp", values: { LINEAR_TOKEN: "lin" } });
+    expect(values.tools.get(toolValuesKey("plugin", "plg_other", "api")), "a same-named server of another plugin is its own group").toEqual({
+      url: "",
+      values: { OTHER_TOKEN: "oth" },
+    });
+    expect(values.tools.get(toolValuesKey("agent", "plg_other", "api")), "an agent's own server is its own group, even under a plugin's id").toEqual({
+      url: "https://zd.example.com/mcp",
+      values: { ZD_KEY: "zd" },
+    });
+    expect([...values.plugins]).toEqual([["plg_linear", { HOOK_KEY: "hook" }]]);
+    expect(values.repositories).toEqual([{ name: "app", url: "https://github.com/acme/app.git", token: "ghp_app" }]);
+  });
+});
+
+describe("toolValuesKey", () => {
+  it("keeps a plugin and a server name apart, whatever either holds", () => {
+    expect(toolValuesKey("plugin", "plg_a", "b_c")).not.toBe(toolValuesKey("plugin", "plg_a_b", "c"));
+    expect(toolValuesKey("plugin", "x", "s")).not.toBe(toolValuesKey("agent", "x", "s"));
+  });
+});
+
+describe("repositoryTokenFor", () => {
+  it("matches a repository by its name and URL together, never by one alone", () => {
+    const repositories = runValuesOf(ANSWER).repositories;
+    expect(repositoryTokenFor(repositories, "app", "https://github.com/acme/app.git")).toBe("ghp_app");
+    expect(repositoryTokenFor(repositories, "app", "https://github.com/acme/other.git")).toBeUndefined();
+    expect(repositoryTokenFor(repositories, "web", "https://github.com/acme/app.git")).toBeUndefined();
+  });
+});
+
+describe("fetchRunValues", () => {
+  it("presents the token it is given and answers the values per declarer", async () => {
+    const client = mockStigmerClient({ fetchExecutionValues: vi.fn().mockResolvedValue(ANSWER) });
+
+    const values = await fetchRunValues(client, "run_1", "scoped");
+
+    expect(client.fetchExecutionValues).toHaveBeenCalledWith("run_1", "scoped");
+    expect(values.tools.size).toBe(3);
+    expect(values.plugins.size).toBe(1);
+  });
+
+  it("keeps a refusal the person fixes apart, carrying the server's sentence", async () => {
+    const client = mockStigmerClient({
+      fetchExecutionValues: vi.fn().mockRejectedValue(
+        new ConnectError("LINEAR_TOKEN for Linear is gone from vault 'Support': fix it and recover", Code.FailedPrecondition),
+      ),
+    });
+
+    const failure = fetchRunValues(client, "run_1");
+    await expect(failure).rejects.toBeInstanceOf(RunValuesRefusedError);
+    await expect(failure).rejects.toThrow("LINEAR_TOKEN for Linear is gone from vault 'Support': fix it and recover");
+  });
+
+  it("propagates every other failure as it is: a refused credential is the platform's", async () => {
+    const denied = new ConnectError("not bound to this execution", Code.PermissionDenied);
+    const client = mockStigmerClient({ fetchExecutionValues: vi.fn().mockRejectedValue(denied) });
+
+    await expect(fetchRunValues(client, "run_1")).rejects.toBe(denied);
+  });
+});
+
+describe("fetchTurnValues", () => {
+  it("presents the turn's own credential on the fetch", async () => {
+    const client = mockStigmerClient({
+      acquireScopedRunnerToken: vi.fn().mockResolvedValue("run-credential"),
+      fetchExecutionValues: vi.fn().mockResolvedValue(ANSWER),
+    });
+
+    await fetchTurnValues(client, "run_1");
+
+    expect(client.acquireScopedRunnerToken).toHaveBeenCalledWith({ agentExecutionId: "run_1" });
+    expect(client.fetchExecutionValues).toHaveBeenCalledWith("run_1", "run-credential");
+  });
+
+  it("fetches nothing when no credential can be had: there is no read without one", async () => {
+    const client = mockStigmerClient({
+      acquireScopedRunnerToken: vi.fn().mockRejectedValue(new Error("Server minted no scoped runner token")),
+    });
+
+    await expect(fetchTurnValues(client, "run_1")).rejects.toThrow("Server minted no scoped runner token");
+    expect(client.fetchExecutionValues).not.toHaveBeenCalled();
+  });
+});