@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

package/src/shared/model-client.ts

@@ -6,10 +6,11 @@
  * (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` stays pure routing utilities (no LangChain
- * dependency); this module is the LangChain-aware layer above it that owns
- * the resolve -> infer-provider -> strip-prefix -> proxy-wire -> construct
- * sequence that used to be copy-pasted across every LLM activity.
+ * 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.
  */
 
 import { ChatAnthropic } from "@langchain/anthropic";
@@ -23,6 +24,15 @@ import {
   buildProxyHeaders,
   type LlmProvider,
 } from "./llm-proxy.js";
+import {
+  resolveAnthropicBackend,
+  checkVertexPrerequisites,
+  checkBedrockPrerequisites,
+  checkFoundryPrerequisites,
+  toVertexModelId,
+  toBedrockModelId,
+  toFoundryDeploymentName,
+} from "./llm-backend.js";
 import { resolveToApiModelId } from "./model-registry.js";
 
 export interface BuildChatModelOptions {
@@ -45,14 +55,37 @@ export interface BuildChatModelOptions {
    * stays the caller's decision to avoid silently changing behavior.
    */
   readonly maxTokens?: number;
+  /**
+   * Per-request bound. When omitted, defaults to the operator's
+   * STIGMER_LLM_REQUEST_TIMEOUT_MS — resolved HERE, not per caller, so no
+   * call site can drop the bound by forgetting to plumb it (the sub-agent
+   * factory did exactly that; stigmer/stigmer#468). An explicit value wins.
+   */
   readonly timeoutMs?: number;
   readonly maxRetries?: number;
 }
 
+/**
+ * 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(): number | undefined {
+  const parsed = Number.parseInt(process.env.STIGMER_LLM_REQUEST_TIMEOUT_MS ?? "", 10);
+  return parsed > 0 ? parsed : undefined;
+}
+
 export interface BuiltChatModel {
   readonly model: BaseChatModel;
   readonly provider: LlmProvider;
-  /** The resolved id actually handed to the provider. */
+  /**
+   * The canonical provider API id the registry resolved to — what pricing
+   * and usage metrics key on. A backend adapter may translate it for the
+   * wire (Vertex separates the snapshot date with `@`), but the translated
+   * form never leaves the adapter: this field stays canonical (the
+   * canonical-id invariant in design decision 001-provider-backends).
+   */
   readonly apiModelId: string;
 }
 
@@ -66,6 +99,106 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
   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";
+
+  // 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. Credentials are read natively by each SDK from its
+  // standard conventions (GCP: CLOUD_ML_REGION + ADC; AWS: AWS_REGION +
+  // the credential chain / AWS_BEARER_TOKEN_BEDROCK; Foundry:
+  // ANTHROPIC_FOUNDRY_API_KEY, or the Azure credential chain when no key
+  // is set).
+  let backendCreateClient:
+    | ((options: { maxRetries?: number; timeout?: number }) => unknown)
+    | undefined;
+  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");
+    backendCreateClient = (options) =>
+      new AnthropicVertex({ maxRetries: options.maxRetries, timeout: options.timeout });
+    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");
+    backendCreateClient = (options) =>
+      new AnthropicBedrock({ 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.
+    let azureADTokenProvider: (() => Promise<string>) | undefined;
+    if (!process.env.ANTHROPIC_FOUNDRY_API_KEY?.trim()) {
+      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,
+        ...(azureADTokenProvider ? { 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);
+  }
 
   const baseUrl = opts.proxyEndpoint
     ? resolveProxyBaseUrl(opts.proxyEndpoint, provider)
@@ -85,10 +218,30 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
   const common = {
     temperature: opts.temperature ?? 0,
     apiKey,
-    ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
-    ...(opts.timeoutMs ? { maxRetries: opts.maxRetries ?? 0, timeout: opts.timeoutMs } : {}),
+    ...(maxTokens ? { maxTokens } : {}),
+    ...(timeoutMs ? { maxRetries: opts.maxRetries ?? 0 } : {}),
   };
 
+  // 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 (T02 finding 2).
+  // 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 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.
@@ -96,6 +249,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     ? new ChatOpenAI({
         model: apiModelId,
         ...common,
+        ...(timeoutMs ? { timeout: timeoutMs } : {}),
         ...(baseUrl || headers
           ? {
               configuration: {
@@ -105,18 +259,24 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
             }
           : {}),
       })
-    : new ChatAnthropic({
-        model: apiModelId,
-        ...common,
-        ...(baseUrl || headers
-          ? {
-              clientOptions: {
-                ...(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.)
+        new ChatAnthropic({
+          model: wireModelId,
+          ...common,
+          ...anthropicClientOptionsField,
+          createClient: backendCreateClient,
+        })
+      : new ChatAnthropic({
+          model: apiModelId,
+          ...common,
+          ...anthropicClientOptionsField,
+        });
 
   return { model, provider, apiModelId };
 }

package/src/shared/model-error.ts

@@ -26,6 +26,14 @@
  */
 
 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 rewritten platform-fault
@@ -96,6 +104,7 @@ export function classifyModelCallError(
 ): ClassifiedModelError | undefined {
   const root = unwrapModelError(err);
   const message = root instanceof Error ? root.message : String(root);
+  const backend = resolveDirectBackend(ctx);
 
   // 1. Platform sentinel — before status mapping (see module doc).
   if (message.includes(PLATFORM_CAPACITY_SENTINEL)) {
@@ -106,6 +115,69 @@ export function classifyModelCallError(
     };
   }
 
+  // 1b. Backend credential acquisition — also 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",
+      retryable: false,
+      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",
+      retryable: false,
+      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",
+      retryable: false,
+      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}`,
+    };
+  }
+
+  // 1c. 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",
+      retryable: false,
+      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. In direct mode this is the user's own
   //    account and the fix is theirs. In proxy mode these patterns should
   //    never appear (the proxy rewrites them), but a version-skewed proxy
@@ -135,7 +207,7 @@ export function classifyModelCallError(
     ? (root as { status: number }).status
     : undefined;
   if (status !== undefined) {
-    return classifyByStatus(status, message, ctx);
+    return classifyByStatus(status, message, ctx, backend);
   }
 
   // 4. Connection/timeout heuristics on the root error's class name. Strict
@@ -175,6 +247,7 @@ function classifyByStatus(
   status: number,
   rawMessage: string,
   ctx: ModelErrorContext,
+  backend: AnthropicBackend,
 ): ClassifiedModelError {
   const context = modelLabel(ctx);
 
@@ -186,7 +259,23 @@ function classifyByStatus(
         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.`
-          : `Authentication failed for ${context}. Check that your API key is valid and not expired.`,
+          // 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 {
@@ -195,13 +284,50 @@ function classifyByStatus(
         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.`
-          : `Access denied for ${context}. Verify that your API key has permission to use this model.`,
+          : 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",
         retryable: false,
-        message: `Model not found: ${context}. Verify the model name is correct and available in your account.`,
+        // 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 {
@@ -260,6 +386,98 @@ export function describeExecutionError(
   };
 }
 
+/**
+ * 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

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

@@ -30,9 +30,18 @@ interface RegistryEntry {
   };
 }
 
-import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
+import {
+  resolveModelRegistryUrl,
+  buildRegistryHeaders,
+  REGISTRY_RETRY_POLICY,
+} from "./registry-endpoint.js";
+import { fetchWithRetry } from "./http-retry.js";
 
 const CACHE_TTL_MS = 3_600_000;
+// Failed fetches are cached much shorter than successes (the model-registry.ts
+// policy): a transient failure must not pin DEFAULT_PRICING — wrong rates for
+// cost tracking — for a full hour.
+const FAILURE_CACHE_TTL_MS = 60_000;
 
 export const DEFAULT_PRICING: ModelPricing = {
   model: "unknown",
@@ -66,7 +75,11 @@ function parsePricingTable(json: unknown): ModelPricing[] {
 }
 
 async function fetchFromApi(): Promise<readonly ModelPricing[]> {
-  const res = await fetch(resolveModelRegistryUrl(), { headers: buildRegistryHeaders() });
+  const res = await fetchWithRetry(
+    resolveModelRegistryUrl(),
+    { headers: buildRegistryHeaders() },
+    REGISTRY_RETRY_POLICY,
+  );
   if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
   const data: unknown = await res.json();
   const table = parsePricingTable(data);
@@ -93,7 +106,7 @@ export async function getPricingTable(): Promise<readonly ModelPricing[]> {
         `Failed to fetch model registry, using default pricing: ${err}`,
       );
       const fallback = [DEFAULT_PRICING];
-      cache = { data: fallback, expiresAt: Date.now() + CACHE_TTL_MS };
+      cache = { data: fallback, expiresAt: Date.now() + FAILURE_CACHE_TTL_MS };
       return fallback;
     })
     .finally(() => {
@@ -102,3 +115,9 @@ export async function getPricingTable(): Promise<readonly ModelPricing[]> {
 
   return inflightFetch;
 }
+
+/** Exposed for testing — resets the in-memory cache. */
+export function _resetPricingCache(): void {
+  cache = null;
+  inflightFetch = null;
+}

package/src/shared/model-registry.ts

@@ -10,7 +10,12 @@
  * (getModelVisionCapability).
  */
 
-import { resolveModelRegistryUrl, buildRegistryHeaders } from "./registry-endpoint.js";
+import {
+  resolveModelRegistryUrl,
+  buildRegistryHeaders,
+  REGISTRY_RETRY_POLICY,
+} from "./registry-endpoint.js";
+import { fetchWithRetry } from "./http-retry.js";
 
 const CACHE_TTL_MS = 3_600_000;
 // Failed fetches are cached much shorter than successes: a transient failure
@@ -68,7 +73,7 @@ function parseVisionCapability(capabilities: unknown): boolean | undefined {
 
 async function fetchRegistry(): Promise<readonly RegistryModel[]> {
   const url = resolveModelRegistryUrl();
-  const res = await fetch(url, { headers: buildRegistryHeaders() });
+  const res = await fetchWithRetry(url, { headers: buildRegistryHeaders() }, REGISTRY_RETRY_POLICY);
   if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
   const data: unknown = await res.json();
   return parseRegistry(data);

package/src/shared/plan-mode-permissions.ts

@@ -0,0 +1,37 @@
+/**
+ * The Plan-mode filesystem permission rules — the enforcement twin of
+ * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
+ *
+ * Plan mode is read-only BY CONSTRUCTION on the native harness: these rules
+ * deny every filesystem write operation at the tool level so
+ * write_file/edit_file cannot mutate the workspace regardless of what the
+ * model was told. Rules are first-match-wins with a permissive default, so a
+ * single deny-all-writes rule is sufficient. (The Cursor harness has no
+ * tool-level lever and enforces plan mode via its prompt prefix instead.)
+ *
+ * Applied in execute-deep-agent/setup.ts to the parent graph AND threaded
+ * into every compiled sub-agent graph: deepagents' parent-permission
+ * inheritance covers only spec-style sub-agents, and ours are pre-built
+ * CompiledSubAgents, so each sub-agent graph must carry the rules itself
+ * (issue #255). Kept as its own side-effect-free module so tests can pin the
+ * production rules without dragging in setup.ts's import graph.
+ *
+ * Rules travel with a companion: every graph that carries them also installs
+ * the path-normalization middleware (middleware/path-normalization.ts,
+ * issue #429), because deepagents' rule validation refuses workspace-relative
+ * paths outright — without the shim, prompt-compliant relative READS die in
+ * validation instead of just working. Both are derived from the same
+ * expression at each composition site so they cannot drift apart.
+ *
+ * Invariant: never combine these rules with a shell-capable (sandbox)
+ * backend — deepagents rejects that pairing at graph construction (see the
+ * cas-capture-backend.ts header). Plan mode guarantees it by construction:
+ * it is the mode that clears `shellEnv`, and `shellEnv` is the single switch
+ * for shell capability on both the parent and sub-agent backends.
+ */
+
+import type { FilesystemPermission } from "deepagents";
+
+export const PLAN_MODE_PERMISSIONS: FilesystemPermission[] = [
+  { operations: ["write"], paths: ["/**"], mode: "deny" },
+];