@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/model-client.js

@@ -0,0 +1,328 @@
+/**
+ * Single construction point for LangChain chat models in the runner.
+ *
+ * This is the only place that translates a Stigmer registry model ID
+ * (dot-notation, e.g. "claude-haiku-4.5") into the provider's API model ID
+ * (e.g. "claude-haiku-4-5-20251001") before a client is built — so no
+ * activity can bypass the translation and 404 the provider.
+ *
+ * Layering: `llm-proxy.ts` and `llm-backend.ts` stay pure routing utilities
+ * (no LangChain dependency); this module is the LangChain-aware layer above
+ * them that owns the resolve -> infer-provider -> strip-prefix ->
+ * proxy-or-backend-wire -> construct sequence that used to be copy-pasted
+ * across every LLM activity.
+ *
+ * In the agent host, a direct-mode client keeps its shape and swaps only
+ * its transport: its base URL is a provider lane of the runner's local
+ * proxy and its credential the host's token (`model-lanes.ts`). Nothing
+ * else here knows the difference.
+ */
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ChatOpenAI } from "@langchain/openai";
+import { inferProvider, stripProviderPrefix, resolveProxyBaseUrl, buildProxyHeaders, } from "./llm-proxy.js";
+import { resolveAnthropicBackend, resolveAnthropicBaseUrl, checkVertexPrerequisites, checkBedrockPrerequisites, checkFoundryPrerequisites, toVertexModelId, toBedrockModelId, toFoundryDeploymentName, } from "./llm-backend.js";
+import { PROVIDER_ANTHROPIC, PROVIDER_AWS_BEDROCK, PROVIDER_AZURE_AI_INFERENCE, PROVIDER_GCP_VERTEX_AI, PROVIDER_OPENAI, } from "../gen-ai-conventions.js";
+import { resolveToApiModelId } from "./model-registry.js";
+import { recordChatModelFacts } from "./model-facts.js";
+import { toAnthropicServiceTier, toOpenAiServiceTier, } from "./service-tier.js";
+import { getRunnerSecret } from "./runner-credential-store.js";
+import { VERTEX_LANE_PROJECT, modelLaneUrl, modelLanes } from "./model-lanes.js";
+/**
+ * The operator's request-timeout bound. Only a positive integer means
+ * "bound the request" — unset, non-numeric, zero, and negative all
+ * normalize to no bound. Deployment-static env, read here the same way
+ * provider API keys are.
+ */
+function resolveDefaultTimeoutMs() {
+    const parsed = Number.parseInt(process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS ?? "", 10);
+    return parsed > 0 ? parsed : undefined;
+}
+/**
+ * Build a configured chat model, resolving the registry id to a provider API
+ * id first. The resolution MUST precede provider inference and prefix
+ * stripping — that ordering is the invariant each per-site copy kept dropping,
+ * surfacing as `404 model: claude-haiku-4.5` at the provider.
+ */
+export async function buildChatModel(opts) {
+    const resolved = await resolveToApiModelId(opts.modelName);
+    const provider = inferProvider(resolved);
+    const apiModelId = stripProviderPrefix(resolved);
+    const timeoutMs = opts.timeoutMs ?? resolveDefaultTimeoutMs();
+    // Backend precedence by construction: a proxied call never consults the
+    // backend var — the proxy owns provider routing (the factories' preflight
+    // warns when both are configured). Selection is deployment-static and read
+    // here the same way provider API keys are, not plumbed through Config.
+    const anthropicBackend = provider === "anthropic" && !opts.proxyEndpoint
+        ? resolveAnthropicBackend()
+        : "public";
+    // Lanes stand in for every direct-mode credential below; never with a
+    // proxy, which carries its own (`model-lanes.ts`).
+    const lanes = opts.proxyEndpoint ? undefined : modelLanes();
+    const laneHeaders = lanes ? buildProxyHeaders(lanes.token, opts.headerScope ?? {}) : undefined;
+    // Backend SDKs (and their auth subtrees: google-auth-library, AWS smithy)
+    // load lazily so deployments that never configure a backend never
+    // evaluate them — cheap cold starts stay cheap, and bundle-slim's CJS
+    // output preserves exactly this deferred evaluation (see
+    // scripts/bundle-slim.mjs). The factory is invoked lazily by
+    // ChatAnthropic once per cached client (batch + streaming), so the class
+    // is captured here, in async context.
+    //
+    // Each factory MUST honor options.maxRetries and options.timeout:
+    // LangChain owns retrying and hands the factory maxRetries: 0 — a factory
+    // that drops it nests the SDK's default 2 retries inside LangChain's
+    // retry loop, multiplying every transient failure — and `timeout` arrives
+    // through the same options object (ChatAnthropic spreads clientOptions
+    // into it), so a factory that drops it silently unbounds
+    // STIGMER_LLM_REQUEST_TIMEOUT_MS on that backend. Pinned by the seam
+    // tests. Prerequisites are re-checked here (not only in
+    // the factories' preflight) so paths that construct models without a
+    // runner factory still fail at dispatch with the catalog message instead
+    // of mid-request. Ambient credentials are read natively by each SDK from
+    // its standard conventions (GCP: CLOUD_ML_REGION + ADC; AWS: AWS_REGION +
+    // the credential chain); runner-held keys (AWS_BEARER_TOKEN_BEDROCK,
+    // ANTHROPIC_FOUNDRY_API_KEY) are passed explicitly from the credential
+    // store because the boot capture empties their env slots (#508).
+    let backendCreateClient;
+    let wireModelId = apiModelId;
+    let maxTokens = opts.maxTokens;
+    if (anthropicBackend === "vertex") {
+        const prereq = checkVertexPrerequisites();
+        if (prereq !== null)
+            throw new Error(prereq);
+        const { AnthropicVertex } = await import("@anthropic-ai/vertex-sdk");
+        const vertexLane = lanes ? vertexLaneOptions(lanes, laneHeaders) : {};
+        backendCreateClient = (options) => new AnthropicVertex({ maxRetries: options.maxRetries, timeout: options.timeout, ...vertexLane });
+        wireModelId = toVertexModelId(apiModelId);
+    }
+    else if (anthropicBackend === "bedrock") {
+        const prereq = checkBedrockPrerequisites();
+        if (prereq !== null)
+            throw new Error(prereq);
+        const { AnthropicBedrock } = await import("@anthropic-ai/bedrock-sdk");
+        // The SDK's own default for `apiKey` is process.env.AWS_BEARER_TOKEN_BEDROCK,
+        // which the boot capture has emptied (#508) — hand it the stored value
+        // explicitly. `undefined` when absent preserves the SDK's fallthrough to
+        // the ambient AWS credential chain (env keys, IRSA, config files).
+        // Through a lane the client signs nothing (`skipAuth`): the lane adds
+        // the bearer token or the SigV4 signature for the real host.
+        const bedrockAuth = lanes
+            ? { skipAuth: true, baseURL: modelLaneUrl(lanes, "bedrock"), defaultHeaders: laneHeaders }
+            : { apiKey: getRunnerSecret("AWS_BEARER_TOKEN_BEDROCK") };
+        backendCreateClient = (options) => new AnthropicBedrock({
+            ...bedrockAuth,
+            maxRetries: options.maxRetries,
+            timeout: options.timeout,
+        });
+        wireModelId = toBedrockModelId(apiModelId);
+        if (maxTokens === undefined) {
+            // LangChain's per-model maxTokens table prefix-matches the model
+            // name. Vertex's translated ids still match their canonical prefix;
+            // Bedrock's `anthropic.…` ids match nothing and silently fall back
+            // to 4096 — a silent output cap. Probe the CANONICAL id with a
+            // throwaway construction (pure field assignment, no I/O; the key is
+            // never used) so bedrock inherits exactly the default the public API
+            // and vertex get for the same model — including models the table
+            // doesn't know yet, where all backends agree on the fallback.
+            // Pinned by the canonical-parity test in bedrock-adapter.test.ts.
+            maxTokens = new ChatAnthropic({ model: apiModelId, apiKey: "max-tokens-probe" }).maxTokens;
+        }
+    }
+    else if (anthropicBackend === "foundry") {
+        const prereq = checkFoundryPrerequisites();
+        if (prereq !== null)
+            throw new Error(prereq);
+        const { AnthropicFoundry } = await import("@anthropic-ai/foundry-sdk");
+        // Auth is an explicit either/or (the Foundry constructor throws when
+        // given both a key and a token provider): ANTHROPIC_FOUNDRY_API_KEY if
+        // present, otherwise keyless Microsoft Entra ID through the Azure
+        // credential chain (env service principal -> workload identity ->
+        // managed identity -> az CLI) — the Azure analogue of Vertex ADC and
+        // the AWS chain, resolved at request time. The provider is built once
+        // here (getBearerTokenProvider caches tokens until near-expiry) and
+        // shared by both cached clients; the SDK still consults it per request,
+        // so refreshed tokens flow without reconstruction (pinned by
+        // foundry-seam.test.ts). Endpoint (resource or base URL) and the key
+        // are read natively by the SDK from its own env vars.
+        // The SDK's own default for `apiKey` is process.env.ANTHROPIC_FOUNDRY_API_KEY,
+        // which the boot capture has emptied (#508) — resolve it from the store
+        // and hand it over explicitly. The either/or stays intact: exactly one of
+        // apiKey / azureADTokenProvider reaches the constructor.
+        const foundryApiKey = lanes ? lanes.token : getRunnerSecret("ANTHROPIC_FOUNDRY_API_KEY")?.trim() || undefined;
+        // Through a lane the endpoint is the lane's; an empty resource keeps the
+        // SDK from reading ANTHROPIC_FOUNDRY_RESOURCE, which beside a base URL it
+        // refuses as ambiguous.
+        const foundryLane = lanes ? { baseURL: modelLaneUrl(lanes, "foundry"), resource: "", defaultHeaders: laneHeaders } : {};
+        let azureADTokenProvider;
+        if (!foundryApiKey) {
+            const { DefaultAzureCredential, getBearerTokenProvider } = await import("@azure/identity");
+            azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), "https://ai.azure.com/.default");
+        }
+        backendCreateClient = (options) => new AnthropicFoundry({
+            maxRetries: options.maxRetries,
+            timeout: options.timeout,
+            ...foundryLane,
+            ...(foundryApiKey ? { apiKey: foundryApiKey } : { azureADTokenProvider }),
+        });
+        // Unlike the vertex/bedrock ids, the deployment name needs no maxTokens
+        // handling: stripping the snapshot date preserves LangChain's per-model
+        // default (probed 2026-08-11 across the full catalog; pinned by the
+        // parity test in foundry-adapter.test.ts).
+        wireModelId = toFoundryDeploymentName(apiModelId);
+    }
+    // The proxy's provider path wins; without one, only the public Anthropic
+    // backend takes an operator-set address (ANTHROPIC_BASE_URL: a gateway in
+    // front of Anthropic, or the install journeys' fake model). The backend
+    // adapters reach their own cloud endpoints and OpenAI keeps its default.
+    const baseUrl = opts.proxyEndpoint
+        ? resolveProxyBaseUrl(opts.proxyEndpoint, provider)
+        : lanes && (provider === "openai" || anthropicBackend === "public")
+            ? modelLaneUrl(lanes, provider)
+            : provider === "anthropic" && anthropicBackend === "public"
+                ? resolveAnthropicBaseUrl()
+                : undefined;
+    const headers = opts.proxyEndpoint && opts.stigmerToken
+        ? buildProxyHeaders(opts.stigmerToken, opts.headerScope ?? {})
+        : provider === "openai" || anthropicBackend === "public"
+            ? laneHeaders
+            : undefined;
+    // Proxy mode authenticates with the Stigmer token; direct mode falls back
+    // to the provider's own key, resolved from the credential store (the boot
+    // capture moved it out of process.env, #508).
+    const apiKey = opts.proxyEndpoint
+        ? (opts.stigmerToken ?? "proxy-managed")
+        : lanes
+            ? lanes.token
+            : provider === "openai"
+                ? (getRunnerSecret("OPENAI_API_KEY") ?? "")
+                : (getRunnerSecret("ANTHROPIC_API_KEY") ?? "");
+    // maxRetries is 0 when a timeout is bound (a retry loop under a bound
+    // multiplies the wall-clock budget); with no bound, LangChain's default
+    // retry behavior is unchanged.
+    const maxRetries = timeoutMs !== undefined ? { maxRetries: 0 } : {};
+    if (opts.thinking !== undefined && provider !== "anthropic") {
+        throw new Error(`buildChatModel: a thinking parameter was passed for ${opts.modelName}, a ${provider} model; ` +
+            "only Anthropic models have a native thinking mapping");
+    }
+    const common = {
+        ...(opts.temperature === null ? {} : { temperature: opts.temperature ?? 0 }),
+        apiKey,
+        ...(maxTokens ? { maxTokens } : {}),
+        ...(opts.streaming ? { streaming: true } : {}),
+        ...maxRetries,
+    };
+    const anthropicThinkingField = opts.thinking !== undefined ? { thinking: opts.thinking } : {};
+    // The request timeout lives in a different slot per wrapper: ChatOpenAI
+    // reads `timeout` as a constructor field, but ChatAnthropic ignores it
+    // there — its slot is `clientOptions.timeout`, which the wrapper spreads
+    // into the createClient factory options and (on the default factory) the
+    // SDK constructor. This split is what makes STIGMER_LLM_REQUEST_TIMEOUT_MS
+    // bound every path; putting `timeout` in the shared constructor spread is
+    // the exact regression that made it inert for Anthropic.
+    // The `maxRetries` half above stays constructor-level for both wrappers:
+    // that is LangChain's own retry knob, distinct from the SDK-level
+    // maxRetries the factories receive.
+    const anthropicClientOptions = {
+        ...(timeoutMs ? { timeout: timeoutMs } : {}),
+        ...(baseUrl ? { baseURL: baseUrl } : {}),
+        ...(headers ? { defaultHeaders: headers } : {}),
+    };
+    const anthropicClientOptionsField = Object.keys(anthropicClientOptions).length > 0
+        ? { clientOptions: anthropicClientOptions }
+        : {};
+    // The tier rides the request body per provider dialect (#361): OpenAI
+    // takes `service_tier` as a first-class constructor field; ChatAnthropic
+    // has no such field, so it rides `invocationKwargs`, which the wrapper
+    // spreads into every request body. Both spellings resolve through the
+    // shared mapping so no construction site can invent a third one.
+    const openAiServiceTierField = opts.serviceTier !== undefined
+        ? { service_tier: toOpenAiServiceTier(opts.serviceTier) }
+        : {};
+    const anthropicServiceTierField = opts.serviceTier !== undefined
+        ? { invocationKwargs: { service_tier: toAnthropicServiceTier(opts.serviceTier) } }
+        : {};
+    // The two SDKs name the transport-override block differently (OpenAI:
+    // `configuration`, Anthropic: `clientOptions`) — encapsulating that here is
+    // the whole point, since the shape mismatch is where bugs used to hide.
+    const model = provider === "openai"
+        ? new ChatOpenAI({
+            model: apiModelId,
+            ...common,
+            ...openAiServiceTierField,
+            ...(timeoutMs ? { timeout: timeoutMs } : {}),
+            ...(baseUrl || headers
+                ? {
+                    configuration: {
+                        ...(baseUrl ? { baseURL: baseUrl } : {}),
+                        ...(headers ? { defaultHeaders: headers } : {}),
+                    },
+                }
+                : {}),
+        })
+        : backendCreateClient
+            ? // Backend adapter: the translated id is wire detail only — each
+                // client moves it from the JSON body into its URL path. The waiver
+                // in ChatAnthropic (an API key is not required when createClient is
+                // provided) is what lets this construct with no ANTHROPIC_API_KEY.
+                // (Backend mode never has a proxy — see the precedence rule above —
+                // so the clientOptions here carry at most the timeout.)
+                //
+                // service_tier deliberately does NOT ride backend requests:
+                // standard/priority tiers are an Anthropic-FIRST-PARTY billing
+                // concept, and Vertex/Bedrock/Foundry bill through the cloud
+                // provider with no tier dimension — an unknown body param there is
+                // a request refusal waiting to happen. The account-default price
+                // hole this parameter closes does not exist on those backends.
+                new ChatAnthropic({
+                    model: wireModelId,
+                    ...common,
+                    ...anthropicThinkingField,
+                    ...anthropicClientOptionsField,
+                    createClient: backendCreateClient,
+                })
+            : new ChatAnthropic({
+                model: apiModelId,
+                ...common,
+                ...anthropicThinkingField,
+                ...anthropicServiceTierField,
+                ...anthropicClientOptionsField,
+            });
+    recordChatModelFacts(model, {
+        providerName: providerNameOf(provider, anthropicBackend),
+        requestModel: opts.modelName,
+        responseModel: apiModelId,
+    });
+    return { model, provider, apiModelId };
+}
+/** The conventions' provider name for where a model is served from. */
+function providerNameOf(provider, anthropicBackend) {
+    if (provider === "openai")
+        return PROVIDER_OPENAI;
+    switch (anthropicBackend) {
+        case "public":
+            return PROVIDER_ANTHROPIC;
+        case "vertex":
+            return PROVIDER_GCP_VERTEX_AI;
+        case "bedrock":
+            return PROVIDER_AWS_BEDROCK;
+        case "foundry":
+            return PROVIDER_AZURE_AI_INFERENCE;
+    }
+}
+/**
+ * A Vertex client bound to its lane. The client cannot acquire a Google
+ * token (the host has no Google identity), so its auth client is a stub
+ * that adds nothing and names a placeholder project; the lane adds the
+ * runner's token and its real project (`agent-proxy/lanes.ts`). The
+ * Vertex client reads exactly `projectId` and `getRequestHeaders()` off its
+ * auth client, so the stub is the SDK's documented `authClient` seam.
+ */
+function vertexLaneOptions(lanes, headers) {
+    const authClient = { projectId: VERTEX_LANE_PROJECT, getRequestHeaders: async () => new Headers() };
+    return {
+        baseURL: modelLaneUrl(lanes, "vertex"),
+        projectId: VERTEX_LANE_PROJECT,
+        defaultHeaders: headers,
+        authClient: authClient,
+    };
+}
+//# sourceMappingURL=model-client.js.map

package/dist/shared/model-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-client.js","sourceRoot":"","sources":["../../src/shared/model-client.ts"],"names":[],"mappings":"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"}

package/dist/shared/model-error.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Model-call error unwrapping and classification, shared by every harness.
+ *
+ * Three problems this module solves:
+ *
+ * 1. LangChain wraps any error thrown inside a middleware-wrapped model call
+ *    in `MiddlewareError`, so `err.constructor.name` reads "MiddlewareError"
+ *    regardless of what actually failed. The wrapper preserves the original
+ *    error on the standard `cause` property — `unwrapModelError` walks that
+ *    chain back to the root SDK error (which carries `.status` and the
+ *    provider's parsed body).
+ *
+ * 2. On Stigmer Cloud every model call runs on a key the organization owns,
+ *    so a provider failure the proxy relays is the organization's, though
+ *    it reaches the runner in proxy mode. The proxy keeps the provider's
+ *    status and message and marks the message with
+ *    ORGANIZATION_PROVIDER_KEY_SENTINEL; this module words a marked failure
+ *    as the organization's own key and account. Provider billing prose
+ *    (stigmer/stigmer#330: Anthropic's "credit balance is too low") reads
+ *    as the account's own in both modes, because no call runs on an account
+ *    the platform owns.
+ *
+ * 3. The proxy refuses a call for a provider the organization holds no key
+ *    for, marking the refusal with PROVIDER_KEY_REQUIRED_SENTINEL. This
+ *    module words it as the missing key and where an admin adds it.
+ *
+ * Classification order is load-bearing: the sentinels precede everything
+ * that reads proxy mode or the status, otherwise the proxy's refusal (a
+ * 403) would read as the proxy denying the call and an organization-key
+ * 401 as the platform rejecting the runner's session.
+ */
+import type { LlmProvider } from "./llm-proxy.js";
+/**
+ * Machine-readable code the cloud proxy embeds in a provider failure it
+ * relays from a call served on the organization's own provider key. The
+ * message text is the contract carrier: it is the one field proven to
+ * survive provider SDK → LangChain → runner intact. Duplicated in
+ * stigmer-cloud's LLM proxy lane; change both or neither.
+ */
+export declare const ORGANIZATION_PROVIDER_KEY_SENTINEL = "STIGMER_ORGANIZATION_PROVIDER_KEY";
+/**
+ * Machine-readable code the cloud proxy embeds in the refusal of a call for
+ * a provider the organization holds no key for. The message text carries it,
+ * as it carries the other sentinels. Duplicated in stigmer-cloud's LLM proxy
+ * lane; change both or neither.
+ */
+export declare const PROVIDER_KEY_REQUIRED_SENTINEL = "STIGMER_PROVIDER_KEY_REQUIRED";
+export interface ClassifiedModelError {
+    /** Stable machine-readable code (the `[type]` a failed turn's message leads with). */
+    readonly code: string;
+    /** User-facing message; provider prose appears only quoted after it. */
+    readonly message: string;
+}
+export interface ModelErrorContext {
+    /** True when model calls route through the Stigmer platform proxy. */
+    readonly proxyMode: boolean;
+    /** Provider, when the caller knows it — sharpens the message wording. */
+    readonly provider?: LlmProvider;
+    /** Model id, when the caller knows it. */
+    readonly modelId?: string;
+}
+/**
+ * Walk the `cause` chain to the root error. LangChain's MiddlewareError (and
+ * anything else that chains causes) preserves the original SDK error there,
+ * and the root is the one link carrying the provider's `.status`.
+ *
+ * The chain is as long as the agent's middleware stack: LangChain wraps a
+ * model call's failure once per middleware that implements `wrapModelCall`
+ * (`MiddlewareError.wrap` in its AgentNode), and a native turn stacks
+ * deepagents' own middleware, the to-do list and Stigmer's, well past ten
+ * layers. So the walk has no depth bound; a cause cycle ends it instead, at
+ * the first error seen twice.
+ */
+export declare function unwrapModelError(err: unknown): unknown;
+/**
+ * Classify a model-call failure into a stable code with a user-facing
+ * message, or return undefined when there is no positive signal that the
+ * error came from a model call at all.
+ *
+ * The undefined arm matters for callers whose catch blocks see more than
+ * model errors (the deep-agent activity wraps tools, MCP, and workspace
+ * operations too): only positively-identified model errors get relabeled;
+ * everything else keeps its own identity.
+ */
+export declare function classifyModelCallError(err: unknown, callerCtx: ModelErrorContext): ClassifiedModelError | undefined;
+/**
+ * Describe an arbitrary activity failure for the execution's user-visible
+ * error field: model-call errors get classified codes and messages; anything
+ * else keeps the ROOT error's identity (never a wrapper's class name).
+ */
+export declare function describeExecutionError(err: unknown, ctx: ModelErrorContext): {
+    errorType: string;
+    errorMessage: string;
+};