@agent-native/core 0.0.0-beta-20260820052446 → 0.0.0-beta-20260820094341

package/corpus/templates/slides/app/components/editor/EditorSidebar.tsx

@@ -63,7 +63,8 @@ interface EditorSidebarProps {
   aspectRatio?: AspectRatio;
   /** Active deck design system used by slide content tokens. */
   designSystem?: DesignSystemData;
-  /** The next slide while the agent is preparing its HTML. */
+  /** The next slide while the agent is preparing its HTML. Omitted when the
+   *  agent is filling a placeholder that already has a row in this rail. */
   generatingSlide?: { index: number };
   generatingSlideSelected?: boolean;
   onSelectGeneratingSlide?: () => void;
@@ -75,8 +76,15 @@ interface EditorSidebarProps {
   /** Clears `describeSlideId` in the parent when the popover closes. */
   onCloseDescribe: () => void;
   /** Reports add-slide generation state up so the toolbar's New Slide button
-   *  can disable itself while a request is in flight. */
-  onAddSlideGeneratingChange?: (generating: boolean) => void;
+   *  can disable itself while a request is in flight. `targetSlideId` is the
+   *  placeholder the agent was asked to fill, so the parent can mark that row
+   *  as the AI-active one instead of appending a second generating row. */
+  onAddSlideGeneratingChange?: (
+    generating: boolean,
+    targetSlideId: string | null,
+  ) => void;
+  /** Slide the agent is filling in place, marked as AI-active in the rail. */
+  aiGeneratingSlideId?: string | null;
   /** Resolves once a just-inserted blank slide has actually reached the
    *  server, so the agent's update-slide request can't race the add-slide
    *  persistence. */
@@ -199,6 +207,7 @@ function SortableSlideThumb({
   onOverflowChange,
   readOnly = false,
   aiEditing = false,
+  isFillingPlaceholder = false,
   canDelete = true,
   hasSlideClipboard = false,
   onCutSlide,
@@ -219,7 +228,11 @@ function SortableSlideThumb({
   aspectRatio?: AspectRatio;
   designSystem?: DesignSystemData;
   onOverflowChange: (info: SlideOverflowInfo) => void;
+  /** A recent edit attributed to the agent — a lingering highlight, not a live signal. */
   aiEditing?: boolean;
+  /** This exact slide is the placeholder the agent is filling right now — the
+   *  one case where the shimmer belongs even without live presence. */
+  isFillingPlaceholder?: boolean;
   /** False when this is the deck's last remaining slide — Cut/Delete stay enabled elsewhere but must not remove it. */
   canDelete?: boolean;
   hasSlideClipboard?: boolean;
@@ -255,7 +268,11 @@ function SortableSlideThumb({
   const humanPresenceUsers = presenceUsers.filter(
     (user) => !isAgentPresenceUser(user),
   );
-  const showAiMarker = aiEditing || agentPresent;
+  const showAiMarker = aiEditing || agentPresent || isFillingPlaceholder;
+  // Narrower than the badge above: `aiEditing` also covers a slide's lingering
+  // post-edit highlight, which is "recently done," not "in progress." The
+  // shimmer should only run while the agent is actually live on this slide.
+  const showGeneratingShimmer = agentPresent || isFillingPlaceholder;
 
   return (
     <div ref={setNodeRef} style={style}>
@@ -331,6 +348,12 @@ function SortableSlideThumb({
                   designSystem={designSystem}
                   onOverflowChange={onOverflowChange}
                 />
+                {showGeneratingShimmer && (
+                  <div
+                    aria-hidden="true"
+                    className="slide-thumbnail-ai-shimmer pointer-events-none absolute inset-0 z-10"
+                  />
+                )}
                 {slide.skipped && (
                   // guard:allow-raw-color — dims an arbitrary-colored slide render, not app chrome; must stay black regardless of theme
                   <div className="absolute inset-0 z-10 flex items-center justify-center bg-black/40">
@@ -454,6 +477,7 @@ export default function EditorSidebar({
   describeSlideId,
   onCloseDescribe,
   onAddSlideGeneratingChange,
+  aiGeneratingSlideId,
   onAwaitAddSlidePersisted,
   onRemoveFailedSlide,
   addSlideAgentSubmit,
@@ -662,6 +686,7 @@ export default function EditorSidebar({
                 aspectRatio={aspectRatio}
                 designSystem={designSystem}
                 aiEditing={aiEditedSlideIds.has(slide.id)}
+                isFillingPlaceholder={slide.id === aiGeneratingSlideId}
                 canDelete={slides.length > 1}
                 hasSlideClipboard={hasSlideClipboard}
                 onCutSlide={onCutSlide}
@@ -706,12 +731,12 @@ export default function EditorSidebar({
           slideCount={slides.length}
           targetSlideId={describeSlideId}
           agentSubmit={async (message, context) => {
-            onAddSlideGeneratingChange?.(true);
+            onAddSlideGeneratingChange?.(true, describeSlideId);
             try {
               await onAwaitAddSlidePersisted?.();
             } catch (error) {
               console.error("Failed to persist new slide:", error);
-              onAddSlideGeneratingChange?.(false);
+              onAddSlideGeneratingChange?.(false, null);
               // The popover already closed (AddSlidePopover doesn't wait on
               // this async callback), so the typed prompt is gone either
               // way. Only remove the placeholder if it's still untouched —

package/corpus/templates/slides/app/global.css

@@ -1167,6 +1167,35 @@ button[title="Open agent sidebar"] {
   }
 }
 
+/* Sweeps across a slide thumbnail while the agent is generating its content.
+   Sits above the rendered slide so it reads as "in progress" instead of a
+   static placeholder for the length of the generation run. */
+.slide-thumbnail-ai-shimmer {
+  background: linear-gradient(
+    100deg,
+    transparent 30%,
+    rgba(255, 255, 255, 0.16) 50%,
+    transparent 70%
+  );
+  background-size: 200% 100%;
+  animation: slide-thumbnail-shimmer 1.6s ease-in-out infinite;
+}
+
+@keyframes slide-thumbnail-shimmer {
+  from {
+    background-position: 150% 0;
+  }
+  to {
+    background-position: -50% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .slide-thumbnail-ai-shimmer {
+    animation: none;
+  }
+}
+
 .image-overlay-btn {
   display: flex;
   align-items: center;

package/corpus/templates/slides/app/lib/generation-state.ts

@@ -26,6 +26,31 @@ export function shouldShowNewDeckGeneratingProgress({
   return generating && isNewDeckCreation;
 }
 
+/** The blank placeholder "New slide" inserted and handed to the agent to fill.
+ *  While one is live the rail marks that existing row as AI-active; appending
+ *  the synthetic generating row too would read as a second, duplicate slide.
+ *  Returns null once the placeholder leaves the deck, or once its content is
+ *  no longer the blank stand-in: the fill is done, presence/recent-edit
+ *  tracking picks up that slide's own marker from there, and if the same run
+ *  goes on to `add-slide` more slides (a multi-slide request), those are
+ *  genuinely new and should get the trailing generating row again. */
+export function slideBeingFilledInPlace({
+  addSlideGenerating,
+  addSlideTargetId,
+  slides,
+  blankContent,
+}: {
+  addSlideGenerating: boolean;
+  addSlideTargetId: string | null;
+  slides: { id: string; content: string }[];
+  blankContent: string;
+}): string | null {
+  if (!addSlideGenerating || !addSlideTargetId) return null;
+  const target = slides.find((slide) => slide.id === addSlideTargetId);
+  if (!target || target.content !== blankContent) return null;
+  return addSlideTargetId;
+}
+
 export function shouldClearNewDeckGeneratingState({
   generating,
   generationStarted,

package/corpus/templates/slides/app/pages/DeckEditor.tsx

@@ -65,6 +65,7 @@ import { Button } from "@/components/ui/button";
 import {
   clearSlideEditingActive,
   deckIdFromPathname,
+  defaultSlideContent,
   hasUnsavedDeckChanges,
   markSlideEditingActive,
   type Slide,
@@ -100,6 +101,7 @@ import {
   shouldClearNewDeckGeneratingState,
   shouldShowNewDeckGeneratingOverlay,
   shouldShowNewDeckGeneratingProgress,
+  slideBeingFilledInPlace,
 } from "@/lib/generation-state";
 import { isMissingUploadProviderError } from "@/lib/image-drop-to-agent";
 import {
@@ -172,6 +174,14 @@ export default function DeckEditor() {
   const [activeSlideId, setActiveSlideId] = useState<string | null>(null);
   const [inlineEditActive, setInlineEditActive] = useState(false);
   const [addSlideGenerating, setAddSlideGenerating] = useState(false);
+  // The blank placeholder the agent was asked to fill in place. The rail must
+  // light THAT row up as AI-active instead of appending a synthetic generating
+  // row, which reads as a second, duplicate slide.
+  const [addSlideTargetId, setAddSlideTargetId] = useState<string | null>(null);
+  const endAddSlideGeneration = useCallback(() => {
+    setAddSlideGenerating(false);
+    setAddSlideTargetId(null);
+  }, []);
   const [generatingSlideSelected, setGeneratingSlideSelected] = useState(false);
   const { hasUnsavedChanges: hasUnsavedSave } = useSaveState();
   const hasPendingDeckEdits =
@@ -207,17 +217,37 @@ export default function DeckEditor() {
   // tracking correct across a remount.
   const { generating: addSlideAgentGenerating, submit: addSlideAgentSubmit } =
     useAgentGenerating();
+  // Neither hook above is actually scoped to THIS run until its own submit()
+  // call has fired: before that, `activeTabRef` inside useAgentGenerating is
+  // still null, so both hooks report on ANY chat activity system-wide, same
+  // as the broad instance. The target is set (and the popover's persistence
+  // wait starts) well before that submit call, so an unrelated run finishing
+  // during that wait could otherwise satisfy either "seen true" guard below
+  // and clear the freshly-set target before this run ever sent a request.
+  // Both cleanup effects stay inert until this flips true.
+  const addSlideRequestSentRef = useRef(false);
   const sawAddSlideAgentGeneratingRef = useRef(false);
   useEffect(() => {
+    if (!addSlideRequestSentRef.current) return;
     if (addSlideAgentGenerating) {
       sawAddSlideAgentGeneratingRef.current = true;
       return;
     }
     if (addSlideGenerating && sawAddSlideAgentGeneratingRef.current) {
       sawAddSlideAgentGeneratingRef.current = false;
-      setAddSlideGenerating(false);
+      endAddSlideGeneration();
     }
-  }, [addSlideGenerating, addSlideAgentGenerating]);
+  }, [addSlideGenerating, addSlideAgentGenerating, endAddSlideGeneration]);
+  // Same guard for the broad `generating` signal below, which is never scoped
+  // to this run at all (by design — it reflects ANY agent chat activity).
+  const sawGeneratingRef = useRef(false);
+  const submitAddSlideAgent = useCallback(
+    (message: string, context: string) => {
+      addSlideRequestSentRef.current = true;
+      addSlideAgentSubmit(message, context);
+    },
+    [addSlideAgentSubmit],
+  );
   // Generation intent can arrive after this route mounts because the user
   // answers pre-generation questions from the empty editor.
   const wasNewDeckCreation = useRef(searchParams.get("generating") === "1");
@@ -371,10 +401,18 @@ export default function DeckEditor() {
   });
 
   const showQuestionFlow = Boolean(questionFlowQuestions?.length);
+  const fillingPlaceholderSlideId = slideBeingFilledInPlace({
+    addSlideGenerating,
+    addSlideTargetId,
+    slides: deck?.slides ?? [],
+    blankContent: defaultSlideContent.blank,
+  });
   const generatingSlideVisible =
     canEdit &&
     !showQuestionFlow &&
-    (isNewDeckGenerating || addSlideGenerating || showNewDeckGeneratingOverlay);
+    (isNewDeckGenerating ||
+      (addSlideGenerating && !fillingPlaceholderSlideId) ||
+      showNewDeckGeneratingOverlay);
   const showCurrentSlideEditor =
     !generatingSlideSelected &&
     !showNewDeckGeneratingOverlay &&
@@ -385,10 +423,20 @@ export default function DeckEditor() {
   }, [generatingSlideVisible]);
 
   // The add-slide request is finished once the agent stops generating, so the
-  // rail's placeholder must not outlive it.
+  // rail's placeholder must not outlive it. Mirrors the "seen true first"
+  // guard above so this backstop can't fire while `generating` just hasn't
+  // caught up with a run that hasn't started sending yet.
   useEffect(() => {
-    if (!generating) setAddSlideGenerating(false);
-  }, [generating]);
+    if (!addSlideRequestSentRef.current) return;
+    if (generating) {
+      sawGeneratingRef.current = true;
+      return;
+    }
+    if (addSlideGenerating && sawGeneratingRef.current) {
+      sawGeneratingRef.current = false;
+      endAddSlideGeneration();
+    }
+  }, [generating, addSlideGenerating, endAddSlideGeneration]);
 
   // Below `md` the rail is a drawer behind a full-viewport dimming scrim; at
   // `md` and up it's docked with no scrim. `sidebarOpen` is seeded from the
@@ -1606,8 +1654,22 @@ export default function DeckEditor() {
                   onCloseDescribe={() => setDescribeSlideId(null)}
                   onAwaitAddSlidePersisted={() => flushDeckSave(id)}
                   onRemoveFailedSlide={(slideId) => deleteSlide(id, slideId)}
-                  addSlideAgentSubmit={addSlideAgentSubmit}
-                  onAddSlideGeneratingChange={setAddSlideGenerating}
+                  addSlideAgentSubmit={submitAddSlideAgent}
+                  onAddSlideGeneratingChange={(isGenerating, targetSlideId) => {
+                    if (isGenerating) {
+                      // A new run starts clean: neither guard's "seen true"
+                      // state may carry over from an unrelated chat run, or
+                      // from whatever state the previous add-slide run left
+                      // behind, or the auto-clear effects below could fire on
+                      // stale state before this run even sends its request.
+                      sawGeneratingRef.current = false;
+                      sawAddSlideAgentGeneratingRef.current = false;
+                      addSlideRequestSentRef.current = false;
+                    }
+                    setAddSlideGenerating(isGenerating);
+                    setAddSlideTargetId(isGenerating ? targetSlideId : null);
+                  }}
+                  aiGeneratingSlideId={fillingPlaceholderSlideId}
                   onSelectSlide={(slideId) => {
                     setGeneratingSlideSelected(false);
                     setActiveSlideId(slideId);

package/dist/app-config/app.d.ts

@@ -27,6 +27,8 @@ export declare const appConfig: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     workspaceId: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
+    pingMessage: z.ZodDefault<z.ZodString>;
+    healthStrictSchema: z.ZodDefault<z.ZodBoolean>;
     url: z.ZodOptional<z.ZodString>;
     packageName: z.ZodOptional<z.ZodString>;
     template: z.ZodOptional<z.ZodString>;

package/dist/app-config/app.js

@@ -51,6 +51,21 @@ export const appConfig = z.object({
         env: ["APP_NAME"],
         doc: "User-facing display name of this app.",
     }),
+    pingMessage: z
+        .string()
+        .min(1)
+        .default("pong")
+        .meta({
+        env: ["PING_MESSAGE"],
+        doc: "Message returned by the framework ping route.",
+    }),
+    healthStrictSchema: z
+        .boolean()
+        .default(false)
+        .meta({
+        env: ["AGENT_NATIVE_HEALTH_STRICT_SCHEMA"],
+        doc: "Return HTTP 503 when the framework health schema probe is not ready.",
+    }),
     /**
      * The app's canonical public URL — what a user sees in a share link, an
      * email, or a JWT issuer claim.

package/dist/app-config/schema.d.ts

@@ -28,6 +28,8 @@ export declare const appConfigSchema: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         workspaceId: z.ZodOptional<z.ZodString>;
         name: z.ZodOptional<z.ZodString>;
+        pingMessage: z.ZodDefault<z.ZodString>;
+        healthStrictSchema: z.ZodDefault<z.ZodBoolean>;
         url: z.ZodOptional<z.ZodString>;
         packageName: z.ZodOptional<z.ZodString>;
         template: z.ZodOptional<z.ZodString>;

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/notifications/routes.d.ts

@@ -11,23 +11,23 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
-    count?: undefined;
-    updated: number;
     error?: undefined;
+    updated: number;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
     error: string;
     ok?: undefined;
-} | {
     count?: undefined;
-    updated?: undefined;
+} | {
     error?: undefined;
+    updated?: undefined;
     ok: boolean;
+    count?: undefined;
 }>>;

package/dist/observability/routes.d.ts

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

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/auth-plugin.js

@@ -1,19 +1,33 @@
 import { autoMountAuth } from "./auth.js";
 import { runBetterAuthMigrations } from "./better-auth-migrations.js";
-import { getH3App, awaitBootstrap, markDefaultPluginProvided, trackPluginInit, } from "./framework-request-handler.js";
+import { FRAMEWORK_AUTH_EARLY_PATHS, awaitBootstrap, getH3App, markDefaultPluginProvided, markFrameworkRoutesReadyBeforeBootstrap, trackPluginInit, } from "./framework-request-handler.js";
 export function createAuthPlugin(options) {
     return (nitroApp) => {
         markDefaultPluginProvided(nitroApp, "auth");
+        const isByoa = Boolean(options?.getSession);
+        const app = getH3App(nitroApp);
         const initPromise = (async () => {
+            // A BYOA provider owns its session lookup and login HTML. Mount it
+            // immediately so a transient database outage in Better Auth or another
+            // default plugin cannot make the custom sign-in document unavailable.
+            if (isByoa) {
+                // The guard is mounted synchronously by the BYOA branch above. Only
+                // after that synchronous registration is it safe to let these paths
+                // skip unrelated bootstrap work.
+                const mountPromise = autoMountAuth(app, options);
+                markFrameworkRoutesReadyBeforeBootstrap(nitroApp, FRAMEWORK_AUTH_EARLY_PATHS);
+                await mountPromise;
+                return;
+            }
             await awaitBootstrap(nitroApp);
             // guard:allow-boot-data-work — local/long-lived runtimes provision auth
             // before mounting routes; production functions are rejected by the
             // migration runner and use the release job instead.
             await runBetterAuthMigrations(nitroApp);
-            await autoMountAuth(getH3App(nitroApp), options);
+            await autoMountAuth(app, options);
         })();
         trackPluginInit(nitroApp, initPromise, {
-            paths: ["/_agent-native/auth"],
+            paths: [...FRAMEWORK_AUTH_EARLY_PATHS],
         });
     };
 }

package/dist/server/auth.js

@@ -60,6 +60,7 @@ import { getConfiguredAppBasePath } from "./app-base-path.js";
 import { getAppProductionUrl } from "./app-url.js";
 import { readAnalyticsAnonymousId, readFirstTouchAttribution, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { getAuthLoginMode } from "./auth-login-mode.js";
+import { injectBetaOptOutPersistence } from "./beta-opt-out-html.js";
 import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getAuthSecret, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
 import { BUILDER_CONNECT_PARAM, BUILDER_RELAY_PATH, BUILDER_RELAY_STATE_PARAM, verifyBuilderConnectTokenAndGetOwner, verifyBuilderPreviewRelayStateForCallback, } from "./builder-browser.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
@@ -346,7 +347,9 @@ export function getConfiguredLoginHtml(event) {
     const queryStart = url.indexOf("?");
     const rawPath = queryStart >= 0 ? url.slice(0, queryStart) : url;
     const loginHtml = config.getLoginHtml?.(event, rawPath) ?? config.loginHtml ?? null;
-    return loginHtml ? injectLoginSocialImageMeta(loginHtml, event) : null;
+    return loginHtml
+        ? injectLoginSocialImageMeta(injectBetaOptOutPersistence(loginHtml), event)
+        : null;
 }
 /**
  * True only when the request originates from the local machine — the raw
@@ -1934,7 +1937,7 @@ function injectLoginSocialImageMeta(loginHtml, event) {
         loginHtml.slice(headCloseIdx));
 }
 function loginHtmlResponse(loginHtml, event) {
-    return new Response(injectAnalyticsIntoHtml(injectLoginSocialImageMeta(loginHtml, event)), {
+    return new Response(injectAnalyticsIntoHtml(injectLoginSocialImageMeta(injectBetaOptOutPersistence(loginHtml), event)), {
         status: 200,
         headers: {
             "Content-Type": "text/html; charset=utf-8",

package/dist/server/beta-opt-out-html.d.ts

@@ -0,0 +1,7 @@
+export declare const BETA_OPT_OUT_PERSISTENCE_MARKER = "Persist the beta opt-out before authentication";
+/**
+ * Custom auth pages do not necessarily use the framework onboarding shell.
+ * Keep the production switcher's one-time opt-out behavior at the shared auth
+ * response boundary so those pages cannot drop the handoff before sign-in.
+ */
+export declare function injectBetaOptOutPersistence(loginHtml: string): string;

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

@@ -0,0 +1,190 @@
+import { 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"';
+const ENVIRONMENT_SWITCHER_SCRIPT_MARKER = 'data-agent-native-environment-switcher-script="1"';
+const EXISTING_ENVIRONMENT_SWITCHER_RE = /\bid=["']environment-switcher["']/;
+function insertBeforeClosingTag(html, fragment, closingTag) {
+    const closeIndex = html.indexOf(closingTag);
+    if (closeIndex < 0)
+        return html + fragment;
+    return html.slice(0, closeIndex) + fragment + html.slice(closeIndex);
+}
+const environmentSwitcherMarkup = `<div class="environment-switcher" id="environment-switcher" ${ENVIRONMENT_SWITCHER_MARKER} hidden>
+  <button type="button" class="environment-badge" id="environment-badge" aria-expanded="false" aria-controls="environment-popover">beta</button>
+  <div class="environment-popover" id="environment-popover" role="dialog" aria-labelledby="environment-popover-title" hidden>
+    <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>
+  </div>
+</div>`;
+const environmentSwitcherStyles = `<style ${ENVIRONMENT_SWITCHER_STYLE_MARKER}>
+  color-scheme: dark;
+  .environment-switcher {
+    position: fixed;
+    right: max(0.75rem, env(safe-area-inset-right));
+    bottom: max(0.75rem, env(safe-area-inset-bottom));
+    z-index: 100;
+  }
+  .environment-switcher[hidden],
+  .environment-popover[hidden] { display: none; }
+  .environment-badge {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    height: 1.5rem;
+    min-width: 0;
+    padding: 0 0.5rem;
+    background: CanvasText;
+    color: Canvas;
+    border: 1px solid color-mix(in srgb, Canvas 16%, transparent);
+    border-radius: 0.75rem;
+    box-shadow: 0 2px 8px color-mix(in srgb, CanvasText 25%, transparent);
+    font: inherit;
+    font-size: 0.6875rem;
+    font-weight: 600;
+    letter-spacing: 0.03125rem;
+    line-height: 1;
+    text-transform: uppercase;
+    cursor: pointer;
+  }
+  .environment-badge:hover,
+  .environment-badge[aria-expanded="true"] {
+    background: color-mix(in srgb, CanvasText 85%, Canvas);
+  }
+  .environment-badge:focus-visible,
+  .environment-production-link:focus-visible {
+    outline: 2px solid LinkText;
+    outline-offset: 2px;
+  }
+  .environment-popover {
+    position: absolute;
+    right: 0;
+    bottom: calc(100% + 0.5rem);
+    width: min(17.5rem, calc(100vw - 1.5rem));
+    padding: 1.25rem;
+    background: Canvas;
+    color: CanvasText;
+    border: 1px solid color-mix(in srgb, CanvasText 12%, transparent);
+    border-radius: 0.75rem;
+    box-shadow: 0 18px 50px color-mix(in srgb, CanvasText 42%, transparent);
+  }
+  .environment-popover-title { margin-bottom: 0.25rem; font-size: 0.875rem; font-weight: 600; line-height: 1.25rem; }
+  .environment-popover-copy { margin-bottom: 1rem; color: GrayText; font-size: 0.875rem; line-height: 1.25rem; }
+  .environment-production-link {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 2rem;
+    padding: 0.375rem 0.75rem;
+    color: CanvasText;
+    border: 1px solid color-mix(in srgb, CanvasText 16%, transparent);
+    border-radius: 0.375rem;
+    font-size: 0.8125rem;
+    text-decoration: none;
+  }
+  .environment-production-link:hover {
+    background: color-mix(in srgb, CanvasText 12%, Canvas);
+  }
+</style>`;
+const environmentSwitcherScript = `<script ${ENVIRONMENT_SWITCHER_SCRIPT_MARKER}>
+(function __anInitEnvironmentBadge() {
+  var switcher = document.getElementById('environment-switcher');
+  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;
+  if (window.parent !== window) return;
+
+  var betaHosts = ${JSON.stringify(ENVIRONMENT_BETA_HOSTS)};
+  var hostname = (window.location.hostname || '').toLowerCase().replace(/\\.$/, '');
+  var productionHost = hostname.indexOf('beta.') === 0 ? hostname.slice(5) : '';
+  if (!productionHost || betaHosts[productionHost] !== hostname) return;
+
+  try {
+    var productionUrl = new URL(window.location.href);
+    productionUrl.protocol = 'https:';
+    productionUrl.hostname = productionHost;
+    productionUrl.port = '';
+    productionUrl.searchParams.set(
+      ${JSON.stringify(BETA_OPT_OUT_QUERY_PARAM)},
+      String(Date.now() + ${BETA_OPT_OUT_DURATION_MS}),
+    );
+    productionLink.href = productionUrl.toString();
+  } catch (error) {
+    void error;
+    return;
+  }
+
+  function setOpen(open) {
+    popover.hidden = !open;
+    button.setAttribute('aria-expanded', String(open));
+  }
+
+  switcher.hidden = false;
+  button.addEventListener('click', function() {
+    setOpen(popover.hidden);
+  });
+  document.addEventListener('click', function(event) {
+    if (!switcher.contains(event.target)) setOpen(false);
+  });
+  document.addEventListener('keydown', function(event) {
+    if (event.key === 'Escape') setOpen(false);
+  });
+})();
+</script>`;
+const betaOptOutPersistenceScript = `<script data-agent-native-beta-opt-out>
+// ${BETA_OPT_OUT_PERSISTENCE_MARKER}.
+(function __anPersistBetaOptOut() {
+  try {
+    var optOutUrl = new URL(window.location.href);
+    var optOutValue = optOutUrl.searchParams.get(${JSON.stringify(BETA_OPT_OUT_QUERY_PARAM)});
+    if (optOutValue === null) return;
+    var optOutExpiry = Number(optOutValue);
+    var optOutStorageReady = false;
+    try {
+      if (Number.isFinite(optOutExpiry) && optOutExpiry > Date.now()) {
+        window.localStorage.setItem(
+          ${JSON.stringify(BETA_OPT_OUT_STORAGE_KEY)},
+          String(optOutExpiry),
+        );
+      }
+      optOutStorageReady = true;
+    } catch (error) {
+      void error;
+    }
+    if (optOutStorageReady) {
+      optOutUrl.searchParams.delete(${JSON.stringify(BETA_OPT_OUT_QUERY_PARAM)});
+      window.history.replaceState(null, '', optOutUrl.toString());
+    }
+  } catch (error) {
+    void error;
+  }
+})();
+</script>`;
+/**
+ * Custom auth pages do not necessarily use the framework onboarding shell.
+ * Keep the production switcher's one-time opt-out behavior at the shared auth
+ * response boundary so those pages cannot drop the handoff before sign-in.
+ */
+export function injectBetaOptOutPersistence(loginHtml) {
+    let html = loginHtml;
+    if (!html.includes(BETA_OPT_OUT_PERSISTENCE_MARKER)) {
+        html = insertBeforeClosingTag(html, betaOptOutPersistenceScript, "</body>");
+    }
+    // The standard onboarding shell already owns this markup, style, and
+    // initializer. Custom login pages need the shared switcher, but adding a
+    // second copy would create duplicate IDs and event handlers.
+    if (EXISTING_ENVIRONMENT_SWITCHER_RE.test(html))
+        return html;
+    if (!html.includes(ENVIRONMENT_SWITCHER_STYLE_MARKER)) {
+        html = insertBeforeClosingTag(html, environmentSwitcherStyles, "</head>");
+    }
+    if (!html.includes(ENVIRONMENT_SWITCHER_MARKER)) {
+        html = insertBeforeClosingTag(html, environmentSwitcherMarkup, "</body>");
+    }
+    if (!html.includes(ENVIRONMENT_SWITCHER_SCRIPT_MARKER)) {
+        html = insertBeforeClosingTag(html, environmentSwitcherScript, "</body>");
+    }
+    return html;
+}

package/dist/server/core-routes-plugin.js

@@ -51,7 +51,7 @@ import { probeDbPressure } from "./db-pressure.js";
 import { resolveDeployEnvironment, resolveServerRelease, } from "./deploy-environment.js";
 import { createEmbedStartRouteHandler } from "./embed-route.js";
 import { shouldReportError } from "./error-noise-filter.js";
-import { getH3App, awaitBootstrap, markDefaultPluginProvided, trackPluginInit, } from "./framework-request-handler.js";
+import { FRAMEWORK_AUTH_EARLY_PATHS, getH3App, awaitBootstrap, markDefaultPluginProvided, markFrameworkRoutesReadyBeforeBootstrap, trackPluginInit, } from "./framework-request-handler.js";
 import { createGatewayAccessCheckHandler } from "./gateway-access-check.js";
 import { getAppBasePath, getOrigin } from "./google-oauth.js";
 import { createGoogleRealtimeSessionHandler } from "./google-realtime-session.js";
@@ -939,9 +939,21 @@ export function createCoreRoutesPlugin(options = {}) {
         });
         trackPluginInit(nitroApp, initPromise, {
             paths: [FRAMEWORK_ROUTE_PREFIX, "/mcp", "/.well-known"],
+            // Liveness and BYOA auth routes are mounted before the DB-dependent
+            // bootstrap below. The broad core entry must not hold those routes while
+            // an unrelated migration or connection pool is unavailable.
+            excludedPaths: [
+                `${FRAMEWORK_ROUTE_PREFIX}/ping`,
+                `${FRAMEWORK_ROUTE_PREFIX}/health`,
+                ...FRAMEWORK_AUTH_EARLY_PATHS,
+            ],
         });
         try {
             const P = FRAMEWORK_ROUTE_PREFIX;
+            markFrameworkRoutesReadyBeforeBootstrap(nitroApp, [
+                ...(!options.disablePing ? [`${P}/ping`] : []),
+                ...(!options.disableHealth ? [`${P}/health`] : []),
+            ]);
             // Keep the framework-owned S3-compatible provider available even when an
             // app does not mount the optional onboarding plugin. The settings CTA and
             // the upload route share this registry. An app may register its own
@@ -962,6 +974,52 @@ export function createCoreRoutesPlugin(options = {}) {
                 }
                 return EMPTY_SPECULATION_RULES;
             }));
+            // Keep liveness independent from the rest of framework bootstrap. A
+            // cold-start database failure must report a useful ping/health result,
+            // not prevent these handlers from being registered at all.
+            if (!options.disablePing) {
+                getH3App(nitroApp).use(`${P}/ping`, defineEventHandler((event) => {
+                    const message = getAppConfig().app.pingMessage;
+                    const configuration = event.url?.searchParams.get("configuration") === "1" ||
+                        event.url?.searchParams.get("configuration") === "true";
+                    if (!configuration)
+                        return { message };
+                    const requirements = {
+                        ...(event.url?.searchParams.get("auth") === "0"
+                            ? { authEnabled: false }
+                            : {}),
+                        ...(event.url?.searchParams.get("database") === "0"
+                            ? { databaseRequired: false }
+                            : {}),
+                    };
+                    return {
+                        message,
+                        configuration: getRuntimeConfigReport(process.env, requirements, {
+                            phase: "runtime",
+                            appName: getAppConfig().app.name,
+                        }),
+                    };
+                }));
+            }
+            if (!options.disableHealth) {
+                getH3App(nitroApp).use(`${P}/health`, defineEventHandler(async (event) => {
+                    setResponseHeader(event, "cache-control", "no-store");
+                    const schema = event.url?.searchParams.get("schema") === "1" ||
+                        event.url?.searchParams.get("schema") === "true";
+                    const strict = event.url?.searchParams.get("strict") === "1" ||
+                        event.url?.searchParams.get("strict") === "true" ||
+                        getAppConfig().app.healthStrictSchema;
+                    const pressure = event.url?.searchParams.get("pressure") === "1" ||
+                        event.url?.searchParams.get("pressure") === "true";
+                    const result = await runDbHealthProbe(getDbExec, {
+                        schema,
+                        pressure,
+                    });
+                    if (strict && !result.ready)
+                        setResponseStatus(event, 503);
+                    return result;
+                }));
+            }
             await awaitBootstrap(nitroApp);
             const runBootDatabaseWork = shouldRunCoreRouteBootDatabaseWork();
             const { persistedEnvVars, builderDisconnected } = runBootDatabaseWork
@@ -1264,33 +1322,6 @@ export function createCoreRoutesPlugin(options = {}) {
                     getH3App(nitroApp).use(route, createPollEventsHandler());
                 }
             }
-            // Ping
-            if (!options.disablePing) {
-                getH3App(nitroApp).use(`${P}/ping`, defineEventHandler((event) => {
-                    const message = process.env.PING_MESSAGE ?? "pong";
-                    const configuration = event.url?.searchParams.get("configuration") === "1" ||
-                        event.url?.searchParams.get("configuration") === "true";
-                    if (!configuration)
-                        return { message };
-                    // Custom required keys must come from server-side app configuration;
-                    // never let an anonymous caller turn this into an env-name oracle.
-                    const requirements = {
-                        ...(event.url?.searchParams.get("auth") === "0"
-                            ? { authEnabled: false }
-                            : {}),
-                        ...(event.url?.searchParams.get("database") === "0"
-                            ? { databaseRequired: false }
-                            : {}),
-                    };
-                    return {
-                        message,
-                        configuration: getRuntimeConfigReport(process.env, requirements, {
-                            phase: "runtime",
-                            appName: process.env.APP_NAME,
-                        }),
-                    };
-                }));
-            }
             // ─── Durable sandbox execution processor ─────────────────────────
             // Self-fired by run-code's background queue (see
             // coding-tools/sandbox/background.ts): the enqueueing request POSTs here
@@ -1370,37 +1401,6 @@ export function createCoreRoutesPlugin(options = {}) {
                     }, 30_000); // Check every 30s but only sweep once per 2min
                 }, 25_000); // Start 25s after init (after the agent sweeps)
             })();
-            // Health + DB warmup — liveness probe that touches the database so
-            // uptime monitors and the keep-warm cron prevent a scale-to-zero
-            // serverless DB (e.g. Neon) from cold-starting on the next real
-            // request. Public, side-effect free, and never cached. Add ?schema=1
-            // for metadata-only schema checks, and ?strict=1 to turn a not-ready
-            // DB/schema probe into a failing HTTP status for monitors.
-            if (!options.disableHealth) {
-                getH3App(nitroApp).use(`${P}/health`, defineEventHandler(async (event) => {
-                    setResponseHeader(event, "cache-control", "no-store");
-                    const schema = event.url?.searchParams.get("schema") === "1" ||
-                        event.url?.searchParams.get("schema") === "true";
-                    const strict = event.url?.searchParams.get("strict") === "1" ||
-                        event.url?.searchParams.get("strict") === "true" ||
-                        process.env.AGENT_NATIVE_HEALTH_STRICT_SCHEMA === "true";
-                    // Off by default: the one-minute warm cron does not need it, and
-                    // an extra `pg_stat_activity` read every minute per app is waste.
-                    // Pressure deliberately does NOT change `ready` or the status
-                    // code — a pressured database is still serving, and an uptime
-                    // monitor that pages on it would learn to ignore this route. The
-                    // fleet audit reads the counters and decides.
-                    const pressure = event.url?.searchParams.get("pressure") === "1" ||
-                        event.url?.searchParams.get("pressure") === "true";
-                    const result = await runDbHealthProbe(getDbExec, {
-                        schema,
-                        pressure,
-                    });
-                    if (strict && !result.ready)
-                        setResponseStatus(event, 503);
-                    return result;
-                }));
-            }
             getH3App(nitroApp).use(`${P}/debug/runtime`, defineEventHandler(async (event) => {
                 setResponseHeader(event, "cache-control", "no-store");
                 const session = await getSession(event).catch(() => null);

package/dist/server/create-server.d.ts

@@ -14,7 +14,7 @@ export interface CreateServerOptions {
     cors?: Record<string, unknown> | false;
     /** JSON body parser limit. Kept for API compatibility (H3 uses readBody). */
     jsonLimit?: string;
-    /** Custom ping message. Default: reads PING_MESSAGE env var, falls back to "pong" */
+    /** Custom ping message. Default: reads the shared app config. */
     pingMessage?: string;
     /** Disable the /_agent-native/ping health check. Default: false */
     disablePing?: boolean;

package/dist/server/create-server.js

@@ -1,4 +1,5 @@
 import { createApp, createRouter, defineEventHandler, getMethod, getRequestHeader, setResponseHeader, setResponseStatus, } from "h3";
+import { getAppConfig } from "../app-config/index.js";
 import { getOrgContext } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
@@ -109,7 +110,7 @@ export function createServer(options = {}) {
     // Health check
     if (!options.disablePing) {
         router.get("/_agent-native/ping", defineEventHandler((event) => {
-            const message = options.pingMessage ?? process.env.PING_MESSAGE ?? "pong";
+            const message = options.pingMessage ?? getAppConfig().app.pingMessage;
             const configuration = event.url?.searchParams.get("configuration") === "1" ||
                 event.url?.searchParams.get("configuration") === "true";
             if (!configuration)
@@ -128,7 +129,7 @@ export function createServer(options = {}) {
                 message,
                 configuration: getRuntimeConfigReport(process.env, requirements, {
                     phase: "runtime",
-                    appName: process.env.APP_NAME,
+                    appName: getAppConfig().app.name,
                 }),
             };
         }));

package/dist/server/embedded.js

@@ -71,17 +71,24 @@ function markEmbeddedPluginStems(nitroApp) {
 export async function mountAgentNativeEmbedded(nitroApp, options = {}) {
     configureAgentNativeEmbeddedEnvironment(options);
     markEmbeddedPluginStems(nitroApp);
+    // The auth plugin tracks its async initialization itself. Do not await the
+    // factory call here: with default Better Auth, its DB bootstrap can be the
+    // thing that is unavailable while public liveness routes still need to
+    // mount below.
+    createAuthPlugin(createAgentNativeEmbeddedAuthOptions(options.auth))(nitroApp);
+    // Mount framework auth and liveness before waiting on the host application's
+    // bootstrap. The embedded plugin tracks its full init as an unscoped promise,
+    // so early requests deliberately skip that promise.
+    if (options.coreRoutes !== false) {
+        await createCoreRoutesPlugin(options.coreRoutes ?? undefined)(nitroApp);
+    }
     await awaitBootstrap(nitroApp);
-    await createAuthPlugin(createAgentNativeEmbeddedAuthOptions(options.auth))(nitroApp);
     if (options.sentry !== false) {
         await createSentryPlugin()(nitroApp);
     }
     if (options.org === true) {
         await createOrgPlugin()(nitroApp);
     }
-    if (options.coreRoutes !== false) {
-        await createCoreRoutesPlugin(options.coreRoutes ?? undefined)(nitroApp);
-    }
     if (options.resources !== false) {
         await createResourcesPlugin()(nitroApp);
     }

package/dist/server/framework-request-handler.d.ts

@@ -13,6 +13,7 @@
  */
 import type { EventHandler } from "h3";
 declare const FRAMEWORK_PREFIX = "/_agent-native";
+export declare const FRAMEWORK_AUTH_EARLY_PATHS: readonly ["/_agent-native/auth", "/sign-in", "/_agent-native/sign-in", "/_agent-native/login", "/_agent-native/signup", "/login", "/signup"];
 /**
  * Wrapper around Nitro's h3 instance that exposes a v1-style `.use()` API
  * for registering path-prefix middleware.
@@ -32,6 +33,13 @@ export interface H3AppShim {
  * auto-mount a generic default over the app's custom implementation.
  */
 export declare function markDefaultPluginProvided(nitroApp: any, stem: string): void;
+/**
+ * Mark routes that are mounted without waiting for unrelated default-plugin
+ * bootstrap. BYOA auth uses this for its cacheable login document: waiting
+ * for Better Auth or another DB-backed plugin turns an available login form
+ * into a serverless 502 during a cold-start database outage.
+ */
+export declare function markFrameworkRoutesReadyBeforeBootstrap(nitroApp: any, paths: readonly string[]): void;
 /**
  * Get (or create) the shared H3 app wrapper for a nitroApp. Plugins use this
  * to register routes via `.use(path, handler)`.
@@ -65,12 +73,15 @@ export declare function awaitBootstrap(nitroApp: any): Promise<void>;
  */
 export declare function trackPluginInit(nitroApp: any, promise: Promise<void>, options?: {
     paths?: string[];
+    excludedPaths?: string[];
 }): void;
 /**
  * Await all tracked plugin initializations. Called by the readiness gate
  * middleware before dispatching framework routes.
  */
-export declare function awaitPluginsReady(nitroApp: any, reqPath?: string): Promise<void>;
+export declare function awaitPluginsReady(nitroApp: any, reqPath?: string, options?: {
+    skipUnscoped?: boolean;
+}): Promise<void>;
 /**
  * Load a workspace-core's `/server` entry, transparently handling TS source.
  *

package/dist/server/framework-request-handler.js

@@ -1,6 +1,7 @@
 import { setResponseHeader, setResponseStatus } from "h3";
 import { getMissingDefaultPlugins } from "../deploy/route-discovery.js";
 import { MCP_PUBLIC_ROUTE_PREFIX } from "../mcp/route-paths.js";
+import { SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, } from "../shared/sign-in-journey.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
 import { captureError } from "./capture-error.js";
 import { createCsrfMiddleware } from "./csrf.js";
@@ -16,8 +17,23 @@ const PLUGIN_READY_KEY = "_agentNativePluginReadyPromise";
 const PLUGIN_READY_PLACEHOLDERS_KEY = "_agentNativePluginReadyPlaceholders";
 const PLUGIN_FAILED_KEY = "_agentNativePluginInitFailures";
 const PROVIDED_PLUGIN_STEMS_KEY = "_agentNativeProvidedPluginStems";
+const EARLY_FRAMEWORK_PATHS_KEY = "_agentNativeEarlyFrameworkPaths";
 const MIDDLEWARE_DISPATCHER_PATCHED_KEY = "_agentNativeMiddlewareDispatcherPatched";
 const REQUEST_CONTEXT_BOUNDARY_KEY = "_agentNativeRequestContextBoundary";
+const CANONICAL_AUTH_EARLY_PATHS = [
+    SIGN_IN_ENTRY_PATH,
+    "/login",
+    "/signup",
+];
+export const FRAMEWORK_AUTH_EARLY_PATHS = [
+    `${FRAMEWORK_PREFIX}/auth`,
+    SIGN_IN_ENTRY_PATH,
+    SIGN_IN_LEGACY_ENTRY_PATH,
+    `${FRAMEWORK_PREFIX}/login`,
+    `${FRAMEWORK_PREFIX}/signup`,
+    "/login",
+    "/signup",
+];
 function getAppBasePath() {
     return getConfiguredAppBasePath();
 }
@@ -27,7 +43,8 @@ function pathMatchesPrefix(reqPath, prefix) {
 function supportsAppBasePathMount(path) {
     return (pathMatchesPrefix(path, FRAMEWORK_PREFIX) ||
         pathMatchesPrefix(path, WELL_KNOWN_PREFIX) ||
-        pathMatchesPrefix(path, MCP_PUBLIC_ROUTE_PREFIX));
+        pathMatchesPrefix(path, MCP_PUBLIC_ROUTE_PREFIX) ||
+        CANONICAL_AUTH_EARLY_PATHS.some((authPath) => pathMatchesPrefix(path, authPath)));
 }
 function resolveMountMatch(reqPath, path) {
     if (pathMatchesPrefix(reqPath, path)) {
@@ -62,6 +79,23 @@ export function markDefaultPluginProvided(nitroApp, stem) {
     provided.add(stem);
     nitroApp[PROVIDED_PLUGIN_STEMS_KEY] = provided;
 }
+/**
+ * Mark routes that are mounted without waiting for unrelated default-plugin
+ * bootstrap. BYOA auth uses this for its cacheable login document: waiting
+ * for Better Auth or another DB-backed plugin turns an available login form
+ * into a serverless 502 during a cold-start database outage.
+ */
+export function markFrameworkRoutesReadyBeforeBootstrap(nitroApp, paths) {
+    if (!nitroApp)
+        return;
+    const existing = nitroApp[EARLY_FRAMEWORK_PATHS_KEY] ??
+        new Set();
+    for (const path of paths) {
+        if (path)
+            existing.add(path);
+    }
+    nitroApp[EARLY_FRAMEWORK_PATHS_KEY] = existing;
+}
 /**
  * Get (or create) the shared H3 app wrapper for a nitroApp. Plugins use this
  * to register routes via `.use(path, handler)`.
@@ -119,6 +153,9 @@ export function getH3App(nitroApp) {
         registerMiddleware(nitroApp, MCP_PUBLIC_ROUTE_PREFIX, readinessGate, {
             prepend: true,
         });
+        for (const path of CANONICAL_AUTH_EARLY_PATHS) {
+            registerMiddleware(nitroApp, path, readinessGate, { prepend: true });
+        }
         // CSRF (see csrf.ts): registered here — synchronously, on the very
         // first `getH3App()` call for this nitroApp — rather than inside
         // createCoreRoutesPlugin's own async init chain. Real deployments mount
@@ -152,7 +189,8 @@ export function getH3App(nitroApp) {
             const reqPath = event.url?.pathname ?? "";
             if (resolveMountMatch(reqPath, FRAMEWORK_PREFIX) ||
                 resolveMountMatch(reqPath, WELL_KNOWN_PREFIX) ||
-                resolveMountMatch(reqPath, MCP_PUBLIC_ROUTE_PREFIX)) {
+                resolveMountMatch(reqPath, MCP_PUBLIC_ROUTE_PREFIX) ||
+                FRAMEWORK_AUTH_EARLY_PATHS.some((path) => resolveMountMatch(reqPath, path))) {
                 const startedAt = Date.now();
                 try {
                     await awaitFrameworkRoutesReadyForRequest(nitroApp, reqPath);
@@ -276,9 +314,15 @@ async function awaitFrameworkRoutesReadyForRequest(nitroApp, reqPath) {
         return await Promise.race([
             (async () => {
                 const bootstrapPromise = nitroApp[BOOTSTRAP_PROMISE_KEY];
-                if (bootstrapPromise)
+                const earlyPaths = nitroApp[EARLY_FRAMEWORK_PATHS_KEY];
+                const canDispatchBeforeBootstrap = Boolean(earlyPaths?.size &&
+                    Array.from(earlyPaths).some((path) => resolveMountMatch(reqPath, path)));
+                if (bootstrapPromise && !canDispatchBeforeBootstrap) {
                     await bootstrapPromise;
-                await awaitPluginsReady(nitroApp, reqPath);
+                }
+                await awaitPluginsReady(nitroApp, reqPath, {
+                    skipUnscoped: canDispatchBeforeBootstrap,
+                });
                 return true;
             })(),
             new Promise((resolve) => {
@@ -341,6 +385,7 @@ export function trackPluginInit(nitroApp, promise, options = {}) {
     const entry = {
         promise: safe,
         paths: options.paths?.filter(Boolean),
+        excludedPaths: options.excludedPaths?.filter(Boolean),
     };
     const existing = nitroApp[PLUGIN_READY_KEY];
     if (existing) {
@@ -349,9 +394,9 @@ export function trackPluginInit(nitroApp, promise, options = {}) {
     else {
         nitroApp[PLUGIN_READY_KEY] = [entry];
     }
-    installPluginReadyPlaceholders(nitroApp, entry.paths);
+    installPluginReadyPlaceholders(nitroApp, entry.paths, entry.excludedPaths);
 }
-function installPluginReadyPlaceholders(nitroApp, paths) {
+function installPluginReadyPlaceholders(nitroApp, paths, excludedPaths) {
     if (!paths?.length)
         return;
     const existing = nitroApp[PLUGIN_READY_PLACEHOLDERS_KEY];
@@ -364,6 +409,9 @@ function installPluginReadyPlaceholders(nitroApp, paths) {
         registerMiddleware(nitroApp, path, (async (event) => {
             const eventAny = event;
             const reqPath = eventAny.context?._mountedPathname ?? event.url?.pathname ?? path;
+            if (excludedPaths?.some((excludedPath) => resolveMountMatch(reqPath, excludedPath))) {
+                return undefined;
+            }
             const ready = await awaitFrameworkRoutesReadyForRequest(nitroApp, reqPath);
             if (!ready) {
                 // Boot is still running and we are out of budget. Answer now, while
@@ -425,14 +473,16 @@ function debugClientAbort(args) {
  * Await all tracked plugin initializations. Called by the readiness gate
  * middleware before dispatching framework routes.
  */
-export async function awaitPluginsReady(nitroApp, reqPath) {
+export async function awaitPluginsReady(nitroApp, reqPath, options = {}) {
     const entries = nitroApp[PLUGIN_READY_KEY];
     if (!entries?.length)
         return;
     const relevant = reqPath
-        ? entries.filter((entry) => entry.paths?.length
-            ? entry.paths.some((path) => resolveMountMatch(reqPath, path))
-            : true)
+        ? entries.filter((entry) => !(options.skipUnscoped && !entry.paths?.length) &&
+            !entry.excludedPaths?.some((path) => resolveMountMatch(reqPath, path)) &&
+            (entry.paths?.length
+                ? entry.paths.some((path) => resolveMountMatch(reqPath, path))
+                : true))
         : entries;
     if (relevant.length) {
         await Promise.all(relevant.map((entry) => entry.promise));

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.0.0-beta-20260820052446",
+  "version": "0.0.0-beta-20260820094341",
   "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": {
@@ -427,8 +427,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.32",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.5",
-    "@agent-native/toolkit": "^0.16.7"
+    "@agent-native/toolkit": "^0.16.7",
+    "@agent-native/recap-cli": "0.5.5"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",