@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/shared/model-error.ts

@@ -0,0 +1,551 @@
+/**
+ * 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";
+import {
+  parseAnthropicBackend,
+  BACKEND_DOC_URL,
+  BEDROCK_INFERENCE_PREFIX_ENV,
+  FOUNDRY_DEPLOYMENT_MAP_ENV,
+  FOUNDRY_RESOURCE_ENV,
+  type AnthropicBackend,
+} from "./llm-backend.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 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 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 function unwrapModelError(err: unknown): unknown {
+  const seen = new Set<unknown>([err]);
+  let current = err;
+  while (current instanceof Error && current.cause instanceof Error && !seen.has(current.cause)) {
+    current = current.cause;
+    seen.add(current);
+  }
+  return current;
+}
+
+/**
+ * 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 function classifyModelCallError(
+  err: unknown,
+  callerCtx: ModelErrorContext,
+): ClassifiedModelError | undefined {
+  const root = unwrapModelError(err);
+  const message = root instanceof Error ? root.message : String(root);
+
+  // 0. No key at all — first: the proxy refused before any provider saw
+  //    the call, so nothing else about it (status, proxy mode) means
+  //    anything but "add a key".
+  if (message.includes(PROVIDER_KEY_REQUIRED_SENTINEL)) {
+    const missing = callerCtx.provider ? `${providerLabel(callerCtx)} key` : "key for this model's provider";
+    return {
+      code: "LLM_PROVIDER_KEY_REQUIRED",
+      message: `This organization has no ${missing}. An admin can add one in Settings → Provider keys.`,
+    };
+  }
+
+  // 0b. Organization-key sentinel — before everything that reads proxyMode:
+  //    the call went through the proxy but on the organization's own key,
+  //    so its failures are the organization's. The key-specific failures
+  //    get key-specific wording; the rest classify as direct mode would.
+  const organizationKey = message.includes(ORGANIZATION_PROVIDER_KEY_SENTINEL);
+  if (organizationKey) {
+    const classified = classifyOrganizationKeyError(root, message, callerCtx);
+    if (classified !== undefined) return classified;
+  }
+  const ctx = organizationKey ? { ...callerCtx, proxyMode: false } : callerCtx;
+  const backend = resolveDirectBackend(ctx);
+
+  // 1. Backend credential acquisition — before status mapping: these
+  //    failures come from the auth library (thrown while adapting the
+  //    request, usually with no HTTP status) and won't self-heal on retry.
+  //    Raw, they read like library internals ("Could not load the default
+  //    credentials"); the operator needs to hear "fix your cloud
+  //    credentials".
+  if (backend === "vertex" && isGoogleCredentialMessage(message)) {
+    return {
+      code: "LLM_BACKEND_CREDENTIALS",
+      message:
+        `The vertex backend could not acquire Google credentials for ${modelLabel(ctx)}. ` +
+        `Set GOOGLE_APPLICATION_CREDENTIALS to a service-account key, or run on a GCP ` +
+        `identity (workload identity / metadata server). ANTHROPIC_VERTEX_PROJECT_ID is ` +
+        `only needed when the credentials don't carry a project. See ${BACKEND_DOC_URL}. ` +
+        `Underlying error: ${message}`,
+    };
+  }
+  if (backend === "bedrock" && isAwsCredentialMessage(message)) {
+    return {
+      code: "LLM_BACKEND_CREDENTIALS",
+      message:
+        `The bedrock backend could not acquire AWS credentials for ${modelLabel(ctx)}. ` +
+        `Provide credentials through the standard AWS chain (environment keys, an IAM ` +
+        `role / IRSA, config files) or set AWS_BEARER_TOKEN_BEDROCK. See ${BACKEND_DOC_URL}. ` +
+        `Underlying error: ${message}`,
+    };
+  }
+  if (backend === "foundry" && isFoundryCredentialMessage(message)) {
+    // Only the keyless Entra path can land here: API-key failures arrive
+    // as HTTP 401s (status arm below), while a failing token provider
+    // throws statusless from inside the Foundry SDK's authHeaders.
+    return {
+      code: "LLM_BACKEND_CREDENTIALS",
+      message:
+        `The foundry backend could not acquire a Microsoft Entra ID token for ${modelLabel(ctx)}. ` +
+        `Give the runner an Azure identity the credential chain can resolve (workload ` +
+        `identity / managed identity, service-principal env vars, or az login), or set ` +
+        `ANTHROPIC_FOUNDRY_API_KEY to use API-key auth instead. See ${BACKEND_DOC_URL}. ` +
+        `Underlying error: ${message}`,
+    };
+  }
+
+  // 1b. Bedrock's inference-profile rejection — a config condition, not a
+  //     bad request: newer Claude models cannot be invoked by bare model id
+  //     (AWS lists their in-region endpoint as N/A). The operator remedy is
+  //     one env var, so say exactly that instead of relaying AWS prose that
+  //     talks about ARNs and provisioned throughput.
+  if (backend === "bedrock" && isBedrockInferenceProfileMessage(message)) {
+    return {
+      code: "LLM_BACKEND_MODEL_ROUTING",
+      message:
+        `Bedrock requires an inference profile for ${modelLabel(ctx)} — the bare model ` +
+        `id cannot be invoked on-demand. Set ${BEDROCK_INFERENCE_PREFIX_ENV} to your ` +
+        `deployment's geography (e.g. "us", "eu", or "global"), or map this model ` +
+        `explicitly in STIGMER_BEDROCK_MODEL_MAP. See ${BACKEND_DOC_URL}. ` +
+        `Underlying error: ${message}`,
+    };
+  }
+
+  // 2. Provider billing prose: the account the key belongs to is out of
+  //    credit, and that account is the caller's own in either mode (the
+  //    cloud relays a failure on the organization's key marked, which 0b
+  //    words first).
+  if (isProviderBillingMessage(message)) {
+    return {
+      code: "LLM_PROVIDER_BILLING",
+      message:
+        `Your ${ctx.provider ? providerLabel(ctx) : "model provider"} account is out of credits or over quota. ` +
+        `Add credits to your provider account or switch to a different model. ` +
+        `Provider message: ${message}`,
+    };
+  }
+
+  // 3. HTTP status duck-typing. Both provider SDKs throw APIError subclasses
+  //    exposing `.status`; duck-typing avoids importing either SDK's classes.
+  const status = typeof (root as { status?: unknown }).status === "number"
+    ? (root as { status: number }).status
+    : undefined;
+  if (status !== undefined) {
+    return classifyByStatus(status, message, ctx, backend);
+  }
+
+  // 4. Connection/timeout heuristics on the root error's class name: the
+  //    SDKs' own APIConnection* class names only. The callers' catch blocks
+  //    are broad (deep-agent, Cursor), and a WorkspaceLockTimeoutError is not
+  //    a model connection timeout.
+  const errName = root instanceof Error ? root.constructor.name : "";
+  const isTimeout = errName.includes("APIConnectionTimeout");
+  if (isTimeout) {
+    return {
+      code: "LLM_CONNECTION_TIMEOUT",
+      message: `Connection timed out for ${modelLabel(ctx)}: ${message}`,
+    };
+  }
+  const isConnection = errName.includes("APIConnection");
+  if (isConnection) {
+    return {
+      code: "LLM_CONNECTION_ERROR",
+      message: `Connection failed for ${modelLabel(ctx)}: ${message}`,
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * The failures an organization's own provider key causes, worded for the
+ * organization's admin: out of credit or quota at the provider, the key
+ * rejected, or the key's account not permitted the model. Undefined for
+ * every other failure, which classifies as direct mode would.
+ */
+function classifyOrganizationKeyError(
+  root: unknown,
+  message: string,
+  ctx: ModelErrorContext,
+): ClassifiedModelError | undefined {
+  const provider = providerSubject(ctx);
+  if (isProviderBillingMessage(message)) {
+    return {
+      code: "LLM_PROVIDER_BILLING",
+      message:
+        `Your organization's own ${providerLabel(ctx)} key is out of credits or over quota. ` +
+        `Add credits to that provider account, or update the key in Settings → Provider keys. ` +
+        `Provider message: ${message}`,
+    };
+  }
+  const status = typeof (root as { status?: unknown }).status === "number"
+    ? (root as { status: number }).status
+    : undefined;
+  if (status === 401) {
+    return {
+      code: "LLM_AUTHENTICATION_ERROR",
+      message:
+        `${provider} rejected your organization's own key (authentication, HTTP 401) for ${modelLabel(ctx)}. ` +
+        `Update the key in Settings → Provider keys.`,
+    };
+  }
+  if (status === 403) {
+    return {
+      code: "LLM_PERMISSION_DENIED",
+      message:
+        `${provider} denied your organization's own key (authorization, HTTP 403) for ${modelLabel(ctx)}. ` +
+        `Check that the key's account may use this model, or update the key in Settings → Provider keys.`,
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Maps a provider HTTP status to its code and message: 401, 403, 404, 400,
+ * 422 and 429 each have their own code (429's message says the provider
+ * SDK's own retry was exhausted), any other 5xx is a provider server
+ * error, and anything else a generic API error.
+ */
+function classifyByStatus(
+  status: number,
+  rawMessage: string,
+  ctx: ModelErrorContext,
+  backend: AnthropicBackend,
+): ClassifiedModelError {
+  const context = modelLabel(ctx);
+
+  switch (status) {
+    case 401:
+      return {
+        code: "LLM_AUTHENTICATION_ERROR",
+        message: ctx.proxyMode
+          ? `The Stigmer platform rejected this model call (authentication, HTTP 401) for ${context}. ` +
+            `Your session token may have expired — retry the execution, and contact support if it persists.`
+          // On a cloud backend the credential is a cloud identity — "check
+          // your API key" would send the operator hunting for a key that
+          // isn't in play.
+          : backend === "vertex"
+            ? `Google rejected this Vertex AI call (authentication, HTTP 401) for ${context}. ` +
+              `The credentials are expired or not valid for this project — check ` +
+              `GOOGLE_APPLICATION_CREDENTIALS or the runner's GCP identity. See ${BACKEND_DOC_URL}.`
+          : backend === "bedrock"
+            ? `AWS rejected this Bedrock call (authentication, HTTP 401) for ${context}. ` +
+              `The credentials are expired or invalid — check the runner's AWS identity ` +
+              `(environment keys, IAM role / IRSA) or AWS_BEARER_TOKEN_BEDROCK. See ${BACKEND_DOC_URL}.`
+          : backend === "foundry"
+            ? `Azure rejected this Microsoft Foundry call (authentication, HTTP 401) for ${context}. ` +
+              `The credential is expired or not valid for this Foundry resource — check ` +
+              `ANTHROPIC_FOUNDRY_API_KEY (find it on the deployment's Details tab) or the ` +
+              `runner's Azure identity. See ${BACKEND_DOC_URL}.`
+            : `Authentication failed for ${context}. Check that your API key is valid and not expired.`,
+      };
+    case 403:
+      return {
+        code: "LLM_PERMISSION_DENIED",
+        message: ctx.proxyMode
+          ? `The Stigmer platform denied this model call (authorization, HTTP 403) for ${context}. ` +
+            `Verify this execution is permitted to use the model, and contact support if it persists.`
+          : backend === "vertex"
+            ? `Vertex AI denied this call (HTTP 403) for ${context}. Grant the runner's ` +
+              `service account the "Vertex AI User" role (aiplatform.endpoints.predict) ` +
+              `in the target project. See ${BACKEND_DOC_URL}.`
+          : backend === "bedrock"
+            // The most common Bedrock setup mistake: Anthropic models must
+            // be enabled per account ("Model access" in the Bedrock console,
+            // including the use-case submission), on top of IAM.
+            ? `Bedrock denied this call (HTTP 403) for ${context}. Enable this Claude model ` +
+              `under "Model access" in the Bedrock console (Anthropic models require a ` +
+              `use-case submission), and grant the runner's identity bedrock:InvokeModel ` +
+              `for the model and its inference profile. See ${BACKEND_DOC_URL}.`
+          : backend === "foundry"
+            ? `Microsoft Foundry denied this call (HTTP 403) for ${context}. Grant the ` +
+              `runner's Azure identity the "Foundry User" (or "Cognitive Services User") ` +
+              `RBAC role on the Foundry resource. See ${BACKEND_DOC_URL}.`
+            : `Access denied for ${context}. Verify that your API key has permission to use this model.`,
+      };
+    case 404:
+      return {
+        code: "LLM_MODEL_NOT_FOUND",
+        // The most common Vertex setup mistake: Claude models must be enabled
+        // per project in Model Garden, and availability varies by region.
+        message: backend === "vertex"
+          ? `Model not found on Vertex AI: ${context}. Enable this Claude model for your ` +
+            `project in the Vertex AI Model Garden, and confirm it is available in ` +
+            `${describeVertexRegion()} — availability varies by region. See ${BACKEND_DOC_URL}.`
+          : backend === "bedrock"
+            ? `Model not found on Bedrock: ${context}. Confirm the model is available in ` +
+              `${describeBedrockRegion()} — availability varies by region — and that the ` +
+              `resolved Bedrock id is right for your deployment (STIGMER_BEDROCK_MODEL_MAP ` +
+              `overrides, ${BEDROCK_INFERENCE_PREFIX_ENV} for inference profiles). See ${BACKEND_DOC_URL}.`
+          : backend === "foundry"
+            // The most common Foundry setup mistake: Foundry routes by
+            // DEPLOYMENT NAME, and deployments are created one by one in
+            // the portal — a model with no deployment (or a custom name)
+            // 404s even though the model itself exists on Foundry.
+            ? `Model deployment not found on Microsoft Foundry: ${context}. Foundry routes ` +
+              `by deployment name — confirm a deployment for this model exists in ` +
+              `${describeFoundryResource()} (default deployment names are the dateless ` +
+              `model ids), or map it to your custom deployment name in ` +
+              `${FOUNDRY_DEPLOYMENT_MAP_ENV}. See ${BACKEND_DOC_URL}.`
+            : `Model not found: ${context}. Verify the model name is correct and available in your account.`,
+      };
+    case 400:
+      return {
+        code: "LLM_BAD_REQUEST",
+        message: `Invalid request to ${context}: ${rawMessage}`,
+      };
+    case 422:
+      return {
+        code: "LLM_UNPROCESSABLE_REQUEST",
+        message: `Unprocessable request to ${context}: ${rawMessage}`,
+      };
+    case 429:
+      return {
+        code: "LLM_RATE_LIMIT",
+        message:
+          `Rate limit exceeded for ${context}. The provider's built-in retry was exhausted. ` +
+          `Try again later or reduce request frequency.`,
+      };
+    default:
+      if (status >= 500) {
+        return {
+          code: "LLM_PROVIDER_ERROR",
+          message: `${providerSubject(ctx)} returned a server error (HTTP ${status}) for ${context}: ${rawMessage}`,
+        };
+      }
+      return {
+        code: "LLM_API_ERROR",
+        message: `${providerSubject(ctx)} returned an API error (HTTP ${status}) for ${context}: ${rawMessage}`,
+      };
+  }
+}
+
+/**
+ * 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 function describeExecutionError(
+  err: unknown,
+  ctx: ModelErrorContext,
+): { errorType: string; errorMessage: string } {
+  const classified = classifyModelCallError(err, ctx);
+  if (classified) {
+    return { errorType: classified.code, errorMessage: classified.message };
+  }
+
+  const root = unwrapModelError(err);
+  return {
+    errorType: root instanceof Error ? root.constructor.name : "UnknownError",
+    errorMessage: root instanceof Error ? root.message : String(root),
+  };
+}
+
+/**
+ * The backend serving this direct-mode Anthropic call — the only condition
+ * under which a backend's specific arms may speak. Proxied calls and other
+ * providers read as "public" (no backend wording applies). The backend is
+ * resolved from env here (deployment-static, like the API keys
+ * model-client reads) rather than threaded through every activity's
+ * ModelErrorContext; an invalid var value also reads as public, since
+ * classification must never throw and invalid values are already fatal at
+ * the factories' preflight and at model construction.
+ */
+function resolveDirectBackend(ctx: ModelErrorContext): AnthropicBackend {
+  if (ctx.proxyMode || ctx.provider !== "anthropic") return "public";
+  const parsed = parseAnthropicBackend();
+  return parsed.ok ? parsed.backend : "public";
+}
+
+/**
+ * Google credential-acquisition prose, matched against the raw message.
+ * Narrow by design (mirrors isProviderBillingMessage): pinned to
+ * google-auth-library's ADC failure, its project-detection failure, the
+ * Vertex SDK's own projectId error, and OAuth's invalid_grant (expired or
+ * revoked service-account key). A miss falls through to status
+ * classification — never worse than the raw error.
+ */
+function isGoogleCredentialMessage(message: string): boolean {
+  const lower = message.toLowerCase();
+  return (
+    lower.includes("could not load the default credentials")
+    || lower.includes("unable to detect a project id")
+    || lower.includes("no projectid was given")
+    || lower.includes("invalid_grant")
+  );
+}
+
+/**
+ * AWS credential-acquisition prose, matched against the raw message.
+ * Narrow by design (mirrors isGoogleCredentialMessage): pinned to the AWS
+ * credential provider chain's terminal failure
+ * (@aws-sdk/credential-providers' CredentialsProviderError wordings) and
+ * the SigV4 signer's invalid-shape error. A miss falls through to status
+ * classification — never worse than the raw error.
+ */
+function isAwsCredentialMessage(message: string): boolean {
+  const lower = message.toLowerCase();
+  return (
+    lower.includes("could not load credentials from any providers")
+    || lower.includes("credential is missing")
+    || lower.includes("resolved credential object is not valid")
+  );
+}
+
+/**
+ * Bedrock's bare-model-id rejection prose (HTTP 400 ValidationException):
+ * "Invocation of model ID … with on-demand throughput isn't supported.
+ * Retry your request with the ID or ARN of an inference profile …".
+ * Matched narrowly on the phrase that only this condition carries.
+ */
+function isBedrockInferenceProfileMessage(message: string): boolean {
+  return message.toLowerCase().includes("on-demand throughput isn't supported");
+}
+
+/**
+ * Entra ID token-acquisition prose, matched against the raw message.
+ * Narrow by design (mirrors the Google/AWS matchers), and narrower than it
+ * looks: the Foundry SDK wraps EVERY token-provider failure — whatever
+ * @azure/identity's credential chain threw — in this one prefix before
+ * rethrowing (pinned by foundry-seam.test.ts), so a single phrase covers
+ * the whole family. A miss falls through to status classification — never
+ * worse than the raw error.
+ */
+function isFoundryCredentialMessage(message: string): boolean {
+  return message.toLowerCase().includes("failed to get token from azureadtokenprovider");
+}
+
+/** "region {value}" when CLOUD_ML_REGION is set, else a pointer to the var. */
+function describeVertexRegion(): string {
+  const region = process.env.CLOUD_ML_REGION?.trim();
+  return region ? `region "${region}"` : "your CLOUD_ML_REGION";
+}
+
+/** "region {value}" when AWS_REGION is set, else a pointer to the var. */
+function describeBedrockRegion(): string {
+  const region = process.env.AWS_REGION?.trim();
+  return region ? `region "${region}"` : "your AWS_REGION";
+}
+
+/** `resource "{value}"` when the resource var is set, else a generic label. */
+function describeFoundryResource(): string {
+  const resource = process.env[FOUNDRY_RESOURCE_ENV]?.trim();
+  return resource ? `resource "${resource}"` : "your Foundry resource";
+}
+
+/**
+ * Provider billing-exhaustion prose, matched against the raw message. Narrow
+ * by design: these phrases are pinned to real provider wordings (Anthropic's
+ * 400 billing prose; OpenAI's insufficient_quota / no-credits 429s). A miss
+ * falls through to status classification — never worse than today.
+ */
+function isProviderBillingMessage(message: string): boolean {
+  const lower = message.toLowerCase();
+  return (
+    lower.includes("credit balance is too low")
+    || lower.includes("insufficient_quota")
+    || lower.includes("exceeded your current quota")
+    || lower.includes("no credits remaining")
+  );
+}
+
+function providerLabel(ctx: ModelErrorContext): string {
+  if (ctx.provider === "anthropic") return "Anthropic";
+  if (ctx.provider === "openai") return "OpenAI";
+  return "the model provider";
+}
+
+/** Sentence-initial form: "Anthropic" / "The model provider". */
+function providerSubject(ctx: ModelErrorContext): string {
+  return ctx.provider ? providerLabel(ctx) : "The model provider";
+}
+
+function modelLabel(ctx: ModelErrorContext): string {
+  if (ctx.modelId && ctx.provider) return `model "${ctx.modelId}" (${providerLabel(ctx)})`;
+  if (ctx.modelId) return `model "${ctx.modelId}"`;
+  if (ctx.provider) return `the model (${providerLabel(ctx)})`;
+  return "the model";
+}

package/src/shared/model-facts.ts

@@ -0,0 +1,30 @@
+/**
+ * What a trace says about a model the runner built: where it is served
+ * from, in OpenTelemetry's GenAI provider names, the registry id it was
+ * asked for, and the provider API id it resolved to.
+ *
+ * `buildChatModel` (`model-client.ts`) records each model it builds, by the
+ * model instance; the native engine's span middleware reads them from the
+ * request's model (`middleware/otel-spans.ts`). So one middleware serves the
+ * parent's graph and every sub-agent's, each on the model it runs, with no
+ * per-stack configuration and no guess from a model's name. A module of its
+ * own, so a reader needs nothing of the model builder.
+ */
+
+export interface ChatModelFacts {
+  readonly providerName: string;
+  readonly requestModel: string;
+  readonly responseModel: string;
+}
+
+const MODEL_FACTS = new WeakMap<object, ChatModelFacts>();
+
+/** Record what the builder knows of `model`. */
+export function recordChatModelFacts(model: object, facts: ChatModelFacts): void {
+  MODEL_FACTS.set(model, facts);
+}
+
+/** The facts recorded for `model`; `undefined` for a model the runner did not build. */
+export function chatModelFacts(model: unknown): ChatModelFacts | undefined {
+  return typeof model === "object" && model !== null ? MODEL_FACTS.get(model) : undefined;
+}

package/src/shared/model-lanes.ts

@@ -0,0 +1,66 @@
+/**
+ * Provider lanes: how a process that holds no provider credential still
+ * calls a provider in direct mode.
+ *
+ * The agent host (`agent-host/host.ts`) runs the engines and holds none of
+ * the runner's keys (#2016). On a runner that calls its providers directly
+ * (a self-hosted runner, `STIGMER_PROXY_ENDPOINT` unset) the host's model
+ * clients keep their direct-mode shape — the same backend SDK, the same
+ * model-id translation, the same error wording — and only their transport
+ * changes: each client's base URL is a lane of the runner's local proxy
+ * (`agent-proxy/`), and its credential is the host's token. The lane checks
+ * the token and the turn, adds the operator's key (or signs with the
+ * runner's ambient cloud identity), and forwards to the provider; the
+ * response comes back unchanged, so the SDK parses what it always parsed.
+ *
+ * In the runner itself no lanes are installed and nothing here changes a
+ * client. On a runner that talks to the Stigmer platform's proxy the host
+ * is a proxy-mode runner instead (`config.proxyEndpoint` is the local
+ * proxy) and no lanes are installed either.
+ */
+
+/** The lanes one host process uses: the local proxy and the host's token there. */
+export interface ModelLanes {
+  readonly endpoint: string;
+  readonly token: string;
+}
+
+/** Each provider's lane, under the local proxy. Anthropic's and OpenAI's are the platform proxy's own paths. */
+export const MODEL_LANE_PATHS = {
+  anthropic: "/v1/proxy/llm/anthropic",
+  openai: "/v1/proxy/llm/openai/v1",
+  bedrock: "/v1/proxy/llm/bedrock",
+  vertex: "/v1/proxy/llm/vertex",
+  foundry: "/v1/proxy/llm/foundry",
+} as const;
+
+export type ModelLane = keyof typeof MODEL_LANE_PATHS;
+
+/**
+ * The project id a lane-bound Vertex client puts in its path. The client
+ * cannot resolve the real one (no Google identity in the host); the Vertex
+ * lane replaces the project segment with the runner's.
+ */
+export const VERTEX_LANE_PROJECT = "stigmer-lane";
+
+let installed: ModelLanes | undefined;
+
+/** Route this process's direct-mode model clients through the lanes at `endpoint`. Called once, by the agent host. */
+export function routeModelCallsThroughLanes(endpoint: string, token: string): void {
+  installed = { endpoint: endpoint.replace(/\/+$/, ""), token };
+}
+
+/** The installed lanes, or `undefined` in a process that calls providers itself. */
+export function modelLanes(): ModelLanes | undefined {
+  return installed;
+}
+
+/** One lane's base URL. */
+export function modelLaneUrl(lanes: ModelLanes, lane: ModelLane): string {
+  return `${lanes.endpoint}${MODEL_LANE_PATHS[lane]}`;
+}
+
+/** Test-only: forget the installed lanes. */
+export function resetModelLanesForTests(): void {
+  installed = undefined;
+}