@stigmer/runner 3.0.1

package/src/shared/mcp-manager.ts

@@ -0,0 +1,150 @@
+/**
+ * MCP connection manager for the deep agent execution path.
+ *
+ * Wraps @langchain/mcp-adapters MultiServerMCPClient with:
+ * - Conversion from ResolvedMcpServer[] to the SDK's Connection config
+ * - Proper async cleanup via close()
+ * - Cloud compatibility validation (warn on non-installable stdio commands)
+ * - Tool filtering based on discovered capabilities
+ *
+ * The Cursor execution path does NOT use this manager — it passes MCP
+ * configs directly to the Cursor SDK via toCursorMcpConfig(). This
+ * manager is exclusively for LangGraph-based deep agent executions.
+ */
+
+import { MultiServerMCPClient } from "@langchain/mcp-adapters";
+import type { Connection } from "@langchain/mcp-adapters";
+import type { DynamicStructuredTool } from "@langchain/core/tools";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+
+const CLOUD_SAFE_COMMANDS = new Set(["npx", "node", "uvx", "python", "python3"]);
+
+/**
+ * Classifies a stdio command's compatibility with cloud execution.
+ * Returns true for commands that are installable/available in typical
+ * cloud environments (npx, node, uvx, python).
+ */
+export function isCloudCompatibleCommand(command: string): boolean {
+  const base = command.split("/").pop() ?? command;
+  return CLOUD_SAFE_COMMANDS.has(base);
+}
+
+/**
+ * Log warnings for MCP servers that may not work in cloud mode.
+ * Does not filter or reject — just provides operator visibility.
+ */
+export function warnCloudIncompatibleServers(
+  servers: ResolvedMcpServer[],
+  isCloudMode: boolean,
+): void {
+  if (!isCloudMode) return;
+
+  for (const server of servers) {
+    if (server.connectionType === "stdio" && server.command) {
+      if (!isCloudCompatibleCommand(server.command)) {
+        console.warn(
+          `[MCP] Server '${server.slug}' uses stdio command '${server.command}' ` +
+          `which may not be available in cloud execution environments. ` +
+          `Consider using an HTTP MCP server or an npx-installable package.`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Convert harness-agnostic ResolvedMcpServer[] into the
+ * MultiServerMCPClient connection config format.
+ */
+export function toMcpClientConfig(
+  servers: ResolvedMcpServer[],
+): Record<string, Connection> {
+  const config: Record<string, Connection> = {};
+
+  for (const server of servers) {
+    if (server.connectionType === "stdio") {
+      if (!server.command) continue;
+      config[server.slug] = {
+        transport: "stdio",
+        command: server.command,
+        args: server.args ?? [],
+        env: server.env ?? processEnvAsStrings(),
+        cwd: server.cwd,
+      };
+    } else if (server.connectionType === "http" || server.connectionType === "sse") {
+      if (!server.url) continue;
+      config[server.slug] = {
+        transport: "http",
+        url: server.url,
+        headers: server.headers,
+      };
+    }
+  }
+
+  return config;
+}
+
+export interface McpConnectionResult {
+  client: MultiServerMCPClient;
+  tools: DynamicStructuredTool[];
+  serverToolMap: Record<string, DynamicStructuredTool[]>;
+}
+
+/**
+ * Create and initialize MCP connections from resolved server specs.
+ *
+ * The caller is responsible for calling result.client.close() when
+ * done — typically in a finally block or via a cleanup handler.
+ */
+export async function connectMcpServers(
+  servers: ResolvedMcpServer[],
+  options?: { isCloudMode?: boolean },
+): Promise<McpConnectionResult> {
+  if (options?.isCloudMode) {
+    warnCloudIncompatibleServers(servers, true);
+  }
+
+  const connectionConfig = toMcpClientConfig(servers);
+
+  if (Object.keys(connectionConfig).length === 0) {
+    const client = new MultiServerMCPClient({});
+    return { client, tools: [], serverToolMap: {} };
+  }
+
+  const client = new MultiServerMCPClient(connectionConfig);
+  const serverToolMap = await client.initializeConnections();
+
+  const tools: DynamicStructuredTool[] = [];
+  for (const serverTools of Object.values(serverToolMap)) {
+    tools.push(...serverTools);
+  }
+
+  console.log(
+    `[MCP] Connected ${Object.keys(serverToolMap).length} server(s), ` +
+    `${tools.length} tool(s) total: ${Object.entries(serverToolMap)
+      .map(([name, t]) => `${name}(${t.length})`)
+      .join(", ")}`,
+  );
+
+  return { client, tools, serverToolMap };
+}
+
+/**
+ * Snapshot of process.env as a string-only record (no undefined values).
+ * Used as a fallback when an MCP server has no declared env — the
+ * subprocess inherits the runner's full environment, matching standard
+ * Unix child-process behavior.
+ *
+ * Without this, @modelcontextprotocol/sdk only passes a restricted
+ * whitelist (HOME, PATH, USER, etc.) which drops platform variables
+ * like STIGMER_SERVER_ADDRESS.
+ */
+function processEnvAsStrings(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) {
+      env[key] = value;
+    }
+  }
+  return env;
+}

package/src/shared/mcp-resolver.ts

@@ -0,0 +1,150 @@
+/**
+ * Resolves Stigmer McpServerUsage references into an intermediate
+ * ResolvedMcpServer format that is harness-agnostic.
+ *
+ * Both ExecuteCursor and ExecuteDeepAgent need MCP server connection info
+ * and tool approval policies. This module provides the common resolution
+ * logic; each harness maps ResolvedMcpServer into its SDK-specific format.
+ */
+
+import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import {
+  resolveHeaders,
+  resolvePlaceholders,
+  filterEnvToDeclaredKeys,
+  PlaceholderResolutionError,
+} from "./placeholder-resolver.js";
+
+/**
+ * Harness-agnostic intermediate representation of a resolved MCP server.
+ * Contains connection info and approval policies. Each harness maps this
+ * into its SDK-specific format (e.g., Cursor McpServerConfig, LangGraph
+ * MultiServerMCPClient config).
+ */
+export interface ResolvedMcpServer {
+  slug: string;
+  connectionType: "stdio" | "http" | "sse";
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  toolApprovals: ToolApprovalPolicy[];
+  pinnedToolApprovals: ToolApprovalPolicy[];
+  discoveredCapabilitiesEmpty: boolean;
+}
+
+export interface McpResolutionResult {
+  resolvedServers: ResolvedMcpServer[];
+}
+
+/**
+ * Fetch McpServer resources and resolve into intermediate format.
+ */
+export async function resolveMcpServers(
+  client: StigmerClient,
+  usages: McpServerUsage[],
+  envVars: Record<string, string> = {},
+): Promise<McpResolutionResult> {
+  const resolved: ResolvedMcpServer[] = [];
+
+  for (const usage of usages) {
+    const ref = usage.mcpServerRef;
+    if (!ref?.slug) continue;
+
+    try {
+      const mcpServer = await client.getMcpServerByReference(ref);
+      const serverEnv = filterEnvToDeclaredKeys(
+        mcpServer.spec?.env,
+        envVars,
+        ref.slug,
+      );
+      const server = mcpServerToResolved(mcpServer, ref.slug, serverEnv);
+      if (server) resolved.push(server);
+    } catch (err) {
+      if (err instanceof PlaceholderResolutionError) {
+        console.error(
+          `MCP server ${ref.org}/${ref.slug}: ${err.message}`,
+        );
+      } else {
+        console.warn(
+          `Failed to resolve MCP server ${ref.org}/${ref.slug}: ${err instanceof Error ? err.message : err}`,
+        );
+      }
+    }
+  }
+
+  return { resolvedServers: resolved };
+}
+
+export function mcpServerToResolved(
+  server: McpServer,
+  slug: string,
+  envVars: Record<string, string>,
+): ResolvedMcpServer | null {
+  const spec = server.spec;
+  if (!spec) return null;
+
+  const status = server.status;
+  const toolApprovals = status?.toolApprovals ?? [];
+  const pinnedToolApprovals = spec.pinnedToolApprovals ?? [];
+  const discoveredCapabilitiesEmpty = !status?.discoveredCapabilities
+    || (status.discoveredCapabilities.tools.length === 0
+      && status.discoveredCapabilities.resourceTemplates.length === 0);
+
+  const base = {
+    toolApprovals,
+    pinnedToolApprovals,
+    discoveredCapabilitiesEmpty,
+  };
+
+  switch (spec.serverType.case) {
+    case "stdio": {
+      const stdio = spec.serverType.value;
+      if (!stdio.command) return null;
+      const resolvedArgs = stdio.args.length > 0
+        ? stdio.args.map((arg, i) =>
+            resolvePlaceholders(arg, envVars, `stdio arg[${i}]`),
+          )
+        : undefined;
+      return {
+        slug,
+        connectionType: "stdio",
+        command: stdio.command,
+        args: resolvedArgs,
+        env: Object.keys(envVars).length > 0 ? { ...envVars } : undefined,
+        cwd: stdio.workingDir || undefined,
+        ...base,
+      };
+    }
+    case "http": {
+      const http = spec.serverType.value;
+      if (!http.url) return null;
+      const rawHeaders = Object.keys(http.headers).length > 0 ? http.headers : undefined;
+      const resolved = rawHeaders
+        ? resolveHeaders(Object.fromEntries(Object.entries(rawHeaders)), envVars)
+        : undefined;
+      return {
+        slug,
+        connectionType: "http",
+        url: http.url,
+        headers: resolved,
+        ...base,
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+export function extractMcpServerSlugs(usages: McpServerUsage[]): string[] {
+  return usages
+    .map((u) => u.mcpServerRef?.slug)
+    .filter((s): s is string => !!s);
+}
+
+export { PlaceholderResolutionError } from "./placeholder-resolver.js";

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

@@ -0,0 +1,109 @@
+/**
+ * Model pricing data — fetched from the model registry API and cached.
+ *
+ * On first access, fetches the full model registry, filters to models
+ * with pricing info, and caches the result. Falls back to conservative
+ * default pricing if the API is unreachable.
+ */
+
+export interface ModelPricing {
+  readonly model: string;
+  readonly displayName: string;
+  readonly costTier: string;
+  readonly inputPricePerMillion: number;
+  readonly outputPricePerMillion: number;
+  readonly cacheWritePricePerMillion: number;
+  readonly cacheReadPricePerMillion: number;
+}
+
+interface RegistryEntry {
+  id: string;
+  displayName: string;
+  provider: string;
+  harness: string;
+  costTier?: string;
+  pricing?: {
+    inputPricePerMillion: number;
+    outputPricePerMillion: number;
+    cacheWritePricePerMillion: number;
+    cacheReadPricePerMillion: number;
+  };
+}
+
+const DEFAULT_API_URL = "https://api.stigmer.ai";
+const CACHE_TTL_MS = 3_600_000;
+
+export const DEFAULT_PRICING: ModelPricing = {
+  model: "unknown",
+  displayName: "Unknown",
+  costTier: "standard",
+  inputPricePerMillion: 1.25,
+  outputPricePerMillion: 6.00,
+  cacheWritePricePerMillion: 1.25,
+  cacheReadPricePerMillion: 0.25,
+};
+
+let cache: { data: readonly ModelPricing[]; expiresAt: number } | null = null;
+let inflightFetch: Promise<readonly ModelPricing[]> | null = null;
+
+function parsePricingTable(json: unknown): ModelPricing[] {
+  if (!json || typeof json !== "object") return [];
+  const models = (json as Record<string, unknown>).models;
+  if (!Array.isArray(models)) return [];
+
+  return (models as RegistryEntry[])
+    .filter((m) => m.pricing != null)
+    .map((m) => ({
+      model: m.id,
+      displayName: m.displayName,
+      costTier: m.costTier ?? "standard",
+      inputPricePerMillion: m.pricing!.inputPricePerMillion,
+      outputPricePerMillion: m.pricing!.outputPricePerMillion,
+      cacheWritePricePerMillion: m.pricing!.cacheWritePricePerMillion,
+      cacheReadPricePerMillion: m.pricing!.cacheReadPricePerMillion,
+    }));
+}
+
+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 });
+  if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
+  const data: unknown = await res.json();
+  const table = parsePricingTable(data);
+  if (table.length === 0) {
+    throw new Error("Model registry returned no models with pricing");
+  }
+  return table;
+}
+
+export async function getPricingTable(): Promise<readonly ModelPricing[]> {
+  if (cache && Date.now() < cache.expiresAt) {
+    return cache.data;
+  }
+
+  if (inflightFetch) return inflightFetch;
+
+  inflightFetch = fetchFromApi()
+    .then((data) => {
+      cache = { data, expiresAt: Date.now() + CACHE_TTL_MS };
+      return data;
+    })
+    .catch((err) => {
+      console.warn(
+        `Failed to fetch model registry, using default pricing: ${err}`,
+      );
+      const fallback = [DEFAULT_PRICING];
+      cache = { data: fallback, expiresAt: Date.now() + CACHE_TTL_MS };
+      return fallback;
+    })
+    .finally(() => {
+      inflightFetch = null;
+    });
+
+  return inflightFetch;
+}

package/src/shared/model-pricing.ts

@@ -0,0 +1,81 @@
+/**
+ * Model pricing lookup and cost computation.
+ */
+
+import { getPricingTable, DEFAULT_PRICING } from "./model-pricing-data.js";
+import type { ModelPricing } from "./model-pricing-data.js";
+
+export type { ModelPricing };
+
+let pricingByModel: Map<string, ModelPricing> | null = null;
+let initPromise: Promise<void> | null = null;
+
+/**
+ * Ensure the pricing map has been populated from the API cache.
+ * Call once at startup or before the first pricing lookup.
+ */
+export async function ensureLoaded(): Promise<void> {
+  if (initPromise) return initPromise;
+
+  initPromise = getPricingTable().then((table) => {
+    pricingByModel = new Map(table.map((entry) => [entry.model, entry]));
+  });
+
+  return initPromise;
+}
+
+function getMap(): Map<string, ModelPricing> {
+  if (!pricingByModel) {
+    console.warn("Model pricing accessed before ensureLoaded() — returning empty map");
+    return new Map();
+  }
+  return pricingByModel;
+}
+
+export function resolveModelId(requestedModel: string): string {
+  if (!requestedModel || requestedModel === "default") return "default";
+  if (getMap().has(requestedModel)) return requestedModel;
+  console.warn(
+    `Model "${requestedModel}" not in pricing registry (${getMap().size} models), falling back to "default"`,
+  );
+  return "default";
+}
+
+export function getModelPricing(model: string): ModelPricing {
+  return getMap().get(model) ?? { ...DEFAULT_PRICING, model };
+}
+
+/**
+ * Compute USD cost for a single turn using disjoint token buckets.
+ */
+export function computeTurnCost(
+  pricing: ModelPricing,
+  inputTokens: number,
+  outputTokens: number,
+  cacheWriteTokens: number,
+  cacheReadTokens: number,
+): number {
+  return (
+    inputTokens * pricing.inputPricePerMillion
+    + outputTokens * pricing.outputPricePerMillion
+    + cacheWriteTokens * pricing.cacheWritePricePerMillion
+    + cacheReadTokens * pricing.cacheReadPricePerMillion
+  ) / 1_000_000;
+}
+
+/**
+ * Compute cost in micro-USD for a workflow LLM call.
+ *
+ * Uses the cloud-fetched pricing registry (via `ensureLoaded`).
+ * Falls back to DEFAULT_PRICING for unknown models so that cost
+ * is always estimated rather than silently reported as zero.
+ */
+export function computeLlmCostMicros(
+  modelId: string,
+  inputTokens: number,
+  outputTokens: number,
+): number {
+  const pricing = getModelPricing(modelId);
+  const costUsd = computeTurnCost(pricing, inputTokens, outputTokens, 0, 0);
+  return Math.round(costUsd * 1_000_000);
+}

package/src/shared/model-registry.ts

@@ -0,0 +1,214 @@
+/**
+ * Model registry — provider lookup and economy-tier model derivation.
+ *
+ * Fetches the model registry from the Stigmer API (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";
+const CACHE_TTL_MS = 3_600_000;
+
+interface RegistryModel {
+  id: string;
+  apiModelId?: string;
+  provider: string;
+  costTier: string;
+  harness: string;
+  featured: boolean;
+}
+
+let cache: { models: readonly RegistryModel[]; expiresAt: number } | null = null;
+let inflightFetch: Promise<readonly RegistryModel[]> | null = null;
+
+function parseRegistry(json: unknown): RegistryModel[] {
+  if (!json || typeof json !== "object") return [];
+  const models = (json as Record<string, unknown>).models;
+  if (!Array.isArray(models)) return [];
+
+  return (models as Array<Record<string, unknown>>)
+    .filter((m) => typeof m.id === "string" && typeof m.provider === "string")
+    .map((m) => ({
+      id: m.id as string,
+      apiModelId: typeof m.apiModelId === "string" ? (m.apiModelId as string) : undefined,
+      provider: m.provider as string,
+      costTier: (m.costTier as string) ?? "standard",
+      harness: (m.harness as string) ?? "native",
+      featured: !!m.featured,
+    }));
+}
+
+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 });
+  if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
+  const data: unknown = await res.json();
+  return parseRegistry(data);
+}
+
+async function getRegistry(): Promise<readonly RegistryModel[]> {
+  if (cache && Date.now() < cache.expiresAt) {
+    return cache.models;
+  }
+
+  if (inflightFetch) return inflightFetch;
+
+  inflightFetch = fetchRegistry()
+    .then((models) => {
+      cache = { models, expiresAt: Date.now() + CACHE_TTL_MS };
+      return models;
+    })
+    .catch((err) => {
+      console.warn(`Failed to fetch model registry for provider lookup: ${err}`);
+      cache = { models: [], expiresAt: Date.now() + CACHE_TTL_MS };
+      return [] as readonly RegistryModel[];
+    })
+    .finally(() => {
+      inflightFetch = null;
+    });
+
+  return inflightFetch;
+}
+
+/**
+ * Check whether a model identifier is known to the registry.
+ *
+ * Used to validate SubAgent model_override values. Returns false if the
+ * registry is empty (fetch failed) — callers should treat this as "unknown"
+ * and reject the override to avoid running on an unintended model.
+ */
+export async function isModelRegistered(modelId: string): Promise<boolean> {
+  const registry = await getRegistry();
+  if (registry.length === 0) return false;
+  return registry.some((m) => m.id === modelId);
+}
+
+/**
+ * Derive the recommended economy-tier model for summarization/classification
+ * tasks, given a primary model name.
+ *
+ * Resolution:
+ * 1. Look up the primary model's provider in the registry
+ * 2. Map provider → economy model (anthropic→claude-haiku-4.5, openai→gpt-4o-mini)
+ * 3. Fall back to the primary model itself if provider is unknown or unmapped
+ */
+export async function getSummarizationModel(primaryModel: string): Promise<string> {
+  return getEconomyModel(primaryModel);
+}
+
+/**
+ * Resolve the economy-tier model for a given primary model by querying
+ * the registry for costTier=economy + same provider + harness=native.
+ *
+ * Resolution order:
+ * 1. Find the primary model's provider in the registry
+ * 2. Find an economy-tier native model from that provider
+ * 3. Cross-provider fallback: any economy-tier native model
+ * 4. Last resort: return the primary model itself
+ */
+export async function getEconomyModel(primaryModel: string): Promise<string> {
+  const registry = await getRegistry();
+  if (registry.length === 0) {
+    // Registry unavailable: keep the caller's chosen model rather than
+    // switching to a hardcoded economy model on a possibly-unconfigured
+    // provider. Summarization degrades gracefully to the primary model.
+    console.warn(
+      `Model registry empty — falling back to primary model "${primaryModel}" for economy tier`,
+    );
+    return primaryModel;
+  }
+
+  const primary = registry.find((m) => m.id === primaryModel);
+  const targetProvider = primary?.provider ?? "anthropic";
+
+  const sameProviderEconomy = registry.find(
+    (m) => m.provider === targetProvider && m.costTier === "economy" && m.harness === "native",
+  );
+  if (sameProviderEconomy) return sameProviderEconomy.id;
+
+  const anyEconomy = registry.find(
+    (m) => m.costTier === "economy" && m.harness === "native",
+  );
+  if (anyEconomy) return anyEconomy.id;
+
+  if (!primary) {
+    console.warn(
+      `Model "${primaryModel}" not found in registry and no economy fallback available`,
+    );
+  }
+  return primaryModel;
+}
+
+/**
+ * Resolve the default agent execution model from the registry.
+ *
+ * Used when the user hasn't selected a model (no executionConfig.modelName).
+ * Returns the provider's API model identifier (e.g., "claude-sonnet-4-6"),
+ * not the Stigmer registry ID (e.g., "claude-sonnet-4.6").
+ *
+ * Resolution order:
+ * 1. Featured + standard + native (platform's curated default)
+ * 2. Any standard + native model
+ * 3. Hardcoded fallback (registry unavailable)
+ */
+const FALLBACK_DEFAULT_MODEL = "claude-sonnet-4-6";
+
+export async function getDefaultModel(): Promise<string> {
+  const registry = await getRegistry();
+  if (registry.length === 0) {
+    console.warn(
+      `Model registry empty — using fallback default model "${FALLBACK_DEFAULT_MODEL}"`,
+    );
+    return FALLBACK_DEFAULT_MODEL;
+  }
+
+  const featuredStandard = registry.find(
+    (m) => m.featured && m.costTier === "standard" && m.harness === "native",
+  );
+  if (featuredStandard) return featuredStandard.apiModelId ?? featuredStandard.id;
+
+  const anyStandard = registry.find(
+    (m) => m.costTier === "standard" && m.harness === "native",
+  );
+  if (anyStandard) return anyStandard.apiModelId ?? anyStandard.id;
+
+  return FALLBACK_DEFAULT_MODEL;
+}
+
+/**
+ * Resolve a Stigmer registry model ID to the provider's API model identifier.
+ *
+ * The registry maintains two identifiers per model:
+ *   - `id`: Stigmer canonical ID (e.g., "claude-haiku-4.5")
+ *   - `apiModelId`: Provider API identifier (e.g., "claude-haiku-4-5-20251001")
+ *
+ * This function performs the translation that the proto documentation promises:
+ * "Model reference resolved via the Stigmer model registry."
+ *
+ * Graceful degradation:
+ *   - Registry unavailable → returns the original string unchanged
+ *   - Model not found in registry → returns the original string unchanged
+ *   - Model found but has no apiModelId → returns the registry `id` unchanged
+ */
+export async function resolveToApiModelId(registryId: string): Promise<string> {
+  if (!registryId) return registryId;
+
+  const registry = await getRegistry();
+  if (registry.length === 0) return registryId;
+
+  const entry = registry.find((m) => m.id === registryId);
+  if (!entry) return registryId;
+
+  return entry.apiModelId ?? registryId;
+}
+
+/** Exposed for testing — resets the in-memory cache. */
+export function _resetRegistryCache(): void {
+  cache = null;
+  inflightFetch = null;
+}