@stigmer/runner 3.1.9 → 3.1.11

package/src/config.ts

@@ -230,8 +230,11 @@ function requireEnv(name: string): string {
 /**
  * Ensures the endpoint has an HTTP(S) scheme. Port 443 implies TLS;
  * all other bare host:port endpoints get http://.
+ *
+ * Exported so registry-endpoint.ts applies the same normalization to
+ * STIGMER_BACKEND_ENDPOINT that this module applies when loading config.
  */
-function normalizeEndpoint(endpoint: string): string {
+export function normalizeEndpoint(endpoint: string): string {
   if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
     return endpoint;
   }

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

@@ -1,5 +1,11 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { getSummarizationModel, getEconomyModel, getDefaultModel, _resetRegistryCache } from "../model-registry.js";
+import {
+  getSummarizationModel,
+  getEconomyModel,
+  getDefaultModel,
+  resolveToApiModelId,
+  _resetRegistryCache,
+} from "../model-registry.js";
 
 describe("getSummarizationModel", () => {
   beforeEach(() => {
@@ -178,6 +184,73 @@ describe("getDefaultModel", () => {
   });
 });
 
+describe("resolveToApiModelId", () => {
+  beforeEach(() => {
+    _resetRegistryCache();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    _resetRegistryCache();
+    vi.useRealTimers();
+  });
+
+  it("resolves a canonical registry id to the provider api id", async () => {
+    mockRegistryResponse([
+      { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic", costTier: "economy", harness: "native" },
+    ]);
+
+    const result = await resolveToApiModelId("claude-haiku-4.5");
+    expect(result).toBe("claude-haiku-4-5-20251001");
+  });
+
+  it("passes unknown ids through unchanged (provider api ids stay verbatim)", async () => {
+    mockRegistryResponse([
+      { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic", costTier: "economy", harness: "native" },
+    ]);
+
+    const result = await resolveToApiModelId("claude-haiku-4-5-20251001");
+    expect(result).toBe("claude-haiku-4-5-20251001");
+  });
+
+  it("degrades to pass-through when the registry fetch fails", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValueOnce(new Error("network error"));
+
+    const result = await resolveToApiModelId("claude-haiku-4.5");
+    expect(result).toBe("claude-haiku-4.5");
+  });
+
+  it("retries after the short failure TTL instead of caching the failure for an hour", async () => {
+    vi.useFakeTimers();
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockRejectedValueOnce(new Error("network error"))
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            models: [
+              { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic", costTier: "economy", harness: "native" },
+            ],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+      );
+
+    // First call fails and degrades to pass-through.
+    expect(await resolveToApiModelId("claude-haiku-4.5")).toBe("claude-haiku-4.5");
+
+    // Within the failure TTL the empty result stays cached (no refetch).
+    vi.advanceTimersByTime(30_000);
+    expect(await resolveToApiModelId("claude-haiku-4.5")).toBe("claude-haiku-4.5");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    // Past the failure TTL the registry is refetched and resolution recovers.
+    vi.advanceTimersByTime(31_000);
+    expect(await resolveToApiModelId("claude-haiku-4.5")).toBe("claude-haiku-4-5-20251001");
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+  });
+});
+
 interface MockModel {
   id: string;
   apiModelId?: string;

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

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest";
+import {
+  resolveRegistryBaseUrl,
+  resolveModelRegistryUrl,
+  buildRegistryHeaders,
+} 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({});
+  });
+});

package/src/shared/model-pricing-data.ts

@@ -30,7 +30,8 @@ interface RegistryEntry {
   };
 }
 
-const DEFAULT_API_URL = "https://api.stigmer.ai";
+import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
+
 const CACHE_TTL_MS = 3_600_000;
 
 export const DEFAULT_PRICING: ModelPricing = {
@@ -65,13 +66,7 @@ function parsePricingTable(json: unknown): ModelPricing[] {
 }
 
 async function fetchFromApi(): Promise<readonly ModelPricing[]> {
-  const url = `${process.env.STIGMER_CLOUD_API_URL ?? DEFAULT_API_URL}/v1/proxy/model-registry`;
-  const headers: Record<string, string> = {};
-  const token = process.env.STIGMER_TOKEN ?? process.env.STIGMER_AUTH_TOKEN;
-  if (token) {
-    headers["Authorization"] = `Bearer ${token}`;
-  }
-  const res = await fetch(url, { headers });
+  const res = await fetch(resolveModelRegistryUrl(), { headers: buildRegistryHeaders() });
   if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
   const data: unknown = await res.json();
   const table = parsePricingTable(data);

package/src/shared/model-registry.ts

@@ -1,13 +1,19 @@
 /**
  * Model registry — provider lookup and economy-tier model derivation.
  *
- * Fetches the model registry from the Stigmer API (same endpoint as
+ * Fetches the model registry from the runner's control plane (see
+ * registry-endpoint.ts for endpoint resolution — same endpoint as
  * model-pricing-data.ts) and uses `costTier` + `harness` fields to
  * dynamically resolve economy-tier models for extraction/summarization.
  */
 
-const DEFAULT_API_URL = "https://api.stigmer.ai";
+import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
+
 const CACHE_TTL_MS = 3_600_000;
+// Failed fetches are cached much shorter than successes: a transient failure
+// must not poison id -> apiModelId resolution (and thereby fail every llm_call
+// with LLM_MODEL_NOT_FOUND) for a full hour.
+const FAILURE_CACHE_TTL_MS = 60_000;
 
 interface RegistryModel {
   id: string;
@@ -39,13 +45,8 @@ function parseRegistry(json: unknown): RegistryModel[] {
 }
 
 async function fetchRegistry(): Promise<readonly RegistryModel[]> {
-  const url = `${process.env.STIGMER_CLOUD_API_URL ?? DEFAULT_API_URL}/v1/proxy/model-registry`;
-  const headers: Record<string, string> = {};
-  const token = process.env.STIGMER_TOKEN ?? process.env.STIGMER_AUTH_TOKEN;
-  if (token) {
-    headers["Authorization"] = `Bearer ${token}`;
-  }
-  const res = await fetch(url, { headers });
+  const url = resolveModelRegistryUrl();
+  const res = await fetch(url, { headers: buildRegistryHeaders() });
   if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
   const data: unknown = await res.json();
   return parseRegistry(data);
@@ -64,8 +65,13 @@ async function getRegistry(): Promise<readonly RegistryModel[]> {
       return models;
     })
     .catch((err) => {
-      console.warn(`Failed to fetch model registry for provider lookup: ${err}`);
-      cache = { models: [], expiresAt: Date.now() + CACHE_TTL_MS };
+      console.warn(
+        `Failed to fetch model registry from ${resolveModelRegistryUrl()}: ${err}. ` +
+          `Model id resolution degrades to pass-through until the next attempt ` +
+          `(${FAILURE_CACHE_TTL_MS / 1000}s). Check that the control plane is ` +
+          `reachable and, for cloud endpoints, that STIGMER_TOKEN is set.`,
+      );
+      cache = { models: [], expiresAt: Date.now() + FAILURE_CACHE_TTL_MS };
       return [] as readonly RegistryModel[];
     })
     .finally(() => {

package/src/shared/registry-endpoint.ts

@@ -0,0 +1,53 @@
+/**
+ * Registry endpoint resolution — where the runner fetches the model registry.
+ *
+ * The model registry (canonical id → provider apiModelId, pricing, tiers) is
+ * served at `/v1/proxy/model-registry` by whichever control plane the runner
+ * talks to: the cloud API in proxy mode, or the local stigmer-server in
+ * direct/local mode (stigmer/stigmer#240). Resolution is therefore
+ * topology-based, not token-based:
+ *
+ *   1. STIGMER_CLOUD_API_URL — explicit override (tests, unusual topologies)
+ *   2. STIGMER_PROXY_ENDPOINT — proxy mode: the origin that serves the rest of
+ *      the runner's /v1/proxy surface (LLM proxy, checkpoints, artifacts) also
+ *      serves the registry
+ *   3. STIGMER_BACKEND_ENDPOINT — direct/local mode: the runner's own control
+ *      plane, defaulting to the local stigmer-server address
+ *
+ * A hardcoded cloud URL is deliberately absent: every runner already knows a
+ * control-plane origin that serves the registry, so falling back to the hosted
+ * API would only mask misconfiguration (and breaks offline/local use).
+ */
+
+import { normalizeEndpoint } from "../config.js";
+
+/** Default local stigmer-server origin — mirrors config.ts's local-mode default. */
+const DEFAULT_LOCAL_BACKEND = "http://localhost:7234";
+
+/**
+ * Resolve the base URL (origin, no path) for model-registry and pricing
+ * fetches. See module doc for the tier order.
+ */
+export function resolveRegistryBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.STIGMER_CLOUD_API_URL;
+  if (override) return normalizeEndpoint(override);
+
+  const proxyEndpoint = env.STIGMER_PROXY_ENDPOINT;
+  if (proxyEndpoint) return normalizeEndpoint(proxyEndpoint);
+
+  return normalizeEndpoint(env.STIGMER_BACKEND_ENDPOINT ?? DEFAULT_LOCAL_BACKEND);
+}
+
+/**
+ * Build request headers for registry fetches: bearer auth when a token is
+ * present (cloud requires it; the local server ignores it).
+ */
+export function buildRegistryHeaders(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const token = env.STIGMER_TOKEN ?? env.STIGMER_AUTH_TOKEN;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+/** Full URL of the model registry endpoint for the resolved control plane. */
+export function resolveModelRegistryUrl(env: NodeJS.ProcessEnv = process.env): string {
+  return `${resolveRegistryBaseUrl(env)}/v1/proxy/model-registry`;
+}

package/src/workflow-engine/__tests__/loader.test.ts

@@ -1343,6 +1343,99 @@ do:
       }
     });
 
+    it("call: human_input with payload and ui_hint", () => {
+      const yaml = `
+document:
+  dsl: '1.0.0'
+  name: test
+do:
+  - reviewGate:
+      call: human_input
+      with:
+        prompt: "Review the proposal"
+        payload: \${ $context.proposal }
+        ui_hint: infra-proposal
+`;
+      const model = loadWorkflowFromYaml(yaml);
+      const task = model.do[0].task;
+      expect(task.kind).toBe("human_input");
+      if (task.kind === "human_input") {
+        expect(task.humanInput.payload).toBe("${ $context.proposal }");
+        expect(task.humanInput.uiHint).toBe("infra-proposal");
+      }
+    });
+
+    it("call: human_input with an inline object payload", () => {
+      const yaml = `
+document:
+  dsl: '1.0.0'
+  name: test
+do:
+  - reviewGate:
+      call: human_input
+      with:
+        prompt: "Review the summary"
+        payload:
+          summary: "Severity: \${ $context.triage.severity }"
+          static: true
+`;
+      const model = loadWorkflowFromYaml(yaml);
+      const task = model.do[0].task;
+      expect(task.kind).toBe("human_input");
+      if (task.kind === "human_input") {
+        expect(task.humanInput.payload).toEqual({
+          summary: "Severity: ${ $context.triage.severity }",
+          static: true,
+        });
+      }
+    });
+
+    it("call: human_input without payload/ui_hint leaves both undefined", () => {
+      const yaml = `
+document:
+  dsl: '1.0.0'
+  name: test
+do:
+  - plainGate:
+      call: human_input
+      with:
+        prompt: "Just approve"
+`;
+      const model = loadWorkflowFromYaml(yaml);
+      const task = model.do[0].task;
+      expect(task.kind).toBe("human_input");
+      if (task.kind === "human_input") {
+        expect(task.humanInput.payload).toBeUndefined();
+        expect(task.humanInput.uiHint).toBeUndefined();
+      }
+    });
+
+    it("call: human_input drops a non-string or empty ui_hint", () => {
+      const yaml = `
+document:
+  dsl: '1.0.0'
+  name: test
+do:
+  - badHint:
+      call: human_input
+      with:
+        prompt: "Approve"
+        ui_hint: 42
+  - emptyHint:
+      call: human_input
+      with:
+        prompt: "Approve"
+        ui_hint: ""
+`;
+      const model = loadWorkflowFromYaml(yaml);
+      for (const entry of model.do) {
+        expect(entry.task.kind).toBe("human_input");
+        if (entry.task.kind === "human_input") {
+          expect(entry.task.humanInput.uiHint).toBeUndefined();
+        }
+      }
+    });
+
     it("call: human_input missing prompt throws", () => {
       const yaml = `
 document:

package/src/workflow-engine/__tests__/resolve.test.ts

@@ -136,6 +136,56 @@ describe("resolveConfigExpressions", () => {
     expect(result.value).toBe(3);
     expect(frozen.value).toBe("${ 1 + 2 }");
   });
+
+  it("never re-interprets literal ${ } text nested inside a Phase-1 object result (injection safety)", async () => {
+    // A strict expression resolving to external data (webhook body, API
+    // response, document under review) may contain literal `${ ... }`
+    // text at any depth. Phase 2 must skip the entire resolved subtree —
+    // not just a string at the exact resolved path.
+    const config = { payload: "${ $context.article }" };
+
+    const state = createState();
+    state.context = {
+      article: {
+        body: "Use ${ .secrets.KEY } to authenticate",
+        steps: ["run ${ $env.HOME }/setup.sh"],
+      },
+    };
+
+    const result = await resolveConfigExpressions(
+      config,
+      null,
+      state,
+      evaluateExpressionBatch,
+    );
+
+    expect(result.payload).toEqual({
+      body: "Use ${ .secrets.KEY } to authenticate",
+      steps: ["run ${ $env.HOME }/setup.sh"],
+    });
+  });
+
+  it("still interpolates embedded expressions in sibling fields alongside a Phase-1 object result", async () => {
+    // The subtree skip is scoped to the resolved path only — template
+    // strings elsewhere in the config keep working.
+    const config = {
+      payload: "${ $context.doc }",
+      note: "Reviewing ${ $context.doc.title }",
+    };
+
+    const state = createState();
+    state.context = { doc: { title: "Q3 plan", raw: "keep ${ .this } intact" } };
+
+    const result = await resolveConfigExpressions(
+      config,
+      null,
+      state,
+      evaluateExpressionBatch,
+    );
+
+    expect(result.payload).toEqual({ title: "Q3 plan", raw: "keep ${ .this } intact" });
+    expect(result.note).toBe("Reviewing Q3 plan");
+  });
 });
 
 describe("isRuntimePlaceholder", () => {

package/src/workflow-engine/__tests__/task-status-accumulator.test.ts

@@ -221,6 +221,41 @@ describe("TaskStatusAccumulator", () => {
       expect(entry.status).toBe("waiting_approval");
       expect(entry.input).toEqual({ prompt: "Approve?" });
     });
+
+    it("records the review-surface uiHint", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("gate", "human_input");
+      acc.taskWaitingApproval("gate", "article-diff");
+      const [entry] = acc.toArray();
+      expect(entry.uiHint).toBe("article-diff");
+    });
+
+    it("leaves uiHint undefined when the gate declares no hint", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("gate", "human_input");
+      acc.taskWaitingApproval("gate");
+      const [entry] = acc.toArray();
+      expect(entry.uiHint).toBeUndefined();
+    });
+
+    it("retains uiHint after the gate resolves to completed", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("gate", "human_input");
+      acc.taskWaitingApproval("gate", "article-diff");
+      acc.taskCompleted("gate", 500);
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("completed");
+      expect(entry.uiHint).toBe("article-diff");
+    });
+
+    it("preserves a previously recorded uiHint when re-entering without one", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("gate", "human_input");
+      acc.taskWaitingApproval("gate", "article-diff");
+      acc.taskWaitingApproval("gate");
+      const [entry] = acc.toArray();
+      expect(entry.uiHint).toBe("article-diff");
+    });
   });
 
   describe("taskSkipped", () => {