@agent-native/core 0.132.2 → 0.133.0

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1645
+- core files: 1646
 - toolkit files: 168
-- template files: 7237
+- template files: 7413

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,166 @@
 # @agent-native/core
 
+## 0.133.0
+
+### Minor Changes
+
+- eecd3ad: Expose the measured agent failure taxonomy and let thread diagnostics separate interactive runs from scheduled `job-` runs.
+
+### Patch Changes
+
+- eecd3ad: Let a delegated A2A run inherit the caller's model when the receiving app never
+  picked one. A cross-app turn resolved its model entirely on the receiving side,
+  and the stored lookup is scoped to the receiver's own app id — so selecting
+  Sonnet in Slides still ran any question Slides delegated to Analytics on
+  Analytics' default. Nothing in the request carried the caller's choice.
+
+  `call-agent` now sends the model it is running on as `callerModel` in the
+  existing A2A correlation metadata, and the receiver applies it strictly last
+  before its default: explicit config, then its own stored setting, then the
+  hint. An app that deliberately pins a model keeps it; the hint only fills the
+  gap where the receiver would otherwise take a default it never chose.
+
+  The hint is a preference, never an authorization. It is bounded to the
+  receiver's already-resolved engine catalog by `resolveDelegatedRunModel`, so a
+  peer cannot move the run to another provider, an unknown id, or a capability
+  tier the engine does not offer; engines that cannot prove membership (empty
+  catalog, OpenAI-compatible gateway) take no hint at all. A rejected hint is
+  logged and dropped rather than failing the delegated run, and it stays out of
+  every identity, org, access, and approval path.
+
+- eecd3ad: Classify AI SDK provider failures that arrive as a stream part, not a throw.
+  `streamText` does not throw for a failed provider request — it emits an `error`
+  part on `fullStream` — so provider HTTP failures had two arrival paths and only
+  the thrown one was classified. The stream-part path built a bare stop event from
+  the message alone, discarding the `APICallError`'s `statusCode` and
+  `isRetryable`. Everything downstream then had nothing structured to read: a 429
+  or 503 was retried only if its prose happened to contain "rate_limit" or
+  "overloaded", and the run persisted `error_code = 'unknown'`.
+
+  That is also why a 100%-reproducible config 400 could run for three days across
+  five apps without anyone noticing: it was indistinguishable in the outcome
+  tables from every other unclassified failure, so it had no signature to alert
+  on.
+
+  Both paths now share one `classifyProviderError` helper — status code →
+  `http_<status>`, transport failure → `provider_network_error`, `isRetryable`
+  passed through, and a message-based fallback when the provider sent nothing
+  structured. Every ai-sdk provider (openai, anthropic, google, openrouter, groq,
+  mistral, cohere, ollama) gets correct classification at once.
+
+- eecd3ad: Recover chats from transient provider failures instead of ending them. A
+  provider transport blip reached persistence with no structured error code and
+  was stored as `unknown`, which the client does not list as auto-recoverable —
+  so the turn died where the identical failure carrying its real code resumes. In
+  production this was measurable: `unknown` runs averaged exactly 1.00 runs per
+  turn (no recovery was ever attempted), against 2.0 for `provider_network_error`
+  and 1.5 for `http_429` on the same underlying errors.
+
+  Four divergent copies of the connection-error predicate had drifted apart, and
+  they disagreed on the exact string the AI SDK actually throws — `RetryError`
+  reports `"Failed after 2 attempts. Last error: Cannot connect to API: …"`, which
+  a copy anchored with `startsWith` scored as unclassified while a copy using
+  `includes` scored as retryable. They are now one exported classifier in
+  `engine/error-detail.ts`, matched against the error's full cause chain, and
+  applied both where the error event is built (the code the client reads) and
+  where the run's terminal code is persisted. Transport and capacity failures map
+  to their real codes; deterministic failures stay unmapped so a broken request
+  still stops the chat instead of spiralling.
+
+  Also stop sending `reasoning_effort` alongside function tools for GPT models on
+  the Builder gateway. The gateway routes them to Chat Completions, which rejects
+  that combination outright, so every agent turn on a `gpt-5.x` model failed
+  deterministically. Omitting the field does not help — only the explicit `"none"`
+  clears it, matching the guard the AI SDK engine already had.
+
+- eecd3ad: Fail closed instead of silently ignoring a broken cross-isolate Stop check: a rejected abort-state read in the agent run manager no longer gets coerced into "not aborted" forever — sustained read failures now self-abort the run with a distinct, typed error. Also add the same fail-closed handling to two `isTurnAborted` call sites in the background-dispatch path that were missing it, matching the existing sibling call sites.
+- eecd3ad: Stop raw provider error text (a JSON error body, an SSL handshake failure) from
+  being persisted as the visible assistant reply. The server-side rebuild of an
+  assistant message (`buildAssistantMessage`, used by every background/durable
+  run, reconnect-after-disconnect, poller-triggered turn, and webhook-triggered
+  turn) appended `event.error` verbatim, unlike the live client which already
+  routes it through `normalizeChatError`/`formatChatErrorText` for friendly copy.
+  The rebuild now uses that same layer, so persisted text always matches what a
+  live client would have shown, and the raw diagnostic is kept only in
+  `runError.details`.
+- eecd3ad: Name the two deterministic provider failures that were ending chats as `unknown`: a model rejecting tools alongside `reasoning_effort`, and a missing authentication header. Both now carry a real error code and user-facing copy that says what to change, and both stay non-recoverable so nothing retries a failure a retry cannot fix.
+- eecd3ad: Preserve Builder design-system source provenance on local proxy references.
+- eecd3ad: Keep the signup email visible when an email-verification link opens a new tab, so the follow-up sign-in targets the verified account instead of a browser-autofilled address.
+- eecd3ad: Fix a split-brain in credential resolution: `resolveCredential` (and its diagnostic sibling `describeCredentialScopeGap`) only ever searched the single org on `ctx.orgId`. Interactive requests always populate it, but CLI runs, cron/recurring jobs, and any other caller built from `getCredentialContext()` outside a request event do not — so an org-scoped key that shows "Ready" in Settings silently missed at runtime for those callers. Both functions now fall back to resolving the caller's org from their email when `ctx.orgId` is unset, and a membership lookup that fails to read now throws a retryable error instead of being reported as "not configured". `resolveRequiredCredential` in the provider-api layer now also appends the scope-gap diagnostic to its error, matching `resolveAnyCredential`.
+- eecd3ad: Mark exhausted in-process agent-loop budgets as non-recoverable so the client does not restart the same exhausted run.
+- eecd3ad: Run scheduled jobs, automations, and Google Docs comment replies under the background timeout regime instead of the interactive one. They were inheriting the 40s soft timeout, a 30s no-progress backstop, and 6 continuations meant for a synchronous request, so work that legitimately spends minutes across many tool calls died in the first gap longer than 30s and was recorded as `no_progress`.
+- eecd3ad: Stop scheduled jobs and event automations from being killed mid-run as
+  "background_worker_never_started". `runBackgroundAutomation` (shared by
+  `jobs/scheduler.ts` and `triggers/dispatcher.ts`) executes entirely
+  in-process — there is no HTTP self-dispatch — but still marked its run row
+  `dispatch_mode = 'background'` for the wider stale window, without ever
+  calling `claimBackgroundRun` the way a genuine HTTP background worker does.
+  That left the row parked at the transient `'background'` state for the run's
+  entire life, indistinguishable from a lost HTTP handoff: the unclaimed-
+  background-run sweep reaps any such row past its 25s grace window, so a
+  single tool call running past 25s (routine for a report or analytics job)
+  got the still-executing run errored out from under it, discarding whatever
+  it later completed with.
+
+  The runner now self-claims its row into `'background-processing'`
+  immediately after inserting it — the same claimed state a real HTTP worker
+  reaches — which removes it from the unclaimed-sweep's eligibility (it filters
+  on `dispatch_mode = 'background'` exactly) and puts it under the wider,
+  heartbeat-driven stale window instead, with the correct `stale_run` code if
+  it ever genuinely dies.
+
+- eecd3ad: Stop resending a Builder credential the gateway already rejected. Every non-Builder provider already skipped a key marked bad by an auth failure; Builder credential selection (`resolveScopedBuilderCredentials`/`resolveBuilderCredentialsDetailed` in user/org/workspace/solo scope and the deploy-env fallback, plus `hasUsableBuilderConnection` and the env-detection path in the engine registry) now consults that same marker and falls through to the next scope instead of resending the identical known-bad key on every live and scheduled turn.
+- eecd3ad: Fix the Slack bot answering as the wrong app and silently dropping mentions
+
+  Outbound Slack delivery never passed an app id, so token resolution fell back
+  to a team-only lookup that took whichever installation was updated most
+  recently. A workspace with two connected Slack apps posted as whichever one
+  reconnected last. Outbound targets can now name an installation, and an
+  ambiguous tenant is reported instead of resolved to an arbitrary app.
+
+  Webhook dispatch also discarded a definitive `failed` outcome and answered the
+  platform 200 regardless, leaving a queued task nobody was running behind an
+  in-progress indicator that never resolved. That failure is now surfaced to the
+  user, and stuck-task recovery sweeps every dispatch mode rather than only
+  durable scopes — portable dispatch is the mode most likely to strand a task,
+  since its self-dispatch dies with the container.
+
+- eecd3ad: Stop a retry storm from deleting the answer the user already read. A rebuild
+  correctly refuses to apply a _trailing_ `clear` — there is no successor chunk to
+  re-emit what it wipes — but it only skipped the clear at the very last index.
+  Each failed engine attempt emits its own `clear`, so three failures in a row is
+  the ordinary shape, and the rebuild still applied the first two, splicing every
+  text and reasoning part out of the run. When the run had made no tool calls this
+  emptied the content entirely and the builder returned null, so the user's
+  message was persisted with no assistant reply at all. The whole trailing run of
+  clears is now skipped; a `clear` with real events after it still applies.
+
+  Also make `terminal_reason` write-once on an already-terminal row. Three writers
+  in three isolates race on that column — the mid-run checkpoint, the run-manager's
+  finalization, and the background worker's failure path — with no ordering
+  between them, and last-writer-wins let a late checkpoint relabel a run another
+  isolate had already finalized. That produced impossible rows (`status='errored'`
+  carrying a continuation reason, no `error_code`, no terminal event) and
+  misattributed 130 production runs to a failure mode they never hit. A row that
+  is still `running` has no honest reason yet and stays writable.
+
+- eecd3ad: Stop the unclaimed-background-run sweep from destroying the runs it exists to
+  recover. Its redispatch asserted `payloadRef: true` without checking the row
+  still carried a `dispatch_payload`, but sweep eligibility never implied one —
+  a background row can reach the grace window having never had a payload at all.
+  The redispatched worker then could not rehydrate a request body and failed the
+  run as `dispatch_payload_missing`, a reason that reads like data loss for what
+  is really an un-redispatchable handoff. That path accounted for 98 failed
+  production runs, every one of them a scheduled job.
+
+  `listUnclaimedBackgroundRunRows` now reports payload presence per row (it
+  reports rather than filters, so a payload-less row stays visible to the slow
+  sweep and cannot be stranded in `running` forever). The fast sweep skips those
+  rows, and the slow sweep sends them straight to its existing loud reap instead
+  of waiting out the redispatch bound first — the run still fails, because
+  nothing can rehydrate it, but with its true cause
+  (`background_worker_never_started`, which the client treats as recoverable).
+
 ## 0.132.2
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.132.2",
+  "version": "0.133.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/a2a/correlation.ts

@@ -5,6 +5,8 @@ export const MAX_A2A_DELEGATION_HOPS = 3;
 
 const APP_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const CORRELATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+// Model ids also carry `/` (provider-prefixed gateway ids).
+const MODEL_HINT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
 
 function boundedIdentifier(
   value: unknown,
@@ -29,7 +31,10 @@ export function sanitizeA2ACorrelationId(value: unknown): string | undefined {
 /**
  * Keep only bounded, opaque ASCII correlation identifiers. These values
  * remain telemetry hints; authentication continues to come exclusively from
- * the verified A2A token/request context.
+ * the verified A2A token/request context. `callerModel` is the one value here
+ * a receiver may act on, and only as a preference — it never reaches identity,
+ * org, access, or approval resolution, and it can only name a model the
+ * receiver's own engine already offers (see `resolveDelegatedRunModel`).
  */
 export function sanitizeA2ACorrelationMetadata(
   value: unknown,
@@ -41,6 +46,10 @@ export function sanitizeA2ACorrelationMetadata(
   const parentRunId = sanitizeA2ACorrelationId(metadata.parentRunId);
   const parentTurnId = sanitizeA2ACorrelationId(metadata.parentTurnId);
   const invocationId = sanitizeA2ACorrelationId(metadata.invocationId);
+  const callerModel = boundedIdentifier(
+    metadata.callerModel,
+    MODEL_HINT_PATTERN,
+  );
   const providedDelegationDepth =
     typeof metadata.delegationDepth === "number" &&
     Number.isInteger(metadata.delegationDepth) &&
@@ -77,5 +86,6 @@ export function sanitizeA2ACorrelationMetadata(
     ...(invocationId ? { invocationId } : {}),
     ...(delegationDepth !== undefined ? { delegationDepth } : {}),
     ...(visitedApps.length > 0 ? { visitedApps } : {}),
+    ...(callerModel ? { callerModel } : {}),
   };
 }

package/corpus/core/src/a2a/types.ts

@@ -160,9 +160,11 @@ export interface A2ASourceContextReference {
 }
 
 /**
- * Telemetry-only cross-app correlation. Receivers must never use these
- * caller-supplied values for identity, ownership, org scoping, access, or
- * approval decisions.
+ * Telemetry-only cross-app correlation, plus `callerModel` — a preference
+ * hint. Receivers must never use any caller-supplied value here for identity,
+ * ownership, org scoping, access, or approval decisions. `callerModel` widens
+ * this channel to a preference, never to an authorization: it may at most pick
+ * a model the receiver's already-resolved engine advertises.
  */
 export interface A2ACorrelationMetadata {
   callerApp?: string;
@@ -174,6 +176,12 @@ export interface A2ACorrelationMetadata {
   delegationDepth?: number;
   /** Bounded app ids already visited, used only for cycle prevention. */
   visitedApps?: string[];
+  /**
+   * Model the caller resolved for its own turn. A hint only: the receiver
+   * honours it just when it has no model of its own, and only after bounding
+   * it to its own engine's catalog.
+   */
+  callerModel?: string;
 }
 
 // --- Framework config ---

package/corpus/core/src/agent/engine/ai-sdk-engine.ts

@@ -23,7 +23,10 @@ import {
   supportsClaudeAdaptiveThinking,
 } from "../../shared/reasoning-effort.js";
 import { AI_SDK_MODEL_CONFIG, type AISDKProvider } from "../model-config.js";
-import { describeErrorWithCauses } from "./error-detail.js";
+import {
+  classifyProviderError,
+  describeErrorWithCauses,
+} from "./error-detail.js";
 import {
   createFirstEventAbortController,
   FIRST_STREAM_EVENT_TIMEOUT_MS,
@@ -440,6 +443,7 @@ class AISDKEngine implements AgentEngine {
       // before it, regardless of where `finish` arrives in the stream.
       let bufferedStop: EngineEvent | undefined;
       let sawFirstEvent = false;
+      let credentialFailureRecorded = false;
 
       for await (const part of result.fullStream) {
         // "start" is a synthetic lifecycle marker the AI SDK enqueues
@@ -453,6 +457,21 @@ class AISDKEngine implements AgentEngine {
         }
         for (const event of aiSdkPartToEngineEvents(part)) {
           observeStreamedToolInput(toolInputs, event);
+          if (
+            event.type === "stop" &&
+            event.reason === "error" &&
+            event.statusCode === 401
+          ) {
+            await recordProviderCredentialAuthFailure({
+              key: PROVIDER_ENV_VARS[this.provider][0],
+              value: this.apiKey,
+              status: event.statusCode,
+              code: event.errorCode ?? "http_401",
+              message:
+                event.error || "The model provider rejected the saved API key.",
+            });
+            credentialFailureRecorded = true;
+          }
           if (event.type === "stop") {
             bufferedStop = event;
           } else {
@@ -491,47 +510,25 @@ class AISDKEngine implements AgentEngine {
       }
 
       yield { type: "assistant-content", parts: assistantContent };
-      await clearProviderCredentialAuthFailure({
-        key: PROVIDER_ENV_VARS[this.provider][0],
-        value: this.apiKey,
-      });
+      if (!credentialFailureRecorded) {
+        await clearProviderCredentialAuthFailure({
+          key: PROVIDER_ENV_VARS[this.provider][0],
+          value: this.apiKey,
+        });
+      }
       yield bufferedStop ?? { type: "stop", reason: "end_turn" };
     } catch (err: any) {
       const timedOut = firstEventAbort.didTimeout();
-      // AI SDK wraps exhausted retries in RetryError and keeps the final
-      // APICallError on `lastError`. Read classification fields from that
-      // provider error so the retry wrapper does not erase transport status.
-      const providerError =
-        err?.lastError instanceof Error ? err.lastError : err;
-      // Surface structured fields from AI SDK's APICallError so
-      // isRetryableError can check statusCode/providerRetryable directly
-      // rather than keyword-matching the message string.
-      const statusCode: number | undefined =
-        typeof providerError?.statusCode === "number"
-          ? providerError.statusCode
-          : undefined;
-      const rawMessage: string =
-        providerError?.message ?? String(providerError);
-      // Classify on the bare message — the recorded `errorMessage` carries the
-      // cause chain, which is where the real transport failure lives.
       const errorMessage = describeErrorWithCauses(err);
-      const normalizedRawMessage = rawMessage.trim().toLowerCase();
-      const isConnectionError =
-        !timedOut &&
-        statusCode === undefined &&
-        (normalizedRawMessage === "connection error." ||
-          normalizedRawMessage.startsWith("cannot connect to api:"));
-      const providerRetryable: boolean | undefined =
-        typeof providerError?.isRetryable === "boolean"
-          ? providerError.isRetryable
-          : isConnectionError || timedOut
-            ? true
-            : undefined;
-      if (statusCode === 401) {
+      // Same classifier the stream-part path uses (translate-ai-sdk.ts) — a
+      // provider failure must not be classifiable only when it happens to
+      // throw.
+      const classification = classifyProviderError(err, timedOut);
+      if (classification.statusCode === 401) {
         await recordProviderCredentialAuthFailure({
           key: PROVIDER_ENV_VARS[this.provider][0],
           value: this.apiKey,
-          status: statusCode,
+          status: classification.statusCode,
           code: "http_401",
           message: errorMessage,
         });
@@ -540,17 +537,7 @@ class AISDKEngine implements AgentEngine {
         type: "stop",
         reason: "error",
         error: errorMessage,
-        // Tag every known status with `http_<status>` (not just 401) so a
-        // rate limit surfaces as `http_429`. The structured statusCode
-        // already drives turn-level retries, but the run-level continuation
-        // logic keys off the errorCode, so this lets a rate-limited turn
-        // auto-resume too — matching the Builder gateway path.
-        ...(statusCode !== undefined
-          ? { errorCode: `http_${statusCode}`, statusCode }
-          : isConnectionError || timedOut
-            ? { errorCode: "provider_network_error" }
-            : {}),
-        ...(providerRetryable !== undefined ? { providerRetryable } : {}),
+        ...classification,
       };
       throw err;
     } finally {

package/corpus/core/src/agent/engine/builder-engine.ts

@@ -22,6 +22,7 @@ import {
 } from "../../server/credential-provider.js";
 import { applyBuilderUtmTrackingParams } from "../../shared/builder-link-tracking.js";
 import {
+  isGPTReasoningModel,
   normalizeReasoningEffortForModel,
   type ReasoningEffort,
 } from "../../shared/reasoning-effort.js";
@@ -32,7 +33,10 @@ import {
   LLM_MISSING_CREDENTIALS_ERROR_CODE,
   LLM_MISSING_CREDENTIALS_MESSAGE,
 } from "./credential-errors.js";
-import { describeErrorWithCauses } from "./error-detail.js";
+import {
+  describeErrorWithCauses,
+  isProviderConnectionErrorMessage,
+} from "./error-detail.js";
 import { FIRST_STREAM_EVENT_TIMEOUT_MS } from "./first-event-timeout.js";
 import { resolveMaxOutputTokensForEngine } from "./output-tokens.js";
 import {
@@ -235,6 +239,8 @@ class BuilderEngine implements AgentEngine {
       }
     }
 
+    const gptToolsRequireExplicitNoReasoning =
+      cachedTools.length > 0 && isGPTReasoningModel(opts.model);
     const body: Record<string, unknown> = {
       model: opts.model,
       messages: cachedMessages,
@@ -248,7 +254,21 @@ class BuilderEngine implements AgentEngine {
       ...(typeof opts.temperature === "number"
         ? { temperature: opts.temperature }
         : {}),
-      ...(reasoningEffort ? { reasoning_effort: reasoningEffort } : {}),
+      // OpenAI rejects `reasoning_effort` alongside function tools on Chat
+      // Completions ("Function tools with reasoning_effort are not supported
+      // for <model> in /v1/chat/completions … or set reasoning_effort to
+      // 'none'"), and the gateway routes GPT models there. Every chat on a
+      // gpt-5.x model failed deterministically because of this. Omitting the
+      // field does NOT help — OpenAI then applies the model's own default
+      // effort and rejects identically; only the explicit "none" clears it.
+      // Same guard as the ai-sdk engine's forced-Chat-Completions path.
+      ...(reasoningEffort || gptToolsRequireExplicitNoReasoning
+        ? {
+            reasoning_effort: gptToolsRequireExplicitNoReasoning
+              ? "none"
+              : reasoningEffort,
+          }
+        : {}),
     };
 
     const gatewayBaseUrl = getBuilderGatewayBaseUrl();
@@ -1137,14 +1157,6 @@ function isBuilderGatewayNetworkError(err: unknown): boolean {
   );
 }
 
-function isProviderConnectionErrorMessage(message: string): boolean {
-  const normalized = message.trim().toLowerCase();
-  return (
-    normalized === "connection error." ||
-    normalized.includes("cannot connect to api:")
-  );
-}
-
 function captureBuilderGatewayTransportError(
   err: unknown,
   context: {

package/corpus/core/src/agent/engine/error-detail.ts

@@ -8,9 +8,6 @@
  * `.cause`. Recording `err.message` alone makes every one of them
  * indistinguishable after the fact, which is how a whole class of production
  * failures becomes undiagnosable.
- *
- * Classification (`isConnectionError`, `isRetryableError`) must keep matching
- * on the bare `err.message` — this is for the RECORDED detail only.
  */
 const DEFAULT_MAX_CAUSE_LINKS = 4;
 const MAX_CAUSE_LINK_CHARS = 200;
@@ -37,3 +34,187 @@ export function describeErrorWithCauses(
   }
   return links.length > 0 ? `${head} (cause: ${links.join(" <- ")})` : head;
 }
+
+/**
+ * The single provider-transport-failure classifier. Every layer that decides
+ * "is this a network blip?" — engine error codes, run-level retry, Sentry
+ * suppression — must call THIS, on `describeErrorWithCauses(err)` rather than
+ * on a bare `err.message`.
+ *
+ * Four divergent copies of this predicate existed, and they disagreed on
+ * exactly the string production actually throws. The AI SDK's `RetryError`
+ * reports `"Failed after 2 attempts. Last error: Cannot connect to API: …"`,
+ * so a copy anchored with `startsWith` scored it as unclassified while a copy
+ * using `includes` scored it as retryable. The result was a split brain: the
+ * agent loop retried the turn, but the run persisted `error_code = 'unknown'`,
+ * which the client does not list as auto-recoverable — so a transient TLS
+ * reset ended the user's chat with a dead error instead of resuming. That one
+ * mismatch accounted for ~150 failed production runs in a week.
+ *
+ * Substring matching is deliberate: the real message is always a provider SDK
+ * wrapper around the transport error, never bare, and the wrapper prefix
+ * differs per SDK and per version.
+ */
+export function isProviderConnectionErrorMessage(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return (
+    normalized.includes("connection error") ||
+    normalized.includes("cannot connect to api")
+  );
+}
+
+/** `isProviderConnectionErrorMessage` over an error's full cause chain. */
+export function isProviderConnectionError(err: unknown): boolean {
+  return isProviderConnectionErrorMessage(describeErrorWithCauses(err));
+}
+
+/** Classification fields an AI SDK provider failure carries. */
+export interface ProviderErrorClassification {
+  errorCode?: string;
+  statusCode?: number;
+  providerRetryable?: boolean;
+}
+
+/**
+ * Classify a provider error from the AI SDK, whichever way it surfaced.
+ *
+ * `streamText` does not throw for a failed provider request — it emits an
+ * `error` part on `fullStream` — so there are two arrival paths, and only the
+ * thrown one used to be classified. The stream-part path discarded
+ * `statusCode`, `errorCode`, and `isRetryable` entirely, which is why every
+ * provider HTTP failure on an ai-sdk engine landed as `unknown`: a 429 was only
+ * retried if its prose happened to contain "rate_limit", and a
+ * 100%-reproducible config 400 was indistinguishable from any other unclassified
+ * failure, so it had no signature to alert on. Both call sites go through here.
+ *
+ * `timedOut` is the caller's own first-event deadline, which only the streaming
+ * path can know.
+ */
+export function classifyProviderError(
+  err: unknown,
+  timedOut = false,
+): ProviderErrorClassification {
+  // The AI SDK wraps exhausted retries in RetryError and keeps the final
+  // APICallError on `lastError`.
+  const wrapped = err as { lastError?: unknown } | null;
+  const providerError = (
+    wrapped?.lastError instanceof Error ? wrapped.lastError : err
+  ) as {
+    statusCode?: unknown;
+    isRetryable?: unknown;
+    message?: unknown;
+  } | null;
+
+  const statusCode =
+    typeof providerError?.statusCode === "number"
+      ? providerError.statusCode
+      : undefined;
+
+  // Classify on the cause chain of the ORIGINAL error, not the unwrapped one:
+  // when RetryError does not expose `lastError` as an Error the unwrap falls
+  // back to the wrapper, whose message ("Failed after 2 attempts. Last error:
+  // …") only *embeds* the transport failure. Matching the wrapper is the point.
+  const described = describeErrorWithCauses(err);
+  const isConnectionError =
+    !timedOut &&
+    statusCode === undefined &&
+    (isProviderConnectionErrorMessage(described) ||
+      isProviderConnectionErrorMessage(
+        typeof providerError?.message === "string"
+          ? providerError.message
+          : String(providerError),
+      ));
+
+  const providerRetryable =
+    typeof providerError?.isRetryable === "boolean"
+      ? providerError.isRetryable
+      : isConnectionError || timedOut
+        ? true
+        : undefined;
+
+  return {
+    // Tag every known status as `http_<status>` (not just 401) so a rate limit
+    // surfaces as `http_429`: the structured statusCode drives turn-level
+    // retries, but run-level continuation keys off the errorCode.
+    ...(statusCode !== undefined
+      ? { errorCode: `http_${statusCode}`, statusCode }
+      : isConnectionError || timedOut
+        ? { errorCode: "provider_network_error" }
+        : // Nothing structured — fall back to reading the message, so a
+          // stream-part 529/timeout is not silently unclassified.
+          (() => {
+            const code = classifyTerminalErrorCode(described);
+            return code ? { errorCode: code } : {};
+          })()),
+    ...(providerRetryable !== undefined ? { providerRetryable } : {}),
+  };
+}
+
+/**
+ * Last-resort error code for a terminal error that reached persistence with no
+ * structured code. Persisting `"unknown"` is not a neutral default: the client
+ * auto-recovers a fixed list of transport codes, so an unclassified transient
+ * blip ends the user's chat while the identical failure carrying its real code
+ * resumes. Over four days that gap was 28% of ALL production chat turns.
+ *
+ * The invariant is NOT "only transport failures may be named". It is: a code
+ * returned here must be absent from the client's recoverable list unless a
+ * fresh attempt genuinely helps. Naming a deterministic failure is what stops
+ * it from reaching the user as raw provider text and hiding inside `unknown`;
+ * naming it *recoverable* is what buys a retry spiral. Those are different
+ * decisions, and `error-detail.spec.ts` asserts the deterministic codes below
+ * stay non-recoverable.
+ */
+export function classifyTerminalErrorCode(
+  message: string | undefined,
+): string | undefined {
+  if (!message) return undefined;
+  const msg = message.toLowerCase();
+  if (isProviderConnectionErrorMessage(msg)) return "provider_network_error";
+  // Word-bounded: request ids and hashes routinely contain a bare "529".
+  if (msg.includes("overloaded") || /\b529\b/.test(msg)) {
+    return "overloaded_error";
+  }
+  if (msg.includes("too many requests") || /\b429\b/.test(msg)) {
+    return "http_429";
+  }
+  if (
+    msg.includes("timed out") ||
+    msg.includes("timeout") ||
+    msg.includes("too much time has passed without sending any data")
+  ) {
+    return "timeout";
+  }
+  if (msg.includes("stream ended without a stop event")) {
+    return "builder_gateway_network_error";
+  }
+  // Deterministic below this line — named so they stop landing in `unknown`,
+  // never retried. Both were measured against the 13 prod app DBs over
+  // 2026-07-24..31: 27 turns/week and 14 turns/week respectively, each with
+  // exactly 1.00 runs/turn, i.e. the chat died on the first attempt showing
+  // the raw provider sentence.
+  //
+  // The request side already avoids emitting reasoning_effort alongside tools
+  // (see ai-sdk-engine.ts). This classifies the failure for the paths that
+  // still reach the provider — another gateway, a stale deploy — so it reads
+  // as a configuration problem rather than a mystery.
+  if (
+    msg.includes("reasoning_effort are not supported") ||
+    msg.includes("reasoning_effort to 'none'") ||
+    (msg.includes("reasoning_effort") &&
+      (msg.includes("tools") || msg.includes("function")))
+  ) {
+    return "provider_config_error";
+  }
+  if (msg.includes("missing authentication header") || msg === "unauthorized") {
+    return "authentication_error";
+  }
+  if (
+    /(?:err_)?ssl|tlsv?\d|tls handshake|ssl routines|econnreset|econnrefused|und_err_socket|socket hang up/i.test(
+      message,
+    )
+  ) {
+    return "provider_network_error";
+  }
+  return undefined;
+}