@agent-native/core 0.169.1 → 0.170.0

package/dist/server/agent-chat/action-filters-a2a.js

@@ -1,6 +1,7 @@
 import { getHeader } from "h3";
 import { appendA2AArtifactLinks, extractA2APersistedMutationReceipts, } from "../../a2a/artifact-response.js";
 import { collectFinalResponseTextFromAgentEvents } from "../../a2a/response-text.js";
+import { isActionExposedToExternalAgents } from "../../action.js";
 import { resolveMainChatMaxOutputTokens } from "../../agent/engine/output-tokens.js";
 import { filterInitialEngineTools, resolveAgentRequestReasoningEffort, } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
@@ -25,6 +26,20 @@ export function filterReadOnlyActions(actions) {
 export function filterAgentTools(actions) {
     return Object.fromEntries(Object.entries(actions).filter(([, entry]) => entry.agentTool !== false));
 }
+/**
+ * The MCP-only actions: `agentTool: false` paired with an explicit
+ * `mcpTool: true`.
+ *
+ * `filterAgentTools` drops these, which is right for every in-app surface and
+ * wrong for the two external ones. Rather than have the MCP and A2A mounts
+ * read the unfiltered registry — and re-derive which agent-hidden actions are
+ * safe to serve — the plugin re-merges exactly this set into those two mounts.
+ * A caller that wants "everything external" merges this with the agent surface;
+ * nobody has to remember which raw fields make an action MCP-only.
+ */
+export function filterMcpOnlyActions(actions) {
+    return Object.fromEntries(Object.entries(actions).filter(([, entry]) => entry.agentTool === false && entry.mcpTool === true));
+}
 export function filterPublicAgentActions(actions) {
     return Object.fromEntries(Object.entries(actions).filter(([, entry]) => {
         const config = entry.publicAgent;
@@ -80,7 +95,10 @@ export function filterDirectA2AActions(actions, options) {
     const autoReads = options.externalAgents?.authenticatedReads === "auto";
     return Object.fromEntries(Object.entries(actions).filter(([name, entry]) => {
         const exposure = entry.publicAgent;
-        const selected = catalog.has(name) ||
+        // `mcpTool: true` is catalog membership declared beside the action; the
+        // exposure resolver below is the veto no config list can re-open.
+        const selected = entry.mcpTool === true ||
+            catalog.has(name) ||
             (autoReads &&
                 isAuthenticatedReadAction(entry) &&
                 !isAutoReadExcludedActionName(name));
@@ -88,7 +106,7 @@ export function filterDirectA2AActions(actions, options) {
         return (selected &&
             rawQueryAllowed &&
             !denied.has(name) &&
-            entry.agentTool !== false &&
+            isActionExposedToExternalAgents(entry) &&
             entry.readOnly === true &&
             exposure?.expose === true &&
             exposure.readOnly === true &&
@@ -108,7 +126,7 @@ export function filterDelegatedA2ACapabilityActions(actions, options) {
     return Object.fromEntries(Object.entries(actions).filter(([name, entry]) => {
         const exposure = entry.publicAgent;
         return (!denied.has(name) &&
-            entry.agentTool !== false &&
+            isActionExposedToExternalAgents(entry) &&
             entry.readOnly !== true &&
             exposure?.expose === true &&
             exposure.readOnly === false &&
@@ -463,20 +481,41 @@ The caller already selected this app to own the current objective. Start with th
 </selected-a2a-receiver>`;
 }
 /**
- * The first-request tool catalog: an explicit `initialToolNames` verbatim, or
- * the app's OWN actions by default.
+ * The first-request tool catalog, in precedence order:
+ *
+ *  1. An explicit `initialToolNames`, plus every action that declares
+ *     `deferLoading: false`. The configured list stays authoritative — an
+ *     action it names is never dropped by a `deferLoading: true` — so a
+ *     template can annotate its actions before deleting the array, not after.
+ *  2. Otherwise, the actions that declared `deferLoading: false`, if any did.
+ *  3. Otherwise, the app's OWN actions, minus any marked `deferLoading: true`.
+ *
+ * Step 2 is what makes `deferLoading` a replacement for the array rather than
+ * a second copy of it: opting a few starter actions out of deferral on an app
+ * with no configured list defers everything else, instead of leaving the whole
+ * registry in and the annotation decorative.
  *
  * "Its own actions" excludes the framework kits. They arrive in this same
  * registry through `autoDiscoverActions` -> `mergeCoreSharingActions`, so the
  * plain `Object.keys` default promoted ~45 sharing/review/history/flag schemas
  * into every app's first request whether or not the app had those surfaces. They
  * remain in `availableTools` and are still found by `tool-search`; an app that
- * wants one on turn one names it in `initialToolNames`.
+ * wants one on turn one sets `deferLoading: false` or names it in
+ * `initialToolNames`.
  */
 export function resolveInitialToolNames(templateActions, configured) {
+    const entries = Object.entries(templateActions);
+    // A framework-grouped action stays out of the DERIVED set, but an explicit
+    // `deferLoading: false` on one is a declaration, not a leak: it is the same
+    // opt-in `initialToolNames` already gave apps for these names.
+    const eager = entries
+        .filter(([, entry]) => entry.deferLoading === false)
+        .map(([name]) => name);
     if (configured)
-        return configured;
-    return Object.entries(templateActions)
-        .filter(([name, entry]) => !isFrameworkGroupedAction(name, entry))
+        return [...new Set([...configured, ...eager])];
+    if (eager.length > 0)
+        return eager;
+    return entries
+        .filter(([name, entry]) => !isFrameworkGroupedAction(name, entry) && entry.deferLoading !== true)
         .map(([name]) => name);
 }

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

@@ -6,6 +6,7 @@ import { appendA2AArtifactLinks, buildA2ARecoverableArtifactMessage, } from "../
 import { hasConfiguredA2ASecret, isLoopbackAddress, isTrustedLocalRuntime, } from "../a2a/auth-policy.js";
 import { sanitizeA2ACorrelationId, sanitizeA2ACorrelationMetadata, } from "../a2a/correlation.js";
 import { createA2AApproval, updateTaskStatusMessage, } from "../a2a/task-store.js";
+import { clientAbortReason } from "../agent/abort-reasons.js";
 import { canUpdateAgentAppModelDefaultSettings, normalizeAgentAppModelDefaultAppId, readAgentAppModelDefaultSettings, resetAgentAppModelDefaultSettings, writeAgentAppModelDefaultSettings, } from "../agent/app-model-defaults.js";
 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";
@@ -14,7 +15,6 @@ import { SYSTEM_PROMPT_CACHE_SPLIT } from "../agent/engine/prompt-cache.js";
 import { PROVIDER_TO_ENV } from "../agent/engine/provider-env-vars.js";
 import { hostedHarnessSystemPrompt } from "../agent/harness/hosted.js";
 import { createProductionAgentHandler, actionsToEngineTools, executeAgentToolCall, filterActionsByAllowedNames, normalizeAgentActionSurfaceResolution, readPersistedActionSurface, toolCallCacheKey, getActiveRunForThreadAsync, abortRunDurably, abortTurnDurably, subscribeToRun, } from "../agent/production-agent.js";
-import { clientAbortReason } from "../agent/run-loop-with-resume.js";
 import { callerHasRunAccess, callerHasThreadAccess, } from "../agent/run-ownership.js";
 import { markTurnAborted, readBackgroundRunClaim } from "../agent/run-store.js";
 import { buildCurrentTimeUserContext, buildRuntimeContextPrompt, } from "../agent/runtime-context.js";
@@ -33,6 +33,7 @@ import { filterFrameworkToolGroups, resolveFrameworkTools, } from "../framework-
 import { verifyInternalToken, extractBearerToken, } from "../integrations/internal-token.js";
 import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
 import { McpClientManager, mcpToolsToActionEntries, syncMcpActionEntries, mountMcpServersRoutes, mountMcpHubRoutes, buildMergedConfig, startMcpConfigRefresh, getHubStatus, isHubServeEnabled, } from "../mcp-client/index.js";
+import { declaredMcpToolNames } from "../mcp/build-server.js";
 import { setProgressPreListHook } from "../progress/store.js";
 import { getSkillNameFromPath } from "../resources/metadata.js";
 import { resourceList, resourceListAccessible, resourceGet, ensurePersonalDefaults, SHARED_OWNER, WORKSPACE_OWNER, } from "../resources/store.js";
@@ -113,7 +114,7 @@ import { buildSystemManifestSections, setContextXraySystemSections, } from "../a
 // the ones that were already part of the public surface) so
 // `createAgentChatPlugin` below stays a thinner orchestrator.
 // ---------------------------------------------------------------------------
-import { buildSelectedA2AReceiverContext, createA2AEngineToolSurface, DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS, DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS, filterAgentTools, filterPublicAgentActions, filterDirectA2AActions, filterReadOnlyActions, isSelectedA2AReceiver, resolveInitialToolNames, runA2AAgentLoop, runMCPAgentLoop, assembleA2AFinalResponse, buildPublicAgentA2ASkills, buildAuthenticatedAgentA2ASkills, resolveArtifactBaseUrl, } from "./agent-chat/action-filters-a2a.js";
+import { buildSelectedA2AReceiverContext, createA2AEngineToolSurface, DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS, DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS, filterAgentTools, filterMcpOnlyActions, filterPublicAgentActions, filterDirectA2AActions, filterReadOnlyActions, isSelectedA2AReceiver, resolveInitialToolNames, runA2AAgentLoop, runMCPAgentLoop, assembleA2AFinalResponse, buildPublicAgentA2ASkills, buildAuthenticatedAgentA2ASkills, resolveArtifactBaseUrl, } from "./agent-chat/action-filters-a2a.js";
 import { createBuilderBrowserTool, createTeamTools, } from "./agent-chat/browser-team-tools.js";
 import { createDataWidgetActionEntries, createFrameworkContextEntry, createRefreshScreenEntry, createUrlTools, } from "./agent-chat/context-tools.js";
 import { _agentChatPromptSectionsForTests, buildFrameworkPrompts, buildSchemaBlock, collectFiles, corpusToolNamesTaughtByPrompt, generateActionsPrompt, generateCorpusToolsPrompt, } from "./agent-chat/framework-prompts.js";
@@ -708,6 +709,17 @@ export function createAgentChatPlugin(options) {
             // whatever `generateCorpusToolsPrompt` teaches by name for this request.
             const templateInitialToolNames = resolveInitialToolNames(templateScripts, options?.initialToolNames);
             const discoveredActions = filterFrameworkToolGroups(filterAgentTools(discoveredActionsAll), disabledFrameworkGroups);
+            // MCP-only actions: `agentTool: false` with an explicit `mcpTool: true`.
+            // `filterAgentTools` above just dropped them — correctly, since the app's
+            // own agent must not see them — so the external surfaces below re-merge
+            // this set instead of reading the unfiltered registries. Keep it OUT of
+            // `allScripts`, the chat/A2A/ask_app loops, and every prompt: an
+            // `ask_app` run is the app's own agent, which `agentTool: false` already
+            // answered. Only the direct MCP and A2A tool surfaces get these.
+            const mcpOnlyActions = filterFrameworkToolGroups(filterMcpOnlyActions({
+                ...discoveredActionsAll,
+                ...templateScriptsAll,
+            }), disabledFrameworkGroups);
             // Per-request owner is read from the AsyncLocalStorage run context
             // (populated by prepareRun). Module-scope `let` would race across
             // concurrent requests on a long-lived Node process — overlapping
@@ -1146,6 +1158,14 @@ export function createAgentChatPlugin(options) {
                     ...devRunCodeTool,
                 })
                 : undefined;
+            // The surface external agents get: everything the app's agent has, plus
+            // the MCP-only actions the agent filter removed. The agent sets win on a
+            // name collision, which by construction cannot happen — an action is in
+            // one set or the other, never both.
+            const externalActions = { ...mcpOnlyActions, ...allScripts };
+            const externalFullActions = mcpFullActions
+                ? { ...mcpOnlyActions, ...mcpFullActions }
+                : undefined;
             const { mountA2A } = await import("../a2a/server.js");
             mountA2A(nitroApp, {
                 appId: options?.appId,
@@ -1153,13 +1173,13 @@ export function createAgentChatPlugin(options) {
                     ? options.appId.charAt(0).toUpperCase() + options.appId.slice(1)
                     : "Agent",
                 description: `Agent-native ${options?.appId ?? "app"} agent`,
-                skills: buildPublicAgentA2ASkills(allScripts),
-                authenticatedSkills: buildAuthenticatedAgentA2ASkills(mcpFullActions ?? allScripts, mcpOptions),
+                skills: buildPublicAgentA2ASkills(externalActions),
+                authenticatedSkills: buildAuthenticatedAgentA2ASkills(externalFullActions ?? externalActions, mcpOptions),
                 publicSkillsOnly: true,
                 streaming: true,
                 durableBackgroundRuns: options?.durableBackgroundRuns,
                 executeReadOnlyAction: async ({ action, input, invocationId }) => {
-                    const actions = filterDirectA2AActions(mcpFullActions ?? allScripts, mcpOptions);
+                    const actions = filterDirectA2AActions(externalFullActions ?? externalActions, mcpOptions);
                     const entry = actions[action];
                     if (!entry) {
                         return {
@@ -1188,7 +1208,7 @@ export function createAgentChatPlugin(options) {
                 },
                 executeApproval: async (approval) => {
                     const result = await executeAgentToolCall({
-                        actions: mcpFullActions ?? allScripts,
+                        actions: externalFullActions ?? externalActions,
                         name: approval.tool,
                         input: approval.input,
                         callId: approval.callId,
@@ -1523,7 +1543,14 @@ export function createAgentChatPlugin(options) {
                         });
                     const a2aToolSurface = createA2AEngineToolSurface(actionsToEngineTools(a2aActions), effectiveInitialToolNames, {
                         receiverOwnsObjective,
-                        localCapabilityNames: mcpOptions.connectorCatalog,
+                        // Same curated set the MCP mount serves: config names plus the
+                        // actions that declare `mcpTool: true` themselves.
+                        localCapabilityNames: [
+                            ...new Set([
+                                ...(mcpOptions.connectorCatalog ?? []),
+                                ...declaredMcpToolNames(a2aActions),
+                            ]),
+                        ],
                     });
                     // Precise current time rides the user message (not the cached
                     // system-prompt prefix) — same pattern as the interactive handler.
@@ -1848,8 +1875,8 @@ export function createAgentChatPlugin(options) {
                         `Agent-native ${options?.appId ?? "app"} agent`,
                     websiteUrl: mcpOptions.websiteUrl,
                     icons: mcpOptions.icons,
-                    actions: allScripts,
-                    productionActions: mcpFullActions,
+                    actions: externalActions,
+                    productionActions: externalFullActions,
                     ...(mcpOptions.catalog ? { catalogMode: mcpOptions.catalog } : {}),
                     ...(mcpOptions.builtinCrossAppTools !== undefined
                         ? { builtinCrossAppTools: mcpOptions.builtinCrossAppTools }

package/dist/server/agent-discovery.js

@@ -40,6 +40,8 @@ export function normalizeAgentId(id) {
         normalized === "asset") {
         return "assets";
     }
+    if (normalized === "videos")
+        return "clips";
     return normalized;
 }
 const WORKSPACE_APPS_ENV_KEY = "AGENT_NATIVE_WORKSPACE_APPS_JSON";
@@ -67,8 +69,11 @@ export function parseWorkspaceAppMetadataSettings(raw) {
         ? record.apps
         : {};
     const apps = {};
-    for (const [id, value] of Object.entries(rawApps)) {
-        if (!id.trim() || !value || typeof value !== "object")
+    const canonicalIds = new Set();
+    for (const [rawId, value] of Object.entries(rawApps)) {
+        const id = rawId.trim();
+        const normalizedId = id ? normalizeAgentId(id) : "";
+        if (!normalizedId || !value || typeof value !== "object")
             continue;
         const item = value;
         const override = {};
@@ -89,8 +94,14 @@ export function parseWorkspaceAppMetadataSettings(raw) {
             override.updatedAt = updatedAt;
         if (updatedBy)
             override.updatedBy = updatedBy;
-        if (Object.keys(override).length > 0)
-            apps[id.trim()] = override;
+        if (Object.keys(override).length > 0) {
+            const isCanonical = id.toLowerCase() === normalizedId;
+            if (isCanonical || !canonicalIds.has(normalizedId)) {
+                apps[normalizedId] = override;
+            }
+            if (isCanonical)
+                canonicalIds.add(normalizedId);
+        }
     }
     return { apps };
 }
@@ -110,7 +121,7 @@ export async function writeWorkspaceAppMetadataOverride(input) {
     const key = workspaceAppMetadataSettingsKey();
     if (!key)
         throw new Error("no authenticated user");
-    const appId = input.appId.trim();
+    const appId = normalizeAgentId(input.appId);
     if (!appId)
         throw new Error("appId is required");
     const { getSetting, putSetting } = await import("../settings/index.js");
@@ -145,7 +156,7 @@ export async function writeWorkspaceAppMetadataOverride(input) {
     return current;
 }
 export function applyWorkspaceAppMetadataOverride(app, settings) {
-    const override = settings.apps[app.id];
+    const override = settings.apps[normalizeAgentId(app.id)] ?? settings.apps[app.id];
     if (!override)
         return app;
     const name = cleanOptionalText(override.name);
@@ -244,21 +255,20 @@ export async function discoverAgents(selfAppId, options) {
                     continue;
                 const manifestId = normalizeAgentId(manifest.id);
                 // If the resource override carries a localhost URL but we're running
-                // in production (e.g. a stale dev-time seed got promoted to the prod
+                // in a hosted runtime (e.g. a stale dev-time seed got promoted to the prod
                 // DB), fall back to the matching built-in's prod URL instead of
                 // letting the override win — otherwise outbound `call-agent` fetches
                 // from a serverless function would target localhost and fail with
                 // "fetch failed" instantly. The override still wins for non-localhost
                 // URLs (the supported case for self-hosted custom agents).
                 let url = manifest.url;
-                const isProduction = typeof process !== "undefined" &&
-                    process.env?.NODE_ENV === "production";
-                if (isProduction &&
-                    typeof url === "string" &&
-                    /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|\/|$)/.test(url)) {
+                const isHosted = isHostedRuntime();
+                if (isHosted && typeof url === "string" && isLoopbackUrl(url)) {
                     const builtin = agentsById.get(manifestId);
                     if (builtin?.url)
                         url = builtin.url;
+                    else
+                        continue;
                 }
                 const builtin = agentsById.get(manifestId);
                 if (options?.preferLocalUrls && builtin) {
@@ -327,10 +337,19 @@ function hostnameFromUrlLike(value) {
 }
 function isLoopbackUrl(value) {
     const hostname = hostnameFromUrlLike(value);
-    return (hostname === "localhost" ||
-        hostname === "127.0.0.1" ||
-        hostname === "0.0.0.0" ||
-        hostname === "::1");
+    if (!hostname)
+        return false;
+    const normalized = hostname.replace(/^\[|\]$/g, "");
+    if (normalized === "localhost" ||
+        normalized.startsWith("127.") ||
+        normalized === "0.0.0.0" ||
+        normalized === "::1") {
+        return true;
+    }
+    const mapped = normalized.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (!mapped)
+        return false;
+    return Number.parseInt(mapped[1], 16) >>> 8 === 0x7f;
 }
 function hasPublicRuntimeUrl() {
     // Intentionally omit generic `URL` / `DEPLOY_URL` here. Platforms that set
@@ -353,6 +372,8 @@ function hasPublicRuntimeUrl() {
     });
 }
 function isHostedRuntime() {
+    if (process.env.NETLIFY_LOCAL === "true")
+        return false;
     return (process.env.NODE_ENV === "production" ||
         !!process.env.NETLIFY ||
         !!process.env.AWS_LAMBDA_FUNCTION_NAME ||
@@ -412,7 +433,8 @@ function parseWorkspaceAppsManifest(parsed) {
         if (!entry || typeof entry !== "object")
             return null;
         const e = entry;
-        const id = typeof e.id === "string" ? e.id.trim() : "";
+        const rawId = typeof e.id === "string" ? e.id.trim() : "";
+        const id = rawId ? normalizeAgentId(rawId) : "";
         const pathValue = typeof e.path === "string" ? e.path.trim() : "";
         if (!id || !pathValue.startsWith("/"))
             return null;
@@ -498,11 +520,11 @@ function readWorkspaceAppsFromFilesystem() {
             return null;
         const routeAccess = workspaceAppRouteAccessFromPackageJson(pkg);
         return {
-            id: entry.name,
+            id: normalizeAgentId(entry.name),
             name: pkg.displayName || titleCase(entry.name),
             description: pkg.description || "",
             path: `/${entry.name}`,
-            isDispatch: entry.name === "dispatch",
+            isDispatch: normalizeAgentId(entry.name) === "dispatch",
             audience: workspaceAppAudienceFromPackageJson(pkg) ??
                 DEFAULT_WORKSPACE_APP_AUDIENCE,
             publicPaths: routeAccess.publicPaths ?? [],
@@ -550,8 +572,9 @@ async function discoverWorkspaceAgents(selfAppId, options) {
     if (!workspaceApps)
         return [];
     const metadataSettings = await readWorkspaceAppMetadataSettings();
+    const normalizedSelfAppId = selfAppId ? normalizeAgentId(selfAppId) : "";
     return workspaceApps
-        .filter((app) => app.id !== selfAppId)
+        .filter((app) => normalizeAgentId(app.id) !== normalizedSelfAppId)
         .map((app) => {
         const withOverride = applyWorkspaceAppMetadataOverride(app, metadataSettings);
         const builtin = BUILTIN_AGENTS.find((agent) => agent.id === withOverride.id);

package/dist/server/auth.js

@@ -4056,6 +4056,24 @@ async function mountBetterAuthRoutes(app, options) {
             return { error: authError.message };
         }
     }));
+    // Better Auth redirects new magic-link users through this small public
+    // callback so first-run onboarding is marked only for newly created users.
+    // Keep this before the generic magic-link handler for runtimes whose
+    // app.use() middleware paths match descendants as prefixes.
+    app.use("/_agent-native/auth/magic-link/new-user", defineEventHandler(async (event) => {
+        if (!isReadMethod(event)) {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const query = getQuery(event);
+        const rawReturn = Array.isArray(query.return)
+            ? query.return[0]
+            : query.return;
+        if (await getSession(event)) {
+            setFirstRunOnboardingCookie(event);
+        }
+        return redirectWithStagedCookies(event, safeReturnPath(rawReturn), 302);
+    }));
     // Passwordless login via Better Auth's rate-limited magic-link plugin.
     app.use("/_agent-native/auth/magic-link", defineEventHandler(async (event) => {
         if (getMethod(event) === "GET") {
@@ -4313,22 +4331,6 @@ async function mountBetterAuthRoutes(app, options) {
             headers: { "Content-Type": "text/html; charset=utf-8" },
         });
     }));
-    // Better Auth redirects new magic-link users through this small public
-    // callback so first-run onboarding is marked only for newly created users.
-    app.use("/_agent-native/auth/magic-link/new-user", defineEventHandler(async (event) => {
-        if (!isReadMethod(event)) {
-            setResponseStatus(event, 405);
-            return { error: "Method not allowed" };
-        }
-        const query = getQuery(event);
-        const rawReturn = Array.isArray(query.return)
-            ? query.return[0]
-            : query.return;
-        if (await getSession(event)) {
-            setFirstRunOnboardingCookie(event);
-        }
-        return redirectWithStagedCookies(event, safeReturnPath(rawReturn), 302);
-    }));
     // Auth guard — stored both in framework middleware registry AND in
     // _authGuardFn so the server middleware can enforce it on ALL routes.
     const loginHtmlConfig = getOnboardingLoginHtmlConfig(options, authLoginMode);

package/dist/server/beta-opt-out-html.js

@@ -1,4 +1,4 @@
-import { BETA_OPT_OUT_DURATION_MS, BETA_OPT_OUT_QUERY_PARAM, BETA_OPT_OUT_STORAGE_KEY, ENVIRONMENT_BETA_HOSTS, } from "../shared/environment-lanes.js";
+import { BETA_FORCE_QUERY_PARAM, BETA_FORCE_SESSION_STORAGE_KEY, BETA_OPT_OUT_DURATION_MS, BETA_OPT_OUT_QUERY_PARAM, BETA_OPT_OUT_STORAGE_KEY, ENVIRONMENT_BETA_HOSTS, } from "../shared/environment-lanes.js";
 export const BETA_OPT_OUT_PERSISTENCE_MARKER = "Persist the beta opt-out before authentication";
 const ENVIRONMENT_SWITCHER_MARKER = 'data-agent-native-environment-switcher="1"';
 const ENVIRONMENT_SWITCHER_STYLE_MARKER = 'data-agent-native-environment-switcher-style="1"';
@@ -16,11 +16,16 @@ const environmentSwitcherMarkup = `<div class="environment-switcher" id="environ
     <div class="environment-popover-title" id="environment-popover-title">You're on Agent Native Beta</div>
     <div class="environment-popover-copy">Choose where you want to continue.</div>
     <a class="environment-production-link" id="environment-production-link" href="">Switch to production</a>
+    <button type="button" class="environment-hide-badge" id="environment-hide-badge">Hide badge</button>
   </div>
 </div>`;
 const environmentSwitcherStyles = `<style ${ENVIRONMENT_SWITCHER_STYLE_MARKER}>
-  color-scheme: dark;
   .environment-switcher {
+    /* Must stay inside a rule. A bare declaration at stylesheet top level does
+       not end at its semicolon: the next qualified rule's prelude swallows it,
+       taking this selector with it, so the badge loses position/left/bottom and
+       drops into normal flow at the bottom of the page. */
+    color-scheme: dark;
     position: fixed;
     left: max(0.75rem, env(safe-area-inset-left));
     bottom: max(0.75rem, env(safe-area-inset-bottom));
@@ -53,7 +58,8 @@ const environmentSwitcherStyles = `<style ${ENVIRONMENT_SWITCHER_STYLE_MARKER}>
     background: color-mix(in srgb, CanvasText 85%, Canvas);
   }
   .environment-badge:focus-visible,
-  .environment-production-link:focus-visible {
+  .environment-production-link:focus-visible,
+  .environment-hide-badge:focus-visible {
     outline: 2px solid LinkText;
     outline-offset: 2px;
   }
@@ -87,6 +93,23 @@ const environmentSwitcherStyles = `<style ${ENVIRONMENT_SWITCHER_STYLE_MARKER}>
   .environment-production-link:hover {
     background: color-mix(in srgb, CanvasText 12%, Canvas);
   }
+  .environment-hide-badge {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    min-height: 2rem;
+    margin-top: 0.5rem;
+    margin-bottom: -0.5rem;
+    padding: 0.375rem 0.75rem;
+    color: GrayText;
+    border: 0;
+    background: transparent;
+    font: inherit;
+    font-size: 0.8125rem;
+    cursor: pointer;
+  }
+  .environment-hide-badge:hover { color: CanvasText; }
 </style>`;
 const environmentSwitcherScript = `<script ${ENVIRONMENT_SWITCHER_SCRIPT_MARKER}>
 (function __anInitEnvironmentBadge() {
@@ -94,9 +117,19 @@ const environmentSwitcherScript = `<script ${ENVIRONMENT_SWITCHER_SCRIPT_MARKER}
   var button = document.getElementById('environment-badge');
   var popover = document.getElementById('environment-popover');
   var productionLink = document.getElementById('environment-production-link');
-  if (!switcher || !button || !popover || !productionLink) return;
+  var hideButton = document.getElementById('environment-hide-badge');
+  if (!switcher || !button || !popover || !productionLink || !hideButton) return;
   if (window.parent !== window) return;
 
+  try {
+    var forceUrl = new URL(window.location.href);
+    if (forceUrl.searchParams.get(${JSON.stringify(BETA_FORCE_QUERY_PARAM)}) === 'true') {
+      window.sessionStorage.setItem(${JSON.stringify(BETA_FORCE_SESSION_STORAGE_KEY)}, '1');
+    }
+  } catch (error) {
+    void error;
+  }
+
   var betaHosts = ${JSON.stringify(ENVIRONMENT_BETA_HOSTS)};
   var hostname = (window.location.hostname || '').toLowerCase().replace(/\\.$/, '');
   var productionHost = hostname.indexOf('beta.') === 0 ? hostname.slice(5) : '';
@@ -132,12 +165,20 @@ const environmentSwitcherScript = `<script ${ENVIRONMENT_SWITCHER_SCRIPT_MARKER}
   document.addEventListener('keydown', function(event) {
     if (event.key === 'Escape') setOpen(false);
   });
+  hideButton.addEventListener('click', function() {
+    setOpen(false);
+    switcher.hidden = true;
+  });
 })();
 </script>`;
 const betaOptOutPersistenceScript = `<script data-agent-native-beta-opt-out>
 // ${BETA_OPT_OUT_PERSISTENCE_MARKER}.
 (function __anPersistBetaOptOut() {
   try {
+    var forceUrl = new URL(window.location.href);
+    if (forceUrl.searchParams.get(${JSON.stringify(BETA_FORCE_QUERY_PARAM)}) === 'true') {
+      window.sessionStorage.setItem(${JSON.stringify(BETA_FORCE_SESSION_STORAGE_KEY)}, '1');
+    }
     var optOutUrl = new URL(window.location.href);
     var optOutValue = optOutUrl.searchParams.get(${JSON.stringify(BETA_OPT_OUT_QUERY_PARAM)});
     if (optOutValue === null) return;

package/dist/server/better-auth-instance.d.ts

@@ -265,5 +265,6 @@ export declare function resetBetterAuth(): Promise<void>;
  */
 export declare function configureLocalSqlite(sqlite: {
     pragma(statement: string): unknown;
-}): void;
+    close?(): void;
+}): Promise<void>;
 export declare function buildDatabaseConfig(dialect: string): Promise<BetterAuthOptions["database"]>;

package/dist/server/better-auth-instance.js

@@ -16,7 +16,7 @@ import { pgTable, text as pgText, timestamp as pgTimestamp, boolean as pgBoolean
 import { sqliteTable, text as sqliteText, integer as sqliteInteger, } from "drizzle-orm/sqlite-core";
 import { TEMPLATES } from "../cli/templates-meta.js";
 import { getDbExec, isPostgres } from "../db/client.js";
-import { getDialect, getCloudflareD1Binding, getDatabaseUrl, getDatabaseAuthToken, closePgliteClients, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgPoolOptions, neonPoolOptions, guardNeonPool, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "../db/client.js";
+import { getDialect, getCloudflareD1Binding, getDatabaseUrl, getDatabaseAuthToken, closePgliteClients, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgPoolOptions, neonPoolOptions, guardNeonPool, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, prepareLocalSqliteUrl, sqliteFilenameFromUrl, retrySqliteBusy, } from "../db/client.js";
 import { CORE_RESET_PASSWORD_EMAIL_ID, CORE_VERIFY_SIGNUP_EMAIL_ID, } from "../email-catalog/system-emails.js";
 import { saveOAuthTokens } from "../oauth-tokens/store.js";
 import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
@@ -539,7 +539,12 @@ export async function getBetterAuth(config) {
         return _auth;
     if (_initPromise)
         return _initPromise;
-    _initPromise = createBetterAuthInstance(config);
+    // A failed boot must not be cached: every later request would replay the same
+    // stale error with no way back short of restarting the process.
+    _initPromise = createBetterAuthInstance(config).catch((error) => {
+        _initPromise = undefined;
+        throw error;
+    });
     _auth = await _initPromise;
     return _auth;
 }
@@ -1247,9 +1252,20 @@ async function createBetterAuthInstance(config) {
  * as the shared app connection. Better Auth uses its own SQLite handle, so the
  * app connection's busy timeout does not protect first-run account creation.
  */
-export function configureLocalSqlite(sqlite) {
+export async function configureLocalSqlite(sqlite) {
     sqlite.pragma("busy_timeout = 10000");
-    sqlite.pragma("journal_mode = WAL");
+    try {
+        // Vite can start a replacement Nitro runtime while the previous instance is
+        // still releasing app.db, and the busy timeout can expire during that
+        // handoff, so retry the idempotent WAL negotiation.
+        await retrySqliteBusy(async () => sqlite.pragma("journal_mode = WAL"), {
+            rethrow: true,
+        });
+    }
+    catch (error) {
+        sqlite.close?.();
+        throw error;
+    }
 }
 export async function buildDatabaseConfig(dialect) {
     if (dialect === "postgres") {
@@ -1325,9 +1341,9 @@ export async function buildDatabaseConfig(dialect) {
     if (url.startsWith("file:") || !url.includes("://")) {
         // Local SQLite via better-sqlite3
         const { default: Database } = await import("better-sqlite3");
-        const filePath = url.replace(/^file:/, "");
-        const sqlite = new Database(filePath);
-        configureLocalSqlite(sqlite);
+        const sqliteUrl = await prepareLocalSqliteUrl(url.startsWith("file:") ? url : `file:${url}`);
+        const sqlite = new Database(sqliteFilenameFromUrl(sqliteUrl));
+        await configureLocalSqlite(sqlite);
         const { drizzle } = await import("drizzle-orm/better-sqlite3");
         const db = drizzle(sqlite, { schema: sqliteAuthSchema });
         const { drizzleAdapter } = await import("better-auth/adapters/drizzle");

package/dist/server/builder-design-systems.d.ts

@@ -81,6 +81,8 @@ export interface BuilderDesignSystemHydratedReference extends BuilderDesignSyste
     docs: BuilderDesignSystemDocument[];
     tokenValues: Record<string, string>;
     docCount: number;
+    /** True only when Builder explicitly confirms that indexing is complete. */
+    completionConfirmed?: boolean;
 }
 export interface BuilderDesignSystemIndexOptions {
     projectName?: string;
@@ -108,8 +110,9 @@ export interface BuilderDesignSystemIndexResult {
     designSystemId: string;
     suggestedTitle: string | null;
     builderUrl: string;
-    status: "in-progress";
+    status: BuilderDesignSystemStatus;
 }
+export type BuilderDesignSystemStatus = "in-progress" | "ready" | "complete" | "completed" | "error" | "failed" | "cancelled";
 export interface BuilderDesignSystemUploadAttachment {
     name: string;
     mimetype: string;