@stigmer/runner 3.9.0 → 3.11.0

package/dist/shared/llm-backend.d.ts

@@ -0,0 +1,275 @@
+/**
+ * LLM provider-backend utilities — pure routing helpers for serving a
+ * provider's models through an alternative cloud backend (GCP Vertex AI,
+ * AWS Bedrock, Microsoft Foundry) instead of the provider's public API.
+ *
+ * Layering mirrors `llm-proxy.ts`: this module is pure string/config
+ * utilities with no LangChain or SDK dependency. Consumers: the runner
+ * factories run `preflightLlmBackends` at startup, and `model-client.ts`
+ * resolves the backend and translates model ids at construction time; see
+ * `__tests__/vertex-seam.test.ts` for the pinned seam behavior.
+ *
+ * Design decision record: stigmer-cloud
+ * `_projects/2026-08/20260809.01.multi-cloud-llm-provider-endpoints/`
+ * `design-decisions/001-provider-backends.md`.
+ */
+import type { LlmProvider } from "./llm-proxy.js";
+/** Env var selecting where Anthropic models are served. */
+export declare const ANTHROPIC_BACKEND_ENV = "STIGMER_ANTHROPIC_BACKEND";
+/** Env var selecting where OpenAI models are served. */
+export declare const OPENAI_BACKEND_ENV = "STIGMER_OPENAI_BACKEND";
+/** Operator guide for backend configuration; the single copy of this URL. */
+export declare const BACKEND_DOC_URL = "https://docs.stigmer.ai/guides/runners/model-backends";
+/**
+ * Backends implemented in this build. Anthropic's values name the serving
+ * SERVICE, not the cloud (`foundry` is Microsoft Foundry, the Azure
+ * service that hosts Claude — "azure" would collide with the unrelated
+ * Azure OpenAI service). The design vocabulary also reserves `azure`
+ * (OpenAI); until that adapter lands — contingent on OpenAI models
+ * entering the native catalog — selecting it is a distinct "recognized
+ * but not implemented" failure, never a silent fallback to the public
+ * API, which would quietly route traffic outside the compliance boundary
+ * the operator asked for.
+ */
+export type AnthropicBackend = "public" | "vertex" | "bedrock" | "foundry";
+export type OpenAiBackend = "public";
+/**
+ * Result of parsing a backend env var. `message` is the operator-facing
+ * text; it names the exact var, the bad value, and what is supported, and
+ * is the single copy of that text (preflight, model construction, and any
+ * future consumer all surface this same string).
+ */
+export type BackendParseResult<B> = {
+    readonly ok: true;
+    readonly backend: B;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Parse `STIGMER_ANTHROPIC_BACKEND` (unset → `public`). */
+export declare function parseAnthropicBackend(env?: NodeJS.ProcessEnv): BackendParseResult<AnthropicBackend>;
+/** Parse `STIGMER_OPENAI_BACKEND` (unset → `public`). */
+export declare function parseOpenAiBackend(env?: NodeJS.ProcessEnv): BackendParseResult<OpenAiBackend>;
+/**
+ * Resolve the Anthropic backend for model construction, throwing the
+ * parser's message on an invalid value.
+ *
+ * The runner factories run {@link preflightLlmBackends} at startup, so in a
+ * normally-booted process this never throws — the throw is defense in depth
+ * for paths that construct models without the factories (tests, direct
+ * library use), keeping "invalid value" impossible to ride past silently.
+ */
+export declare function resolveAnthropicBackend(env?: NodeJS.ProcessEnv): AnthropicBackend;
+/**
+ * Static prerequisite check for the vertex backend, or null when satisfied.
+ *
+ * Region is the ONE hard requirement checkable without I/O: the Vertex SDK
+ * throws without it. Project id and credentials are deliberately NOT
+ * checked here — both are legitimately resolvable at request time from
+ * Application Default Credentials (workload identity, metadata server,
+ * gcloud login), so requiring env vars for them would reject perfectly
+ * valid GCP deployments. Runtime credential failures get actionable
+ * classification in `model-error.ts` instead.
+ */
+export declare function checkVertexPrerequisites(env?: NodeJS.ProcessEnv): string | null;
+/** Operator override map: canonical id -> exact Bedrock id, consulted first. */
+export declare const BEDROCK_MODEL_MAP_ENV = "STIGMER_BEDROCK_MODEL_MAP";
+/** Inference-profile geography prefix (`us`, `eu`, `global`, …), no default. */
+export declare const BEDROCK_INFERENCE_PREFIX_ENV = "STIGMER_BEDROCK_INFERENCE_PREFIX";
+/**
+ * Static prerequisite check for the bedrock backend, or null when satisfied.
+ *
+ * AWS_REGION is REQUIRED even though the Bedrock SDK would default it to
+ * us-east-1 (pinned by bedrock-seam.test.ts): for a deployment-controlled
+ * data-residency feature, silently routing model traffic to a US region on
+ * a missing var is exactly the failure backends exist to prevent. Same
+ * shape as vertex's CLOUD_ML_REGION requirement. Credentials are
+ * deliberately NOT checked — the AWS chain (env keys, IRSA / instance
+ * metadata, config files, AWS_BEARER_TOKEN_BEDROCK) legitimately resolves
+ * at request time; requiring env keys would reject valid deployments.
+ * Runtime credential failures get actionable classification in
+ * `model-error.ts` instead.
+ *
+ * A malformed STIGMER_BEDROCK_MODEL_MAP is also fatal here: it is
+ * deployment-static, and finding out at the first model call would fail
+ * executions a boot check could have refused.
+ */
+export declare function checkBedrockPrerequisites(env?: NodeJS.ProcessEnv): string | null;
+type ModelMapParseResult = {
+    readonly ok: true;
+    readonly map: ReadonlyMap<string, string>;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Parse `STIGMER_BEDROCK_MODEL_MAP`: comma-separated `canonical=bedrockId`
+ * pairs, e.g. "claude-sonnet-4-6=us.anthropic.claude-sonnet-4-6-v1:0".
+ */
+export declare function parseBedrockModelMap(env?: NodeJS.ProcessEnv): ModelMapParseResult;
+/**
+ * Operator override map: canonical id -> Foundry deployment name, consulted
+ * first. Named DEPLOYMENT_MAP, not MODEL_MAP, because the target is Azure's
+ * term of art — the operator-chosen deployment name, not another model id.
+ */
+export declare const FOUNDRY_DEPLOYMENT_MAP_ENV = "STIGMER_FOUNDRY_DEPLOYMENT_MAP";
+/** The Foundry resource name (SDK-native; builds the endpoint host). */
+export declare const FOUNDRY_RESOURCE_ENV = "ANTHROPIC_FOUNDRY_RESOURCE";
+/** Full endpoint override (SDK-native; mutually exclusive with resource). */
+export declare const FOUNDRY_BASE_URL_ENV = "ANTHROPIC_FOUNDRY_BASE_URL";
+/**
+ * Parse `STIGMER_FOUNDRY_DEPLOYMENT_MAP`: comma-separated
+ * `canonical=deploymentName` pairs, e.g.
+ * "claude-sonnet-4-6=my-sonnet-deployment".
+ */
+export declare function parseFoundryDeploymentMap(env?: NodeJS.ProcessEnv): ModelMapParseResult;
+/**
+ * Static prerequisite check for the foundry backend, or null when satisfied.
+ *
+ * The endpoint is the ONE hard requirement checkable without I/O: the
+ * Foundry SDK's constructor throws without exactly one of the resource
+ * name or a full base URL, so both halves of its contract (missing AND
+ * both-set) are refused here at boot with catalog messages instead of at
+ * the first model call. Credentials are deliberately NOT checked —
+ * ANTHROPIC_FOUNDRY_API_KEY is optional by design (without it the adapter
+ * authenticates through Microsoft Entra ID via the Azure credential chain,
+ * which resolves at request time exactly like Vertex ADC and the AWS
+ * chain), so requiring it would reject correctly-configured keyless
+ * deployments. Runtime credential failures get actionable classification
+ * in `model-error.ts` instead.
+ *
+ * A malformed STIGMER_FOUNDRY_DEPLOYMENT_MAP is also fatal here: it is
+ * deployment-static, and finding out at the first model call would fail
+ * executions a boot check could have refused.
+ */
+export declare function checkFoundryPrerequisites(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Check that direct-mode (unproxied) calls to `provider` have a usable
+ * credential path, or return the operator message describing what is
+ * missing. Null means "a request can authenticate":
+ *
+ * - `anthropic`: a non-blank `ANTHROPIC_API_KEY`, or any non-public backend
+ *   (vertex authenticates through Application Default Credentials, and
+ *   `ChatAnthropic` waives its API-key requirement when `createClient` is
+ *   supplied — pinned by vertex-seam.test.ts).
+ * - `openai`: a non-blank `OPENAI_API_KEY`. The message deliberately offers
+ *   no backend remedy until the azure adapter ships — advertising
+ *   STIGMER_OPENAI_BACKEND today would point the operator at a value that
+ *   fails with "not implemented in this build".
+ *
+ * An invalid backend value also returns null: `resolveAnthropicBackend` at
+ * model construction owns that condition's precise catalog message, and
+ * reporting it here too would create a second copy that can drift.
+ *
+ * This is the single copy of the "do we have a credential?" question. The
+ * reaction stays with each caller, because the right one differs per site:
+ * `call-llm.ts` raises a non-retryable LLM_MISSING_API_KEY, tool
+ * classification fails closed (every tool gated), and Cursor tier-2
+ * extraction skips to "no structured output". Callers consult it only when
+ * no proxy is configured — a proxied deployment authenticates with
+ * STIGMER_TOKEN and holds no provider credentials at all.
+ */
+export declare function checkDirectCredentials(provider: LlmProvider, env?: NodeJS.ProcessEnv): string | null;
+export interface LlmBackendPreflight {
+    /** Fatal, actionable operator message; null when the config is usable. */
+    readonly error: string | null;
+    /** Non-fatal operator notices (e.g. proxy overrides backend selection). */
+    readonly warnings: readonly string[];
+}
+/**
+ * Validate the deployment's backend configuration once, at startup.
+ *
+ * Called by the runner factories (`createStigmerRunner` /
+ * `createStigmerRunnerManager`) — the construction boundary every entry
+ * path shares (static, pool, and manager modes in main.ts, plus in-process
+ * embedders of `@stigmer/runner`) — so a misconfigured deployment refuses
+ * to accept work instead of failing every execution mid-flight. Mirrors the
+ * `preflightNodeRuntime` pattern: pure check in, operator message out.
+ *
+ * Precedence rule: when `STIGMER_PROXY_ENDPOINT` is set the proxy owns
+ * provider routing and backend vars are inert, so they downgrade to
+ * warnings (never silence, but never fail a proxied fleet over an ignored
+ * var either). Without a proxy, invalid values and missing prerequisites
+ * are fatal.
+ */
+export declare function preflightLlmBackends(env?: NodeJS.ProcessEnv): LlmBackendPreflight;
+/**
+ * Translate a canonical Anthropic API model id into Vertex AI's form.
+ *
+ * The model registry serves two id shapes, and Vertex treats them
+ * differently (platform.claude.com "Model IDs and versions"):
+ *
+ * - Pre-4.6 models carry a snapshot date, and Vertex separates it with `@`
+ *   instead of `-`: "claude-sonnet-4-5-20250929" -> "claude-sonnet-4-5@20250929".
+ * - 4.6-generation and later ids are dateless AND canonical on every
+ *   platform: "claude-sonnet-4-6" is used verbatim on Vertex. Appending a
+ *   date to them 404s — a real bug shipped by other integrations (Dify
+ *   langgenius/dify-official-plugins#2905, Roo-Code #11625) — so dateless
+ *   ids MUST pass through untouched.
+ *
+ * The translated id is Vertex wire detail only: it goes into the request
+ * URL path and must never escape the adapter into usage metrics or pricing,
+ * which key on the canonical id (the canonical-id invariant in the design
+ * decision record).
+ *
+ * Already-translated ids (`name@date`) and Bedrock-shaped ids
+ * (`anthropic.…-v1:0`) don't match the trailing-date pattern, so a second
+ * pass is a no-op by construction.
+ */
+export declare function toVertexModelId(apiModelId: string): string;
+/**
+ * Translate a canonical Anthropic API model id into Bedrock's form, in
+ * three layers (approved design, T04) — each a deployment-level knob:
+ *
+ * 1. `STIGMER_BEDROCK_MODEL_MAP` override, consulted first: the escape
+ *    hatch for ids the deterministic rule cannot derive (Bedrock ids for
+ *    dateless canonicals may carry AWS-side snapshot dates we cannot know).
+ * 2. `STIGMER_BEDROCK_INFERENCE_PREFIX` (e.g. "us", "eu", "global"),
+ *    applied to the derived id. Newer Claude models on Bedrock are invoked
+ *    through geography-prefixed inference profiles (AWS lists the base id's
+ *    in-region endpoint as N/A) — but WHICH geography is a deployment
+ *    decision (data residency), underivable from the model id, and never
+ *    defaulted: a missing prefix yields the bare id, and if AWS rejects it
+ *    with its "use an inference profile" error, model-error.ts translates
+ *    that into "set ${BEDROCK_INFERENCE_PREFIX_ENV}".
+ * 3. Deterministic rule: `anthropic.{canonical}-v1:0` — verified against
+ *    AWS's model catalog for the registry's dated ids (e.g.
+ *    claude-sonnet-4-5-20250929 -> anthropic.claude-sonnet-4-5-20250929-v1:0).
+ *
+ * Like the Vertex translation, the result is wire detail only: it rides in
+ * the request URL and must never escape the adapter into usage metrics or
+ * pricing, which key on the canonical id (the canonical-id invariant).
+ *
+ * Throws the catalog message on a malformed map — defense in depth for
+ * paths that construct models without the factories; a normally-booted
+ * runner already refused to start in `checkBedrockPrerequisites`.
+ */
+export declare function toBedrockModelId(apiModelId: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Translate a canonical Anthropic API model id into a Microsoft Foundry
+ * deployment name, in two layers (approved design, T05):
+ *
+ * 1. `STIGMER_FOUNDRY_DEPLOYMENT_MAP` override, consulted first: Foundry
+ *    routes by DEPLOYMENT NAME, and the portal lets operators name
+ *    deployments anything ("my-sonnet-deployment"). This is the escape
+ *    hatch for those custom names.
+ * 2. Deterministic rule: strip a trailing `-YYYYMMDD` snapshot date —
+ *    Foundry's DEFAULT deployment names are the dateless Claude ids
+ *    (claude-sonnet-4-5-20250929 -> claude-sonnet-4-5; dateless ids pass
+ *    through unchanged). Verified against Anthropic's published Foundry
+ *    model table: every native-catalog id maps onto a real default
+ *    deployment name. Note this is the INVERSE of toVertexModelId, which
+ *    keeps the date and reseparates it with `@`.
+ *
+ * Like the other translations, the result is wire detail only: it rides in
+ * the request body's `model` field (Foundry keeps it in the body — see
+ * foundry-seam.test.ts — unlike Vertex/Bedrock, which move it into the URL
+ * path) and must never escape the adapter into usage metrics or pricing,
+ * which key on the canonical id (the canonical-id invariant).
+ *
+ * Throws the catalog message on a malformed map — defense in depth for
+ * paths that construct models without the factories; a normally-booted
+ * runner already refused to start in `checkFoundryPrerequisites`.
+ */
+export declare function toFoundryDeploymentName(apiModelId: string, env?: NodeJS.ProcessEnv): string;
+export {};