@agent-native/core 0.132.2 → 0.133.1

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,186 @@
 # @agent-native/core
 
+## 0.133.1
+
+### Patch Changes
+
+- 1c08605: Fail closed when an `ai-sdk:*` engine has no provider key, instead of sending an
+  unauthenticated request. The provider factory was previously built with no
+  `apiKey`, so the SDK omitted the Authorization header and the gateway's 401 came
+  back as `http_401` "Missing Authentication header" — a transport error naming the
+  wrong cause, which a scheduled job then retried on every tick forever. It now
+  reports `missing_credentials` and names the env var it wants, matching what
+  `builder-engine` and `anthropic-engine` already did.
+
+  Also stop reaping in-process background automations (scheduler and trigger runs)
+  at the tight 45s post-claim stale window. That window exists to reach a durable
+  successor sooner, but these runs carry no `dispatch_payload` and have no
+  successor to reach, so an early reap killed still-working jobs that nothing could
+  recover. They now get the 90s background window, and the recovery path reports
+  `not_redispatchable` rather than `payload_missing`, which read as data loss for
+  the one case where nothing was ever lost.
+
+## 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.1",
   "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,14 @@ 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 {
+  LLM_MISSING_CREDENTIALS_ERROR_CODE,
+  LLM_MISSING_CREDENTIALS_MESSAGE,
+} from "./credential-errors.js";
+import {
+  classifyProviderError,
+  describeErrorWithCauses,
+} from "./error-detail.js";
 import {
   createFirstEventAbortController,
   FIRST_STREAM_EVENT_TIMEOUT_MS,
@@ -225,6 +232,8 @@ class AISDKEngine implements AgentEngine {
   private readonly provider: AISDKProvider;
   private readonly apiKey?: string;
   private readonly baseUrl?: string;
+  /** Empty for providers that need no key (ollama). */
+  private readonly requiredEnvVars: readonly string[];
   private readonly appName?: string;
   private readonly appUrl?: string;
 
@@ -240,12 +249,34 @@ class AISDKEngine implements AgentEngine {
     this.apiKey =
       config.apiKey ??
       (config.allowEnvFallback === false ? "" : getProviderApiKey(provider));
+    this.requiredEnvVars = PROVIDER_ENV_VARS[provider];
     this.baseUrl = config.baseUrl;
     this.appName = config.appName;
     this.appUrl = config.appUrl;
   }
 
   async *stream(opts: EngineStreamOptions): AsyncIterable<EngineEvent> {
+    // An absent key is not an anonymous request. Without this the provider
+    // factory is constructed with no `apiKey`, the SDK omits the Authorization
+    // header entirely, and the gateway's 401 comes back as
+    // "Missing Authentication header" — which `classifyProviderError` codes
+    // `http_401`, a transport failure naming the wrong cause. A scheduled job
+    // then repeats that doomed unauthenticated request on every tick forever.
+    // `builder-engine` and `anthropic-engine` already fail closed here; this
+    // engine was the only one that did not.
+    //
+    // A configured `baseUrl` is exempt: a self-hosted or local gateway may
+    // legitimately accept unauthenticated requests.
+    if (!this.apiKey && !this.baseUrl && this.requiredEnvVars.length > 0) {
+      yield {
+        type: "stop",
+        reason: "error",
+        error: `${LLM_MISSING_CREDENTIALS_MESSAGE} (engine "${this.name}" has no ${this.requiredEnvVars.join(" or ")})`,
+        errorCode: LLM_MISSING_CREDENTIALS_ERROR_CODE,
+      };
+      return;
+    }
+
     let aiModule: any;
     try {
       aiModule = await import("ai");
@@ -440,6 +471,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 +485,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 +538,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 +565,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: {