@agent-native/core 0.122.4 → 0.123.1

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

@@ -23,6 +23,7 @@ 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 {
   createFirstEventAbortController,
   FIRST_STREAM_EVENT_TIMEOUT_MS,
@@ -37,6 +38,11 @@ import {
   aiSdkPartToEngineEvents,
   aiSdkStepToAssistantContent,
 } from "./translate-ai-sdk.js";
+import {
+  createStreamedToolInputState,
+  finalizeStreamedToolInputs,
+  observeStreamedToolInput,
+} from "./translate-anthropic.js";
 import type {
   AgentEngine,
   EngineCapabilities,
@@ -345,10 +351,27 @@ class AISDKEngine implements AgentEngine {
           };
         }
       } else if (this.provider === "openai") {
-        providerOpts.openai = {
-          ...((providerOpts.openai as object) ?? {}),
-          reasoningEffort,
-        };
+        // OpenAI rejects `reasoning_effort` together with function tools on
+        // the legacy Chat Completions surface for some reasoning models
+        // ("Function tools with reasoning_effort are not supported for
+        // <model> in /v1/chat/completions. To use function tools, use
+        // /v1/responses or set reasoning_effort to 'none'.") — a real prod
+        // incident, e.g. Sentry AGENT-NATIVE-BROWSER-94 on gpt-5.6-terra.
+        // `createProviderModel` forces Chat Completions specifically when
+        // `this.baseUrl` is set (many OpenAI-compatible gateways/proxies
+        // don't implement Responses — see that comment). In that exact
+        // combination — forced Chat Completions AND tools present — drop
+        // the explicit override and let the model use its default reasoning
+        // behavior instead of hard-failing the whole request; Responses-API
+        // calls (no baseUrl) are unaffected and keep full effort control.
+        const forcedChatCompletionsWithTools =
+          Boolean(this.baseUrl) && aiSdkTools !== undefined;
+        if (!forcedChatCompletionsWithTools) {
+          providerOpts.openai = {
+            ...((providerOpts.openai as object) ?? {}),
+            reasoningEffort,
+          };
+        }
       } else if (this.provider === "openrouter") {
         providerOpts.openrouter = {
           ...((providerOpts.openrouter as object) ?? {}),
@@ -384,6 +407,7 @@ class AISDKEngine implements AgentEngine {
 
     let assistantContent: EngineContentPart[] = [];
     const firstEventAbort = createFirstEventAbortController(opts.abortSignal);
+    const toolInputs = createStreamedToolInputState();
 
     try {
       const result = streamText({
@@ -392,6 +416,10 @@ class AISDKEngine implements AgentEngine {
         messages,
         tools: aiSdkTools,
         maxOutputTokens: resolvedMaxOutputTokens,
+        // Explicit: the agent loop already retries a failed model call with
+        // backoff. Leaving the SDK on its default (2) multiplies the two retry
+        // layers into ~12 HTTP requests per failed run.
+        maxRetries: 1,
         ...(opts.temperature !== undefined
           ? { temperature: opts.temperature }
           : {}),
@@ -420,6 +448,7 @@ class AISDKEngine implements AgentEngine {
           firstEventAbort.markFirstEvent();
         }
         for (const event of aiSdkPartToEngineEvents(part)) {
+          observeStreamedToolInput(toolInputs, event);
           if (event.type === "stop") {
             bufferedStop = event;
           } else {
@@ -437,6 +466,26 @@ class AISDKEngine implements AgentEngine {
         );
       }
 
+      // A step can finish having announced a tool call it never delivered.
+      // Assemble it from its deltas, or report it in-band, rather than ending
+      // the turn as if the model never asked for it.
+      for (const recovered of finalizeStreamedToolInputs(
+        toolInputs,
+        assistantContent.flatMap((part) =>
+          part.type === "tool-call" ? [part.id] : [],
+        ),
+      )) {
+        if (recovered.type === "tool-call") {
+          assistantContent.push({
+            type: "tool-call",
+            id: recovered.id,
+            name: recovered.name,
+            input: recovered.input,
+          });
+        }
+        yield recovered;
+      }
+
       yield { type: "assistant-content", parts: assistantContent };
       await clearProviderCredentialAuthFailure({
         key: PROVIDER_ENV_VARS[this.provider][0],
@@ -450,11 +499,14 @@ class AISDKEngine implements AgentEngine {
       // rather than keyword-matching the message string.
       const statusCode: number | undefined =
         typeof err?.statusCode === "number" ? err.statusCode : undefined;
-      const errorMessage = err?.message ?? String(err);
+      const rawMessage: string = err?.message ?? String(err);
+      // 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 isConnectionError =
         !timedOut &&
         statusCode === undefined &&
-        String(errorMessage).trim().toLowerCase() === "connection error.";
+        rawMessage.trim().toLowerCase() === "connection error.";
       const providerRetryable: boolean | undefined =
         typeof err?.isRetryable === "boolean"
           ? err.isRetryable

package/src/agent/engine/anthropic-engine.ts

@@ -23,6 +23,7 @@ import {
   LLM_MISSING_CREDENTIALS_ERROR_CODE,
   LLM_MISSING_CREDENTIALS_MESSAGE,
 } from "./credential-errors.js";
+import { describeErrorWithCauses } from "./error-detail.js";
 import {
   createFirstEventAbortController,
   FIRST_STREAM_EVENT_TIMEOUT_MS,
@@ -31,12 +32,19 @@ import {
   clampThinkingBudgetTokens,
   resolveMaxOutputTokensForEngine,
 } from "./output-tokens.js";
+import {
+  splitSystemPromptForCache,
+  stablePrefixCacheControl,
+} from "./prompt-cache.js";
 import {
   engineToolsToAnthropic,
   engineMessagesToAnthropic,
   anthropicContentToEngine,
   anthropicChunkToEngineEvents,
   createAnthropicChunkStreamState,
+  createStreamedToolInputState,
+  finalizeStreamedToolInputs,
+  observeStreamedToolInput,
 } from "./translate-anthropic.js";
 import type {
   AgentEngine,
@@ -72,7 +80,10 @@ class AnthropicEngine implements AgentEngine {
 
   async *stream(opts: EngineStreamOptions): AsyncIterable<EngineEvent> {
     const Anthropic = (await import("@anthropic-ai/sdk")).default;
-    const client = new Anthropic({ apiKey: this.apiKey });
+    // Explicit: the agent loop already retries a failed model call up to
+    // MAX_RETRIES times with backoff. Leaving the SDK on its default (2)
+    // multiplies the two layers into ~12 HTTP requests per failed run.
+    const client = new Anthropic({ apiKey: this.apiKey, maxRetries: 1 });
 
     const tools = engineToolsToAnthropic(opts.tools);
     const messages = engineMessagesToAnthropic(opts.messages);
@@ -133,10 +144,16 @@ class AnthropicEngine implements AgentEngine {
     // changes turn-to-turn, it's a no-op. Templates can opt out by setting
     // providerOptions.anthropic.cacheControl = false.
     const cacheEnabled = anthropicOpts?.cacheControl !== false;
-    const systemBlocks: any[] = [{ type: "text", text: opts.systemPrompt }];
+    // Two system blocks: the breakpoint sits on the stable prefix so a change
+    // in the volatile tail (resources the agent itself creates mid-turn, app
+    // extras, model overlay, runtime context) no longer invalidates system +
+    // tools. Callers that emit no sentinel get one block, as before.
+    const { stable, volatile } = splitSystemPromptForCache(opts.systemPrompt);
+    const systemBlocks: any[] = [{ type: "text", text: stable }];
     if (cacheEnabled) {
-      systemBlocks[0].cache_control = { type: "ephemeral" };
+      systemBlocks[0].cache_control = stablePrefixCacheControl();
     }
+    if (volatile) systemBlocks.push({ type: "text", text: volatile });
 
     // Apply cache_control to the last tool definition when caching is enabled.
     // Anthropic caches the prefix up to and including the last cached block.
@@ -144,14 +161,16 @@ class AnthropicEngine implements AgentEngine {
     if (cacheEnabled && tools.length > 0) {
       cachedTools = [...tools];
       const last = { ...cachedTools[cachedTools.length - 1] } as any;
-      last.cache_control = { type: "ephemeral" };
+      last.cache_control = stablePrefixCacheControl();
       cachedTools[cachedTools.length - 1] = last;
     }
 
     // Apply a moving cache breakpoint on the last user message's last content
     // block so the entire conversation prefix (system + tools + growing
     // history) is cached turn-over-turn as the thread lengthens. Mirrors the
-    // Builder gateway engine's identical handling in builder-engine.ts.
+    // Builder gateway engine's identical handling in builder-engine.ts. This
+    // breakpoint keeps the default 5m TTL: it moves every iteration, so a
+    // longer-lived entry would only pay the higher write premium.
     let cachedMessages = messages;
     if (cacheEnabled && messages.length > 0) {
       let lastUserIdx = -1;
@@ -200,6 +219,7 @@ class AnthropicEngine implements AgentEngine {
     // long tool-input generation emits countable `tool-input-start` /
     // `tool-input-delta` progress events (mirroring the Builder engine).
     const chunkState = createAnthropicChunkStreamState();
+    const toolInputs = createStreamedToolInputState();
 
     try {
       for await (const chunk of apiStream) {
@@ -208,6 +228,7 @@ class AnthropicEngine implements AgentEngine {
         firstEventAbort.markFirstEvent();
         const events = anthropicChunkToEngineEvents(chunk, chunkState);
         for (const event of events) {
+          observeStreamedToolInput(toolInputs, event);
           yield event;
         }
       }
@@ -215,6 +236,26 @@ class AnthropicEngine implements AgentEngine {
       const finalMessage = await apiStream.finalMessage();
       const assistantContent = anthropicContentToEngine(finalMessage.content);
 
+      // A tool call the stream announced but the final message never carried
+      // would otherwise vanish, leaving the turn claiming an action it never
+      // ran. Recover it from its deltas, or tell the model in-band.
+      for (const recovered of finalizeStreamedToolInputs(
+        toolInputs,
+        assistantContent.flatMap((part) =>
+          part.type === "tool-call" ? [part.id] : [],
+        ),
+      )) {
+        if (recovered.type === "tool-call") {
+          assistantContent.push({
+            type: "tool-call",
+            id: recovered.id,
+            name: recovered.name,
+            input: recovered.input,
+          });
+        }
+        yield recovered;
+      }
+
       // Emit usage
       if (finalMessage.usage) {
         yield {
@@ -256,16 +297,18 @@ class AnthropicEngine implements AgentEngine {
       // A first-event abort surfaces from the SDK as a generic
       // APIUserAbortError ("Request was aborted.") — replace it with a
       // message that actually explains what happened.
+      const rawMessage: string = err?.message ?? String(err);
       const errorMessage = timedOut
         ? `Model request produced no stream events within ${FIRST_STREAM_EVENT_TIMEOUT_MS / 1000}s; the connection appears wedged.`
-        : (err?.message ?? String(err));
+        : describeErrorWithCauses(err);
       // Anthropic SDK APIConnectionError defaults to "Connection error." with
       // no HTTP status. Tag it so in-run retries and run-level resume treat
-      // the failure as a transient network interruption.
+      // the failure as a transient network interruption. Classify on the bare
+      // message — the recorded `errorMessage` carries the cause chain.
       const isConnectionError =
         !timedOut &&
         statusCode === undefined &&
-        String(errorMessage).trim().toLowerCase() === "connection error.";
+        rawMessage.trim().toLowerCase() === "connection error.";
       if (statusCode === 401) {
         await recordProviderCredentialAuthFailure({
           key: "ANTHROPIC_API_KEY",

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

@@ -32,11 +32,19 @@ import {
   LLM_MISSING_CREDENTIALS_ERROR_CODE,
   LLM_MISSING_CREDENTIALS_MESSAGE,
 } from "./credential-errors.js";
+import { describeErrorWithCauses } from "./error-detail.js";
 import { FIRST_STREAM_EVENT_TIMEOUT_MS } from "./first-event-timeout.js";
 import { resolveMaxOutputTokensForEngine } from "./output-tokens.js";
 import {
+  splitSystemPromptForCache,
+  stablePrefixCacheControl,
+} from "./prompt-cache.js";
+import {
+  createStreamedToolInputState,
   engineMessagesToBuilderGatewayAnthropic,
   engineToolsToAnthropic,
+  finalizeStreamedToolInputs,
+  observeStreamedToolInput,
 } from "./translate-anthropic.js";
 import type {
   AgentEngine,
@@ -172,17 +180,23 @@ class BuilderEngine implements AgentEngine {
     const cacheEnabled =
       opts.providerOptions?.anthropic?.cacheControl !== false;
 
-    // System: wrap in array with cache_control when caching is on.
+    // System: split into a stable block carrying the breakpoint and a volatile
+    // tail (resources, app extras, model overlay, runtime context) without one,
+    // so mid-turn resource churn no longer invalidates system + tools.
+    const { stable, volatile } = splitSystemPromptForCache(
+      opts.systemPrompt ?? "",
+    );
     const systemValue: unknown = opts.systemPrompt
       ? cacheEnabled
         ? [
             {
               type: "text",
-              text: opts.systemPrompt,
-              cache_control: { type: "ephemeral" },
+              text: stable,
+              cache_control: stablePrefixCacheControl(),
             },
+            ...(volatile ? [{ type: "text", text: volatile }] : []),
           ]
-        : opts.systemPrompt
+        : stable + volatile
       : undefined;
 
     // Tools: add cache_control to the last tool definition.
@@ -190,12 +204,14 @@ class BuilderEngine implements AgentEngine {
     if (cacheEnabled && tools.length > 0) {
       cachedTools = [...tools];
       const last = { ...cachedTools[cachedTools.length - 1] } as any;
-      last.cache_control = { type: "ephemeral" };
+      last.cache_control = stablePrefixCacheControl();
       cachedTools[cachedTools.length - 1] = last;
     }
 
     // Messages: add a moving cache breakpoint on the last user message's last
-    // content block so the entire conversation prefix is cached.
+    // content block so the entire conversation prefix is cached. Stays on the
+    // default 5m TTL — it moves every iteration, so a longer-lived entry would
+    // only pay the higher write premium.
     let cachedMessages = messages;
     if (cacheEnabled && messages.length > 0) {
       let lastUserIdx = -1;
@@ -522,6 +538,27 @@ async function* parseJsonlStream(
     flushPendingThinking();
   };
 
+  const toolInputs = createStreamedToolInputState();
+
+  // The gateway can announce a tool call through `tool-call-delta` frames and
+  // then die before the terminal `tool-call` frame. Assemble what streamed, or
+  // hand the model an in-band error — never end the turn advertising a call
+  // that was silently dropped.
+  const recoverUndeliveredToolCalls = (): EngineEvent[] => {
+    const events = finalizeStreamedToolInputs(toolInputs);
+    for (const event of events) {
+      if (event.type === "tool-call") {
+        parts.push({
+          type: "tool-call",
+          id: event.id,
+          name: event.name,
+          input: event.input,
+        });
+      }
+    }
+    return events;
+  };
+
   try {
     for await (const line of readJsonlLines(
       reader,
@@ -574,8 +611,8 @@ async function* parseJsonlStream(
           break;
         }
 
-        case "tool-call-delta":
-          yield {
+        case "tool-call-delta": {
+          const delta: EngineEvent = {
             type: "tool-input-delta",
             id: event.id,
             name: event.name,
@@ -586,7 +623,10 @@ async function* parseJsonlStream(
                   ? event.delta
                   : "",
           };
+          observeStreamedToolInput(toolInputs, delta);
+          yield delta;
           break;
+        }
 
         case "heartbeat":
           yield { type: "gateway-heartbeat" };
@@ -594,18 +634,15 @@ async function* parseJsonlStream(
 
         case "tool-call": {
           flushPending();
-          parts.push({
-            type: "tool-call",
-            id: event.id,
-            name: event.name,
-            input: event.input,
-          });
-          yield {
-            type: "tool-call",
+          const call = {
+            type: "tool-call" as const,
             id: event.id,
             name: event.name,
             input: event.input,
           };
+          parts.push(call);
+          observeStreamedToolInput(toolInputs, call);
+          yield { ...call };
           break;
         }
 
@@ -626,6 +663,7 @@ async function* parseJsonlStream(
 
         case "stop": {
           flushPending();
+          yield* recoverUndeliveredToolCalls();
           yield { type: "assistant-content", parts };
 
           const reason = event.reason ?? "end_turn";
@@ -754,6 +792,7 @@ async function* parseJsonlStream(
 
     // Stream ended without a stop event — synthesize one so callers don't hang.
     flushPending();
+    yield* recoverUndeliveredToolCalls();
     yield { type: "assistant-content", parts };
     yield {
       type: "stop",
@@ -1060,8 +1099,7 @@ function formatTimeoutMs(timeoutMs: number): string {
 }
 
 function errorMessage(err: unknown): string {
-  if (err instanceof Error) return err.message;
-  return String(err);
+  return describeErrorWithCauses(err);
 }
 
 function errorSearchText(err: unknown): string {

package/src/agent/engine/continuation-dispatch-retry.ts

@@ -52,7 +52,6 @@ export async function attemptContinuationDispatch(params: {
 }> {
   const {
     event,
-    chainViaDurableBackground,
     backgroundContinuationCount,
     nextRunId,
     nextRowInserted,
@@ -127,14 +126,16 @@ export async function attemptContinuationDispatch(params: {
       dispatched = true;
     } catch (dispatchErr) {
       lastDispatchErr = dispatchErr;
-      // Regular-function targets (foreground self-chain) respond only
-      // after the successor chunk FINISHES, so an await timeout is not
-      // proof of a dead handoff. The successor's ATOMIC CLAIM is: a row
-      // that left `dispatch_mode='background'` (claimed) or is already
-      // terminal proves the handoff landed — stop retrying. A duplicate
-      // delivery would lose the claim and no-op anyway; skipping it saves
-      // wall-clock this close to the invocation deadline.
-      if (!chainViaDurableBackground && nextRowInserted) {
+      // A failed dispatch never proves a dead handoff, on ANY target: the
+      // request can land while the response is lost (observed in prod as a
+      // connection-level `fetch failed` against a background function that
+      // had already started the successor). The successor's ATOMIC CLAIM is
+      // authoritative — a row that left `dispatch_mode='background'`
+      // (claimed) or is already terminal means the handoff landed, so stop
+      // retrying. A duplicate delivery would lose the claim and no-op anyway;
+      // skipping it saves wall-clock this close to the invocation deadline
+      // and keeps the parent chunk from reporting a false `deferred`.
+      if (nextRowInserted) {
         const claim = await d
           .readBackgroundRunClaim(nextRunId)
           .catch(() => null);

package/src/agent/engine/credential-errors.ts

@@ -2,6 +2,14 @@ import { PROVIDER_ENV_VARS } from "./provider-env-vars.js";
 
 export const LLM_MISSING_CREDENTIALS_ERROR_CODE = "missing_credentials";
 
+/**
+ * Set by {@link ../../server/credential-provider.js CredentialStoreUnavailableError}
+ * when the credential store could not be read. Lives here so the classifier can
+ * recognize it without importing server-only code into the browser bundle.
+ */
+export const CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE =
+  "credential_store_unavailable";
+
 export const LLM_MISSING_CREDENTIALS_MESSAGE =
   "No LLM provider is connected. Open this app's Manage agent > LLM, then connect Builder.io or add a provider key.";
 
@@ -28,6 +36,9 @@ export function isLlmCredentialError(
       ? String((error as { errorCode?: unknown }).errorCode ?? "")
       : "");
   if (code === LLM_MISSING_CREDENTIALS_ERROR_CODE) return true;
+  // "We could not read the credential store" is a retryable failure, not a
+  // setup problem. Telling this user to connect a provider is the bug.
+  if (code === CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE) return false;
 
   const message = getErrorMessage(error);
   if (!message) return false;

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

@@ -0,0 +1,39 @@
+/**
+ * Compose an error's message with its `cause` chain.
+ *
+ * Provider SDKs collapse the real failure into a generic wrapper message —
+ * the Anthropic SDK reports every transport failure as exactly
+ * "Connection error." and undici reports "fetch failed" — and keep the actual
+ * reason (ECONNRESET, UND_ERR_SOCKET, TLS failure, request too large) only on
+ * `.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;
+
+export function describeErrorWithCauses(
+  err: unknown,
+  maxLinks: number = DEFAULT_MAX_CAUSE_LINKS,
+): string {
+  const head =
+    err instanceof Error ? err.message : String(err ?? "Unknown error");
+  const links: string[] = [];
+  const seen = new Set<unknown>([err]);
+  let cause: unknown = (err as { cause?: unknown } | null)?.cause;
+  while (cause !== undefined && cause !== null && links.length < maxLinks) {
+    if (seen.has(cause)) break;
+    seen.add(cause);
+    const code = (cause as { code?: unknown }).code;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const text = (typeof code === "string" ? `${code} ${message}` : message)
+      .trim()
+      .slice(0, MAX_CAUSE_LINK_CHARS);
+    if (text) links.push(text);
+    cause = (cause as { cause?: unknown }).cause;
+  }
+  return links.length > 0 ? `${head} (cause: ${links.join(" <- ")})` : head;
+}

package/src/agent/engine/prompt-cache.ts

@@ -0,0 +1,44 @@
+/**
+ * Sentinel marking the end of the cacheable STABLE system-prompt prefix.
+ *
+ * Zero-width on purpose: engines that do not split the system prompt forward
+ * it to the model verbatim, so anything visible here would leak into their
+ * rendered prompt.
+ */
+export const SYSTEM_PROMPT_CACHE_SPLIT = "\u200b";
+
+/**
+ * Split an assembled system prompt into the stable prefix (which carries the
+ * cache breakpoint) and the volatile remainder (resources, app extras, model
+ * overlay, runtime context). Without a sentinel the whole prompt is stable.
+ */
+export function splitSystemPromptForCache(systemPrompt: string): {
+  stable: string;
+  volatile: string;
+} {
+  const at = systemPrompt.indexOf(SYSTEM_PROMPT_CACHE_SPLIT);
+  if (at < 0) return { stable: systemPrompt, volatile: "" };
+  return {
+    stable: systemPrompt.slice(0, at),
+    volatile: systemPrompt.slice(at + SYSTEM_PROMPT_CACHE_SPLIT.length),
+  };
+}
+
+export type PromptCacheControl = { type: "ephemeral"; ttl?: "1h" };
+
+/**
+ * Cache control for the stable prefix (system prompt + tool definitions).
+ *
+ * Anthropic's default ephemeral entry lives 5 minutes. Measured hosted chunk
+ * boundaries sit ~6 minutes apart on average with a quarter of them past 5
+ * minutes, so the default expires between chunks and the whole prefix is
+ * re-written at full price. A 1h entry costs 2x to write and 0.1x to read,
+ * which can be useful for long hosted turns, but gateways may reject the
+ * newer `ttl` field. Opt into it explicitly with
+ * `AGENT_PROMPT_CACHE_TTL=1h`.
+ */
+export function stablePrefixCacheControl(): PromptCacheControl {
+  return process.env.AGENT_PROMPT_CACHE_TTL === "1h"
+    ? { type: "ephemeral", ttl: "1h" }
+    : { type: "ephemeral" };
+}

package/src/agent/engine/registry.ts

@@ -11,10 +11,11 @@
 import { createRequire } from "node:module";
 
 import {
+  assertCredentialStoreReadable,
   canUseDeployCredentialFallbackForRequest,
   getProviderCredentialAuthFailure,
   readDeployCredentialEnv,
-  resolveBuilderCredentials,
+  resolveBuilderCredentialsDetailed,
   resolveSecret,
 } from "../../server/credential-provider.js";
 import { getSetting } from "../../settings/store.js";
@@ -471,16 +472,12 @@ export async function detectEngineFromUserSecrets(): Promise<AgentEngineEntry |
   const hasAllKeys = async (entry: AgentEngineEntry): Promise<boolean> => {
     if (!isAgentEnginePackageInstalled(entry)) return false;
     if (entry.requiredEnvVars.length === 0) return false;
-    if (entry.name === "builder") {
-      const creds = await resolveBuilderCredentials();
-      return Boolean(creds.privateKey && creds.publicKey);
-    }
+    if (entry.name === "builder") return hasUsableBuilderConnection();
     for (const key of entry.requiredEnvVars) {
-      try {
-        if (!(await resolveUsableProviderSecret(key))) return false;
-      } catch {
-        return false;
-      }
+      // A throw here means the credential store could not be read. Let it
+      // propagate: swallowing it reports "no provider connected" to a user
+      // whose key is sitting in a row we simply failed to load.
+      if (!(await resolveUsableProviderSecret(key))) return false;
     }
     return true;
   };
@@ -583,6 +580,17 @@ async function resolveOpenAiBaseUrl(): Promise<string | undefined> {
   return raw ? normalizeOpenAiBaseUrl(raw) : undefined;
 }
 
+/**
+ * A Builder connection we could not read is not a missing connection. Throwing
+ * keeps that distinction instead of reporting "connect a provider" to a user
+ * whose org-shared keys exist but were unreadable.
+ */
+async function hasUsableBuilderConnection(): Promise<boolean> {
+  const creds = await resolveBuilderCredentialsDetailed();
+  assertCredentialStoreReadable(creds);
+  return Boolean(creds.privateKey && creds.publicKey);
+}
+
 async function resolveUsableProviderSecret(
   key: string,
 ): Promise<string | null> {
@@ -648,17 +656,9 @@ export async function isStoredEngineUsableForRequest(
   if (!isAgentEnginePackageInstalled(entry)) return false;
   if (isAgentEngineSettingConfigured(stored)) return true;
   if (entry.requiredEnvVars.length === 0) return true;
-  if (entry.name === "builder") {
-    const creds = await resolveBuilderCredentials();
-    return Boolean(creds.privateKey && creds.publicKey);
-  }
+  if (entry.name === "builder") return hasUsableBuilderConnection();
   for (const key of entry.requiredEnvVars) {
-    try {
-      if (await resolveUsableProviderSecret(key)) continue;
-    } catch {
-      return false;
-    }
-    return false;
+    if (!(await resolveUsableProviderSecret(key))) return false;
   }
   return true;
 }
@@ -680,10 +680,7 @@ export async function isResolvedEngineUsableForRequest(
   if (!isAgentEnginePackageInstalled(entry)) return false;
   if (entry.requiredEnvVars.length === 0) return true;
 
-  if (entry.name === "builder") {
-    const creds = await resolveBuilderCredentials();
-    return Boolean(creds.privateKey && creds.publicKey);
-  }
+  if (entry.name === "builder") return hasUsableBuilderConnection();
 
   if (options.apiKey?.trim()) {
     const key = entry.requiredEnvVars[0];
@@ -695,12 +692,7 @@ export async function isResolvedEngineUsableForRequest(
   }
 
   for (const key of entry.requiredEnvVars) {
-    try {
-      if (await resolveUsableProviderSecret(key)) continue;
-    } catch {
-      return false;
-    }
-    return false;
+    if (!(await resolveUsableProviderSecret(key))) return false;
   }
   return true;
 }