@agent-native/core 0.145.1 → 0.145.2

package/dist/notifications/routes.d.ts

@@ -13,13 +13,13 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
 } | {
     count?: undefined;
     updated?: undefined;

package/dist/observability/routes.d.ts

@@ -41,16 +41,16 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
+    error?: undefined;
     ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
+    error?: undefined;
     ok?: undefined;
 } | {
     summary?: undefined;
@@ -59,9 +59,9 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     error: any;
     ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/agent-chat-plugin.js

@@ -11,6 +11,7 @@ import { DEFAULT_ANTHROPIC_MODEL } from "../agent/default-model.js";
 import { AGENT_CHAT_BACKGROUND_RUN_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, backgroundRunMarkerExpectsBackgroundRuntime, isInBackgroundFunctionRuntime, prepareProcessRunRequest, } from "../agent/durable-background.js";
 import { resolveEngine, createAnthropicEngine, getStoredModelForEngine, normalizeModelForEngine, resolveDelegatedRunModel, getAgentEngineEntry, isAgentEnginePackageInstalled, isStoredEngineUsableForRequest, listAgentEngines, registerBuiltinEngines, } from "../agent/engine/index.js";
 import { SYSTEM_PROMPT_CACHE_SPLIT } from "../agent/engine/prompt-cache.js";
+import { PROVIDER_TO_ENV } from "../agent/engine/provider-env-vars.js";
 import { createProductionAgentHandler, actionsToEngineTools, executeAgentToolCall, toolCallCacheKey, getActiveRunForThreadAsync, abortRunDurably, abortTurnDurably, subscribeToRun, } from "../agent/production-agent.js";
 import { callerHasRunAccess, callerHasThreadAccess, } from "../agent/run-ownership.js";
 import { markTurnAborted, readBackgroundRunClaim } from "../agent/run-store.js";
@@ -1240,8 +1241,12 @@ export function createAgentChatPlugin(options) {
                     }
                     // Use the SAME agent setup as the interactive chat — identical tools,
                     // prompt, and capabilities. The A2A agent IS the app's agent.
-                    const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
-                    const ownerApiKey = await getOwnerActiveApiKey(userEmail);
+                    const { resolveOwnerEngineApiKey } = await import("../agent/production-agent.js");
+                    const { apiKey: ownerApiKey, apiKeyEnvVar: ownerApiKeyEnvVar } = await resolveOwnerEngineApiKey({
+                        engineOption: options?.engine,
+                        ownerEmail: userEmail,
+                        anthropicFallback: options?.apiKey,
+                    });
                     // A2A runs are reconstructed in a fresh processor request, so they
                     // do not pass through the interactive handler's prepareRun hook.
                     // Seed the same mutable run context before resolving the engine and
@@ -1254,6 +1259,7 @@ export function createAgentChatPlugin(options) {
                     if (a2aRunContext) {
                         a2aRunContext.owner = userEmail;
                         a2aRunContext.userApiKey = ownerApiKey;
+                        a2aRunContext.userApiKeyEnvVar = ownerApiKeyEnvVar;
                         // The async processor restores the original request origin from
                         // task metadata. Only derive a fallback for synchronous A2A calls
                         // where the inbound event is still the caller request.
@@ -1274,7 +1280,8 @@ export function createAgentChatPlugin(options) {
                     }
                     const a2aEngine = await resolveEngine({
                         engineOption: options?.engine,
-                        apiKey: ownerApiKey ?? options?.apiKey,
+                        apiKey: ownerApiKey,
+                        apiKeyEnvVar: ownerApiKeyEnvVar,
                         appId: options?.appId,
                     });
                     const devActive = isDevMode();
@@ -1684,13 +1691,27 @@ export function createAgentChatPlugin(options) {
                     askAgent: async (message) => {
                         const ownerEmail = getRequestUserEmail();
                         const mcpRunId = crypto.randomUUID();
-                        const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
-                        const ownerApiKey = ownerEmail
-                            ? await getOwnerActiveApiKey(ownerEmail)
-                            : undefined;
+                        const { resolveOwnerEngineApiKey } = await import("../agent/production-agent.js");
+                        const ownerApiKey = await resolveOwnerEngineApiKey({
+                            engineOption: options?.engine,
+                            ownerEmail,
+                            anthropicFallback: options?.apiKey,
+                        });
+                        // `ask_app` runs outside the interactive handler, so nothing seeds
+                        // the run context for it — and `onEngineResolved` never fires on
+                        // this path either. Without the resolved key and its provenance
+                        // here, an agent-team sub-agent spawned from an MCP run falls back
+                        // to the plugin host key while the parent bills the owner's BYO
+                        // credential. Same reason the A2A branch above seeds it.
+                        const mcpRunContext = ensureRequestRunContext();
+                        if (mcpRunContext) {
+                            mcpRunContext.userApiKey = ownerApiKey.apiKey;
+                            mcpRunContext.userApiKeyEnvVar = ownerApiKey.apiKeyEnvVar;
+                        }
                         const mcpEngine = await resolveEngine({
                             engineOption: options?.engine,
-                            apiKey: ownerApiKey ?? options?.apiKey,
+                            apiKey: ownerApiKey.apiKey,
+                            apiKeyEnvVar: ownerApiKey.apiKeyEnvVar,
                             appId: options?.appId,
                         });
                         const mcpModelCandidate = options?.model ??
@@ -2180,12 +2201,19 @@ export function createAgentChatPlugin(options) {
                 getActions: buildSubAgentActions,
                 getEngine: () => {
                     const runCtx = getRequestRunContext();
+                    // Sub-agents must inherit the parent run's resolved key so
+                    // delegations spawned by agent-teams don't silently fall back to
+                    // the platform key while the parent uses BYO credentials. This
+                    // fallback engine is Anthropic, so a key the parent resolved for
+                    // another provider is not inheritable — passing it anyway sends a
+                    // live OpenAI/Gemini secret to Anthropic's endpoint.
+                    const inheritableKey = runCtx?.userApiKeyEnvVar === undefined ||
+                        runCtx.userApiKeyEnvVar === "ANTHROPIC_API_KEY"
+                        ? runCtx?.userApiKey
+                        : undefined;
                     return (runCtx?.engine ??
                         createAnthropicEngine({
-                            // Sub-agents must inherit the parent run's resolved key so
-                            // delegations spawned by agent-teams don't silently fall back
-                            // to the platform key while the parent uses BYO credentials.
-                            apiKey: runCtx?.userApiKey ?? options?.apiKey,
+                            apiKey: inheritableKey ?? options?.apiKey,
                         }));
                 },
                 getModel: () => getRequestRunContext()?.model ?? resolvedModel,
@@ -2342,13 +2370,17 @@ export function createAgentChatPlugin(options) {
             // content is what the token-saving modes strip.
             const prepareRun = async (event) => {
                 const owner = await getOwnerFromEvent(event);
-                const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
-                const userApiKey = await getOwnerActiveApiKey(owner);
+                const { resolveOwnerEngineApiKey } = await import("../agent/production-agent.js");
+                const userApiKey = await resolveOwnerEngineApiKey({
+                    engineOption: options?.engine,
+                    ownerEmail: owner,
+                });
                 const runCtx = ensureRequestRunContext();
                 if (runCtx) {
                     runCtx.requestOrigin = getOrigin(event);
                     runCtx.owner = owner;
-                    runCtx.userApiKey = userApiKey;
+                    runCtx.userApiKey = userApiKey.apiKey;
+                    runCtx.userApiKeyEnvVar = userApiKey.apiKeyEnvVar;
                 }
                 const extra = await resolveExtraContext(event, owner);
                 return { owner, extra };
@@ -2938,21 +2970,28 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         resolveConfig: async ({ payload, ownerEmail, orgId: _orgId }) => {
                             // Resolve the owner's API key so BYO-key sub-agents use the
                             // same credentials as the parent chat.
-                            let apiKey;
+                            let resolvedKey = {
+                                apiKey: undefined,
+                                apiKeyEnvVar: undefined,
+                            };
                             try {
-                                const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
-                                apiKey =
-                                    (await getOwnerActiveApiKey(ownerEmail)) ?? undefined;
+                                const { resolveOwnerEngineApiKey } = await import("../agent/production-agent.js");
+                                resolvedKey = await resolveOwnerEngineApiKey({
+                                    engineOption: options?.engine,
+                                    ownerEmail,
+                                    anthropicFallback: options?.apiKey,
+                                });
                             }
                             catch {
-                                apiKey = undefined;
+                                resolvedKey = { apiKey: undefined, apiKeyEnvVar: undefined };
                             }
                             // Use the same resolveEngine path as the A2A and MCP
                             // processors so Builder-gateway/OpenAI users get their
                             // configured engine instead of always hitting the Anthropic SDK.
                             const engine = await resolveEngine({
                                 engineOption: options?.engine,
-                                apiKey: apiKey ?? options?.apiKey,
+                                apiKey: resolvedKey.apiKey,
+                                apiKeyEnvVar: resolvedKey.apiKeyEnvVar,
                                 appId: options?.appId,
                             });
                             const modelCandidate = payload.model ??
@@ -3148,15 +3187,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     setResponseStatus(event, 401);
                     return { error: "Authentication required" };
                 }
-                const providerToEnv = {
-                    anthropic: "ANTHROPIC_API_KEY",
-                    openai: "OPENAI_API_KEY",
-                    google: "GOOGLE_GENERATIVE_AI_API_KEY",
-                    groq: "GROQ_API_KEY",
-                    mistral: "MISTRAL_API_KEY",
-                    cohere: "COHERE_API_KEY",
-                };
-                const secretKey = providerToEnv[provider] ?? `${provider.toUpperCase()}_API_KEY`;
+                const secretKey = PROVIDER_TO_ENV[provider] ?? `${provider.toUpperCase()}_API_KEY`;
                 try {
                     const { writeAppSecret } = await import("../secrets/storage.js");
                     await writeAppSecret({
@@ -3686,9 +3717,12 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     .trim();
                 // Mirror the chat-run resolution so BYO-key users have title
                 // generation billed to their own key instead of the platform key.
-                const { getOwnerActiveApiKey } = await import("../agent/production-agent.js");
-                const userApiKey = await getOwnerActiveApiKey(ownerEmail);
-                const apiKey = userApiKey;
+                // This request goes straight to Anthropic, so it needs the owner's
+                // Anthropic key specifically — the active engine may be another
+                // provider, whose key must never be sent here. Owners without one
+                // get the truncated title.
+                const { getOwnerApiKeyForEngine } = await import("../agent/production-agent.js");
+                const { apiKey } = await getOwnerApiKeyForEngine("anthropic", ownerEmail);
                 if (!apiKey) {
                     // Fallback: truncate the message
                     return { title: cleanMessage.trim().slice(0, 60) };

package/dist/server/complete-text.js

@@ -1,6 +1,6 @@
 import { getStoredModelForEngine, normalizeModelForEngine, registerBuiltinEngines, resolveEngine, } from "../agent/engine/index.js";
 import { EngineError } from "../agent/engine/types.js";
-import { getOwnerActiveApiKey } from "../agent/production-agent.js";
+import { resolveOwnerEngineApiKey, } from "../agent/production-agent.js";
 import { getRequestUserEmail } from "./request-context.js";
 function normalizeCompleteTextMessages(messages, input) {
     const normalized = [];
@@ -56,14 +56,20 @@ function createCompletionAbortSignal(signal, timeoutMs) {
         },
     };
 }
-async function resolveCompletionApiKey(explicitApiKey) {
-    if (explicitApiKey)
-        return explicitApiKey;
+async function resolveCompletionApiKey(options) {
+    // A caller-supplied key is opaque: `CompleteTextOptions.apiKey` names no
+    // provider, so it keeps the caller's contract and is passed through untagged.
+    if (options.apiKey) {
+        return { apiKey: options.apiKey, apiKeyEnvVar: undefined };
+    }
     try {
-        return await getOwnerActiveApiKey(getRequestUserEmail());
+        return await resolveOwnerEngineApiKey({
+            engineOption: options.engine,
+            ownerEmail: getRequestUserEmail(),
+        });
     }
     catch {
-        return undefined;
+        return { apiKey: undefined, apiKeyEnvVar: undefined };
     }
 }
 /**
@@ -75,10 +81,11 @@ async function resolveCompletionApiKey(explicitApiKey) {
  */
 export async function completeText(options) {
     registerBuiltinEngines();
-    const apiKey = await resolveCompletionApiKey(options.apiKey);
+    const { apiKey, apiKeyEnvVar } = await resolveCompletionApiKey(options);
     const engine = await resolveEngine({
         engineOption: options.engine,
         apiKey,
+        apiKeyEnvVar,
         model: options.model,
         appId: options.appId,
     });

package/dist/server/index.d.ts

@@ -14,7 +14,7 @@ export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } fro
 export { verifyCaptcha, type CaptchaVerifyResult } from "./captcha.js";
 export { getLocaleInitScript, parseAcceptLanguage, resolveLocaleFromRequest, type LocaleInitScriptOptions, type ResolveLocaleFromRequestOptions, type ResolvedRequestLocale, } from "../localization/server.js";
 export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "../agent/index.js";
-export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, runAgentLoop, type AgentToolCallExecutionResult, type ExecuteAgentToolCallOptions, } from "../agent/production-agent.js";
+export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, getOwnerApiKeyForEngine, resolveOwnerEngineApiKey, runAgentLoop, type AgentToolCallExecutionResult, type ExecuteAgentToolCallOptions, type ResolvedOwnerApiKey, } from "../agent/production-agent.js";
 export { mountRealtimeVoiceRoutes, realtimeVoiceSafetyIdentifier, REALTIME_VOICE_MAX_SDP_BYTES, REALTIME_VOICE_MAX_TOOL_BODY_BYTES, REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS, REALTIME_VOICE_SESSION_PATH, REALTIME_VOICE_TOOL_PATH, type MountRealtimeVoiceRoutesOptions, type RealtimeVoiceRequestContext, type RealtimeVoiceToolExecutionRequest, type RealtimeVoiceToolExecutionResult, } from "./realtime-voice.js";
 export { getStoredModelForEngine, resolveEngine, } from "../agent/engine/index.js";
 export { completeText, type CompleteTextMessage, type CompleteTextOptions, type CompleteTextResult, type CompleteTextUsage, } from "./complete-text.js";

package/dist/server/index.js

@@ -14,7 +14,7 @@ export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } fro
 export { verifyCaptcha } from "./captcha.js";
 export { getLocaleInitScript, parseAcceptLanguage, resolveLocaleFromRequest, } from "../localization/server.js";
 export { createProductionAgentHandler, } from "../agent/index.js";
-export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, runAgentLoop, } from "../agent/production-agent.js";
+export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, getOwnerApiKeyForEngine, resolveOwnerEngineApiKey, runAgentLoop, } from "../agent/production-agent.js";
 export { mountRealtimeVoiceRoutes, realtimeVoiceSafetyIdentifier, REALTIME_VOICE_MAX_SDP_BYTES, REALTIME_VOICE_MAX_TOOL_BODY_BYTES, REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS, REALTIME_VOICE_SESSION_PATH, REALTIME_VOICE_TOOL_PATH, } from "./realtime-voice.js";
 export { getStoredModelForEngine, resolveEngine, } from "../agent/engine/index.js";
 export { completeText, } from "./complete-text.js";

package/dist/server/request-context.d.ts

@@ -41,8 +41,14 @@ export interface RequestRunContext {
     } | null;
     /** Resolved owner email (set by prepareRun). */
     owner?: string;
-    /** Owner's active Anthropic API key (set by prepareRun). */
+    /** Owner's API key for this run's engine (set by prepareRun). */
     userApiKey?: string;
+    /**
+     * Env var `userApiKey` was issued for. Anything that hands the key to a
+     * fixed provider must check this first — the owner's active engine is not
+     * always Anthropic, and an unchecked key reaches the wrong endpoint.
+     */
+    userApiKeyEnvVar?: string;
     /** Thread ID for the current run (set by onRunStart). */
     threadId?: string;
     /** Run ID for the current run (set by onRunStart). */

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;

package/docs/content/environment-variables.mdx

@@ -40,6 +40,8 @@ deployment-specific values in the environment or scoped secret store.
 | `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Stable encryption key for a workspace-shared secrets vault.                                     | The same stable key in every app that reads the vault.                                                         |
 | `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Previous workspace key during rotation.                                                         | The old key only; remove it after migration.                                                                   |
 | `ANTHROPIC_API_KEY`                         | Optional deploy-level fallback for the embedded production agent.                               | An API key; prefer scoped credentials for multi-tenant apps.                                                   |
+| `AGENT_ENGINE`                              | Explicitly selects the agent engine instead of auto-detecting from provider keys.               | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                      |
+| `AGENT_ENGINE_PREFER_BYO_KEY`               | Prefers a provider key you set over the managed Builder gateway during auto-detection.          | `true` or `1`; Builder still applies as the fallback when no provider key is set.                              |
 | `AUTH_MODE`                                 | Selects the local authentication behavior used by CLI and agent flows.                          | Unset or `local`; this is not a browser login bypass.                                                          |
 | `AUTH_DISABLED`                             | Disables auth for local or preview-only work.                                                   | `true` or `1`; never use on a public production app.                                                           |
 | `AUTH_MAGIC_LINK`                           | Controls the password-first versus magic-link sign-in path.                                     | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links.               |
@@ -95,8 +97,12 @@ specific Google API integrations; they are not required for browser sign-in.
 These are deploy-level fallbacks for single-tenant or local use. Hosted,
 multi-user apps should prefer the scoped credential and connection store.
 
+Every provider key below selects its engine on its own: dropping one in is
+enough, and `AGENT_ENGINE` is only needed to pick between several.
+
 | Variable                       | What it controls                                         | Supported values or format                              |
 | ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`            | Claude model fallback for the built-in AI engine.        | An Anthropic API key.                                   |
 | `OPENAI_API_KEY`               | OpenAI model, realtime voice, or transcription fallback. | An OpenAI API key.                                      |
 | `OPENAI_BASE_URL`              | OpenAI-compatible endpoint used with `OPENAI_API_KEY`.   | An absolute `http(s)` URL without embedded credentials. |
 | `GOOGLE_GENERATIVE_AI_API_KEY` | Gemini model fallback for the built-in AI engine.        | A Google AI API key.                                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.1",
+  "version": "0.145.2",
   "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": {
@@ -412,8 +412,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "^0.13.3",
-    "@agent-native/recap-cli": "0.5.3"
+    "@agent-native/recap-cli": "0.5.3",
+    "@agent-native/toolkit": "^0.13.3"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",