@agent-native/core 0.159.5 → 0.160.0

package/dist/agent/engine/credential-errors.d.ts

@@ -6,10 +6,33 @@ export declare const LLM_MISSING_CREDENTIALS_ERROR_CODE = "missing_credentials";
  */
 export declare const CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE = "credential_store_unavailable";
 export declare const LLM_MISSING_CREDENTIALS_MESSAGE = "No LLM provider is connected. Open this app's Manage agent > LLM, then connect Builder.io (free tier available) or add a provider key.";
+/**
+ * The one line a site visitor sees for every gateway rejection. Quota,
+ * concurrency, a revoked token, a disabled gateway and an unreadable credential
+ * store all read the same to someone with no account and no settings page.
+ */
+export declare const GATEWAY_UNAVAILABLE_VISITOR_MESSAGE = "AI features aren't available on this site right now.";
+/**
+ * Rewrite a gateway rejection for a visitor on a Builder-credits site: one
+ * message, and the real reason preserved on `errorCode` for the site owner, who
+ * is the only party who can act on it.
+ */
+export declare function gatewayVisitorFacingError(errorCode?: string): {
+    error: string;
+    errorCode?: string;
+};
 export declare function isLlmCredentialError(error: unknown, errorCode?: string | null): boolean;
 export declare function formatLlmCredentialErrorMessage(options?: {
     agentName?: string;
+    /**
+     * True when the reader is a visitor on a deployment that pays for its own AI:
+     * they have no Builder account, no Settings page and nothing to connect, so
+     * the owner-facing instructions name an action they cannot take. The real
+     * reason stays on the error code, which is where the owner reads it.
+     */
+    visitorFacing?: boolean;
 }): string;
 export declare function userFacingLlmCredentialError(error: unknown, options?: {
     agentName?: string;
+    visitorFacing?: boolean;
 }): string | null;

package/dist/agent/engine/credential-errors.js

@@ -7,6 +7,23 @@ export const LLM_MISSING_CREDENTIALS_ERROR_CODE = "missing_credentials";
  */
 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 (free tier available) or add a provider key.";
+/**
+ * The one line a site visitor sees for every gateway rejection. Quota,
+ * concurrency, a revoked token, a disabled gateway and an unreadable credential
+ * store all read the same to someone with no account and no settings page.
+ */
+export const GATEWAY_UNAVAILABLE_VISITOR_MESSAGE = "AI features aren't available on this site right now.";
+/**
+ * Rewrite a gateway rejection for a visitor on a Builder-credits site: one
+ * message, and the real reason preserved on `errorCode` for the site owner, who
+ * is the only party who can act on it.
+ */
+export function gatewayVisitorFacingError(errorCode) {
+    return {
+        error: GATEWAY_UNAVAILABLE_VISITOR_MESSAGE,
+        ...(errorCode ? { errorCode } : {}),
+    };
+}
 const LLM_CREDENTIAL_KEYS = new Set([
     ...PROVIDER_ENV_VARS,
     "BUILDER_PRIVATE_KEY",
@@ -38,6 +55,8 @@ export function isLlmCredentialError(error, errorCode) {
     return MISSING_CREDENTIAL_PATTERNS.some((pattern) => pattern.test(message));
 }
 export function formatLlmCredentialErrorMessage(options) {
+    if (options?.visitorFacing)
+        return GATEWAY_UNAVAILABLE_VISITOR_MESSAGE;
     const agentName = options?.agentName?.trim();
     if (agentName) {
         return `The ${agentName} agent could not finish this request because that app needs an LLM connection. Open ${agentName}'s Manage agent > LLM, then connect Builder.io (free tier available) or add a provider key.`;

package/dist/agent/engine/error-detail.d.ts

@@ -22,6 +22,21 @@ export declare function describeErrorWithCauses(err: unknown, maxLinks?: number)
 export declare function isProviderConnectionErrorMessage(message: string): boolean;
 /** `isProviderConnectionErrorMessage` over an error's full cause chain. */
 export declare function isProviderConnectionError(err: unknown): boolean;
+/**
+ * The single context-window-overflow classifier, shared by the layer that reads
+ * a provider's raw reply and the layer that decides to trim and retry.
+ *
+ * It lives here, beside the transport classifier, because the Builder gateway
+ * reports an overflow as an ordinary 400 `invalid_request_error` whose prose is
+ * the only carrier — and on a Builder-credits deployment that prose is replaced
+ * by one visitor line before any agent-level predicate sees it. The engine
+ * therefore runs this against the RAW reply and hands the verdict on as a
+ * structural field; `isContextTooLongError` (production-agent) keeps calling it
+ * for every other engine, which still delivers its own message intact.
+ */
+export declare function isContextOverflowMessage(message: string): boolean;
+/** The overflow codes a provider or gateway may report instead of prose. */
+export declare function isContextOverflowCode(code: string | undefined): boolean;
 /** Classification fields an AI SDK provider failure carries. */
 export interface ProviderErrorClassification {
     errorCode?: string;

package/dist/agent/engine/error-detail.js

@@ -60,6 +60,35 @@ export function isProviderConnectionErrorMessage(message) {
 export function isProviderConnectionError(err) {
     return isProviderConnectionErrorMessage(describeErrorWithCauses(err));
 }
+/**
+ * The single context-window-overflow classifier, shared by the layer that reads
+ * a provider's raw reply and the layer that decides to trim and retry.
+ *
+ * It lives here, beside the transport classifier, because the Builder gateway
+ * reports an overflow as an ordinary 400 `invalid_request_error` whose prose is
+ * the only carrier — and on a Builder-credits deployment that prose is replaced
+ * by one visitor line before any agent-level predicate sees it. The engine
+ * therefore runs this against the RAW reply and hands the verdict on as a
+ * structural field; `isContextTooLongError` (production-agent) keeps calling it
+ * for every other engine, which still delivers its own message intact.
+ */
+export function isContextOverflowMessage(message) {
+    const msg = message.toLowerCase();
+    return (msg.includes("context_length_exceeded") ||
+        msg.includes("input_too_long") ||
+        msg.includes("too many tokens") ||
+        msg.includes("prompt is too long") ||
+        msg.includes("reduce the length") ||
+        // Gemini phrasing
+        msg.includes("input token count exceeds") ||
+        msg.includes("request too large"));
+}
+/** The overflow codes a provider or gateway may report instead of prose. */
+export function isContextOverflowCode(code) {
+    const normalized = (code ?? "").toLowerCase();
+    return (normalized.includes("context_length") ||
+        normalized.includes("input_too_long"));
+}
 /**
  * Classify a provider error from the AI SDK, whichever way it surfaced.
  *

package/dist/agent/engine/registry.d.ts

@@ -9,6 +9,16 @@
  */
 import { type BuilderCredentialLookupIdentity } from "../../server/credential-provider.js";
 import type { AgentEngine, EngineCapabilities } from "./types.js";
+export interface AgentEngineEnvCredentialSet {
+    /** Every var here must resolve for the set to satisfy the engine. */
+    envVars: string[];
+    /**
+     * Injected by a deploy pipeline rather than configured by the owner. Selects
+     * when nothing else resolves, but never outranks an owner-configured
+     * credential — including the legacy Builder pair, which keeps normal priority.
+     */
+    deployInjected?: boolean;
+}
 export interface AgentEngineEntry {
     /** Unique name, e.g. "anthropic", "ai-sdk:anthropic", "ai-sdk:openai" */
     name: string;
@@ -26,6 +36,8 @@ export interface AgentEngineEntry {
     supportedModels: readonly string[];
     /** Environment variables required for this engine to work */
     requiredEnvVars: string[];
+    /** Alternative credential shapes; detection treats these and `requiredEnvVars` as OR. */
+    alternateRequiredEnvVars?: AgentEngineEnvCredentialSet[];
     /** Create an engine instance from config */
     create(config: Record<string, unknown>): AgentEngine;
 }
@@ -89,9 +101,8 @@ export declare function resolveDelegatedRunModel(engine: ModelResolvableEngine,
  */
 export declare function resolveEnginePreservesCustomModels(entry: Pick<AgentEngineEntry, "name">): Promise<boolean>;
 /**
- * First registered engine whose requiredEnvVars are all set. Registration
- * order controls priority — the Builder gateway is registered first so it
- * wins when the Builder private key is present.
+ * Registered engines whose env credentials are all set. Selection is
+ * {@link selectDetectedEngine}'s job.
  *
  * Escape hatch: AGENT_ENGINE_PREFER_BYO_KEY=true skips the Builder engine
  * on the first pass, so an explicit provider key (ANTHROPIC_API_KEY etc.)

package/dist/agent/engine/registry.js

@@ -9,7 +9,7 @@
  */
 import { createRequire } from "node:module";
 import { getAppConfig } from "../../app-config/index.js";
-import { assertCredentialStoreReadable, canUseDeployCredentialFallbackForRequest, getBuilderCredentialAuthFailure, getProviderCredentialAuthFailure, readDeployCredentialEnv, resolveBuilderCredentialsDetailed, resolveSecret, } from "../../server/credential-provider.js";
+import { assertCredentialStoreReadable, canUseDeployCredentialFallbackForRequest, getBuilderCredentialAuthFailure, getProviderCredentialAuthFailure, readDeployCredentialEnv, resolveBuilderCredentialsDetailed, resolveBuilderGatewayCredentialsDetailed, resolveSecret, } from "../../server/credential-provider.js";
 import { getSetting } from "../../settings/store.js";
 import { getAgentAppModelDefaultForCurrentRequest } from "../app-model-defaults.js";
 import { OLLAMA_BASE_URL_ENV_VAR, OPENAI_BASE_URL_ENV_VAR, } from "./openai-compatible-endpoint.js";
@@ -267,10 +267,35 @@ function assertAgentEnginePackageInstalled(entry) {
         : "";
     throw new Error(`[agent-engine] Engine "${entry.name}" requires optional packages that are not installed in this app.${installHint}`);
 }
+/** The single source both detectors read, so alternates cannot diverge between them. */
+function envCredentialSetsForEntry(entry) {
+    const sets = [];
+    if (entry.requiredEnvVars.length > 0) {
+        sets.push({ envVars: entry.requiredEnvVars, deployInjected: false });
+    }
+    for (const alternate of entry.alternateRequiredEnvVars ?? []) {
+        if (alternate.envVars.length > 0) {
+            sets.push({
+                envVars: alternate.envVars,
+                deployInjected: alternate.deployInjected === true,
+            });
+        }
+    }
+    return sets;
+}
+/**
+ * Registration order decides, except that an injected set loses to any
+ * owner-configured credential. Builder is registered first, so without that
+ * exception an injected token would move a BYO customer onto Builder credits.
+ */
+function selectDetectedEngine(matches) {
+    return (matches.find((match) => !match.deployInjected)?.entry ??
+        matches[0]?.entry ??
+        null);
+}
 /**
- * First registered engine whose requiredEnvVars are all set. Registration
- * order controls priority — the Builder gateway is registered first so it
- * wins when the Builder private key is present.
+ * Registered engines whose env credentials are all set. Selection is
+ * {@link selectDetectedEngine}'s job.
  *
  * Escape hatch: AGENT_ENGINE_PREFER_BYO_KEY=true skips the Builder engine
  * on the first pass, so an explicit provider key (ANTHROPIC_API_KEY etc.)
@@ -283,32 +308,22 @@ function assertAgentEnginePackageInstalled(entry) {
  */
 export function detectEngineFromEnv() {
     const preferByo = getAppConfig().agent.preferBringYourOwnKey;
-    if (preferByo) {
-        for (const entry of _registry.values()) {
-            if (entry.name === "builder")
-                continue;
-            if (entry.requiredEnvVars.length === 0)
-                continue;
-            if (!isAgentEnginePackageInstalled(entry))
-                continue;
-            if (entry.requiredEnvVars.every((v) => canUseDeployCredentialFallbackForRequest(v) &&
-                !!readDeployCredentialEnv(v))) {
-                return entry;
-            }
-        }
-        // No BYO key matched — fall through to include Builder as fallback.
-    }
+    const matches = [];
     for (const entry of _registry.values()) {
-        if (entry.requiredEnvVars.length === 0)
-            continue;
         if (!isAgentEnginePackageInstalled(entry))
             continue;
-        if (entry.requiredEnvVars.every((v) => canUseDeployCredentialFallbackForRequest(v) &&
-            !!readDeployCredentialEnv(v))) {
-            return entry;
-        }
+        const set = envCredentialSetsForEntry(entry).find((candidate) => candidate.envVars.every((v) => canUseDeployCredentialFallbackForRequest(v) &&
+            !!readDeployCredentialEnv(v)));
+        if (set)
+            matches.push({ entry, deployInjected: set.deployInjected });
     }
-    return null;
+    if (preferByo) {
+        const byo = matches.find((match) => match.entry.name !== "builder");
+        // No BYO key matched — fall through to include Builder as fallback.
+        if (byo)
+            return byo.entry;
+    }
+    return selectDetectedEngine(matches);
 }
 async function envKeyUsableForEntry(key) {
     if (!(canUseDeployCredentialFallbackForRequest(key) &&
@@ -320,16 +335,17 @@ async function envKeyUsableForEntry(key) {
         return false;
     return !(await getProviderCredentialAuthFailure({ key, value }));
 }
+const BUILDER_LEGACY_ENV_PAIR = ["BUILDER_PRIVATE_KEY", "BUILDER_PUBLIC_KEY"];
+function isBuilderLegacyEnvPair(envVars) {
+    return BUILDER_LEGACY_ENV_PAIR.every((key) => envVars.includes(key));
+}
 /**
- * Builder's deploy-env fallback is checked as a pair, not per-key: the
- * auth-failure marker is fingerprinted from privateKey+publicKey together
- * (see `builderCredentialFingerprint`), so a single-key lookup can never
- * match it. Without this, a rejected deploy-level Builder key would keep
- * reporting "usable" through this env-only path forever — the same class of
- * bug as the per-scope check in `credential-provider.ts`'s
- * `isCompleteBuilderConnection`.
+ * The legacy pair's marker is fingerprinted from both keys together, so the
+ * per-var lookup in {@link envKeyUsableForEntry} can never match it and a rejected
+ * pair would report "usable" forever. Selected by credential shape, not engine
+ * name: every other set carries a per-var marker already.
  */
-async function hasUsableBuilderEnvKeys() {
+async function hasUsableBuilderLegacyEnvPair() {
     const privateKey = canUseDeployCredentialFallbackForRequest("BUILDER_PRIVATE_KEY")
         ? readDeployCredentialEnv("BUILDER_PRIVATE_KEY")
         : null;
@@ -340,19 +356,31 @@ async function hasUsableBuilderEnvKeys() {
         return false;
     return !(await getBuilderCredentialAuthFailure({ privateKey, publicKey }));
 }
-async function hasUsableEnvKeys(entry) {
-    if (!isAgentEnginePackageInstalled(entry))
+async function isEnvCredentialSetUsable(set) {
+    // Every var in the set must resolve — the paired check answers only for the
+    // two legacy keys, so a set that carries them alongside anything else still
+    // owes the per-var check on the rest, exactly as `detectEngineFromEnv` does.
+    const pairedCheck = isBuilderLegacyEnvPair(set.envVars);
+    if (pairedCheck && !(await hasUsableBuilderLegacyEnvPair()))
         return false;
-    if (entry.requiredEnvVars.length === 0)
-        return false;
-    if (entry.name === "builder")
-        return hasUsableBuilderEnvKeys();
-    for (const key of entry.requiredEnvVars) {
+    for (const key of set.envVars) {
+        if (pairedCheck && BUILDER_LEGACY_ENV_PAIR.includes(key))
+            continue;
         if (!(await envKeyUsableForEntry(key)))
             return false;
     }
     return true;
 }
+async function usableEnvCredentialMatch(entry) {
+    if (!isAgentEnginePackageInstalled(entry))
+        return null;
+    for (const set of envCredentialSetsForEntry(entry)) {
+        if (await isEnvCredentialSetUsable(set)) {
+            return { entry, deployInjected: set.deployInjected };
+        }
+    }
+    return null;
+}
 /**
  * Request-aware env auto-detect. Same priority as {@link detectEngineFromEnv},
  * but skips provider keys that currently have an auth-failure marker so a
@@ -361,19 +389,18 @@ async function hasUsableEnvKeys(entry) {
  */
 export async function detectEngineFromEnvForRequest() {
     const preferByo = getAppConfig().agent.preferBringYourOwnKey;
-    if (preferByo) {
-        for (const entry of _registry.values()) {
-            if (entry.name === "builder")
-                continue;
-            if (await hasUsableEnvKeys(entry))
-                return entry;
-        }
-    }
+    const matches = [];
     for (const entry of _registry.values()) {
-        if (await hasUsableEnvKeys(entry))
-            return entry;
+        const match = await usableEnvCredentialMatch(entry);
+        if (match)
+            matches.push(match);
     }
-    return null;
+    if (preferByo) {
+        const byo = matches.find((match) => match.entry.name !== "builder");
+        if (byo)
+            return byo.entry;
+    }
+    return selectDetectedEngine(matches);
 }
 function shouldTraceEngineDetection() {
     return /^(1|true)$/i.test(process.env.AGENT_NATIVE_DEBUG_AGENT_ENGINE_DETECT ??
@@ -533,6 +560,15 @@ async function hasUsableBuilderConnection(identity) {
     assertCredentialStoreReadable(creds);
     return Boolean(creds.privateKey && creds.publicKey);
 }
+/**
+ * Either lane. Not {@link hasUsableBuilderConnection}, which asks the narrower
+ * "did this user connect Builder" and is false on every credits-only site.
+ */
+async function canRunBuilderEngine(identity) {
+    const creds = await resolveBuilderGatewayCredentialsDetailed(identity);
+    assertCredentialStoreReadable(creds);
+    return Boolean(creds.privateKey && creds.publicKey);
+}
 async function resolveUsableProviderSecret(key) {
     const value = await resolveSecret(key);
     if (!value)
@@ -647,11 +683,11 @@ async function engineCreateConfigForEntry(entry, apiKey, extra, credentialResolu
     }
     if (entry.name === "builder" &&
         (credentialIdentity !== undefined || safeExtra.credentials == null)) {
-        // Builder authentication is a private/public key pair, not the single
-        // provider key carried by ResolveEngineConfig. Capture the scoped pair
-        // while the verified request identity is available so a later stream or
-        // detached run cannot resolve credentials from the wrong ambient context.
-        const creds = await resolveBuilderCredentialsDetailed(credentialIdentity);
+        // Builder authentication is a token plus space id, not the single provider
+        // key carried by ResolveEngineConfig. Capture the gateway-lane pair while
+        // the verified request identity is available so a later stream or detached
+        // run cannot resolve credentials from the wrong ambient context.
+        const creds = await resolveBuilderGatewayCredentialsDetailed(credentialIdentity);
         assertCredentialStoreReadable(creds);
         if (credentialIdentity !== undefined ||
             creds.source !== null ||
@@ -661,6 +697,7 @@ async function engineCreateConfigForEntry(entry, apiKey, extra, credentialResolu
                 publicKey: creds.publicKey,
                 userId: creds.userId,
                 orgName: creds.orgName,
+                lane: creds.lane,
             };
         }
     }
@@ -682,8 +719,16 @@ export function isStoredEngineUsable(stored, entry) {
         return true;
     if (entry.requiredEnvVars.length === 0)
         return true;
-    return entry.requiredEnvVars.every((v) => canUseDeployCredentialFallbackForRequest(v) &&
-        !!readDeployCredentialEnv(v));
+    // Every credential set, not just `requiredEnvVars`. Reading only the latter
+    // reports a Builder engine running on the injected gateway pair as
+    // unconfigured, which the engine-status endpoint surfaces as "no provider" and
+    // the composer refuses to start on — while the request path, which does read
+    // the alternates, runs the same engine perfectly well.
+    const sets = envCredentialSetsForEntry(entry);
+    if (sets.length === 0)
+        return true;
+    return sets.some((set) => set.envVars.every((v) => canUseDeployCredentialFallbackForRequest(v) &&
+        !!readDeployCredentialEnv(v)));
 }
 /**
  * Request-aware version of `isStoredEngineUsable`.
@@ -701,7 +746,7 @@ export async function isStoredEngineUsableForRequest(stored, entry, options = {}
     if (entry.requiredEnvVars.length === 0)
         return true;
     if (entry.name === "builder") {
-        return hasUsableBuilderConnection(options.credentialIdentity);
+        return canRunBuilderEngine(options.credentialIdentity);
     }
     for (const key of entry.requiredEnvVars) {
         if (!(await resolveUsableProviderSecret(key)))
@@ -726,7 +771,7 @@ export async function isResolvedEngineUsableForRequest(engine, options = {}) {
     if (entry.requiredEnvVars.length === 0)
         return true;
     if (entry.name === "builder") {
-        return hasUsableBuilderConnection(options.credentialIdentity);
+        return canRunBuilderEngine(options.credentialIdentity);
     }
     if (options.apiKey?.trim()) {
         const key = entry.requiredEnvVars[0];

package/dist/agent/engine/types.d.ts

@@ -26,11 +26,20 @@ export declare class EngineError extends Error {
     readonly statusCode?: number;
     /** Whether the provider explicitly marked this error as retryable. */
     readonly providerRetryable?: boolean;
+    /**
+     * Whether the request exceeded the model's context window. Set by engines that
+     * classified the provider's own reply, because the delivered message may not
+     * be that reply: a Builder-credits deployment replaces it with one visitor
+     * line, which leaves `isContextTooLongError` nothing to match and kills the
+     * one-shot trim-and-retry recovery.
+     */
+    readonly contextOverflow?: boolean;
     constructor(message: string, opts?: {
         errorCode?: string;
         upgradeUrl?: string;
         statusCode?: number;
         providerRetryable?: boolean;
+        contextOverflow?: boolean;
     });
 }
 /**
@@ -187,6 +196,13 @@ export type EngineEvent = {
      * should retry even if status code / message patterns don't match.
      */
     providerRetryable?: boolean;
+    /**
+     * The request exceeded the model's context window. Carried structurally
+     * for the same reason as `providerRetryable`: `error` is visitor copy on a
+     * Builder-credits deployment, so a verdict left in the prose is gone by
+     * the time the agent decides whether to trim and retry.
+     */
+    contextOverflow?: boolean;
 };
 export interface EngineCapabilities {
     /** Extended / adaptive thinking support */

package/dist/agent/engine/types.js

@@ -25,6 +25,14 @@ export class EngineError extends Error {
     statusCode;
     /** Whether the provider explicitly marked this error as retryable. */
     providerRetryable;
+    /**
+     * Whether the request exceeded the model's context window. Set by engines that
+     * classified the provider's own reply, because the delivered message may not
+     * be that reply: a Builder-credits deployment replaces it with one visitor
+     * line, which leaves `isContextTooLongError` nothing to match and kills the
+     * one-shot trim-and-retry recovery.
+     */
+    contextOverflow;
     constructor(message, opts) {
         super(message);
         this.name = "EngineError";
@@ -32,5 +40,6 @@ export class EngineError extends Error {
         this.upgradeUrl = opts?.upgradeUrl;
         this.statusCode = opts?.statusCode;
         this.providerRetryable = opts?.providerRetryable;
+        this.contextOverflow = opts?.contextOverflow;
     }
 }

package/dist/agent/production-agent.d.ts

@@ -889,6 +889,13 @@ export declare function runAgentLoop(opts: {
      */
     processors?: Processor[];
 }): Promise<AgentLoopUsage>;
+/** @internal exported for unit tests only */
+export declare function isRecoverableContinuationError(event: {
+    type: "error";
+    error: string;
+    errorCode?: string;
+    recoverable?: boolean;
+}): boolean;
 export declare function lastUnfinishedPreparingActionToolFromEvents(events: readonly AgentChatEvent[]): string | undefined;
 export declare function backgroundContinuationReasonForRun(run: ActiveRun): AgentLoopContinuationReason;
 export declare function runAgentLoopWithMainChatInternalContinuations(opts: Parameters<typeof runAgentLoop>[0] & {