@agent-native/core 0.161.22 → 0.162.0

package/dist/client/onboarding/FirstRunOnboarding.js

@@ -1,7 +1,7 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Skeleton } from "@agent-native/toolkit/ui/skeleton";
 import { IconArrowRight, IconBrandGithub, IconCheck, IconExternalLink, IconInfoCircle, IconKey, IconLoader2, IconSearch, } from "@tabler/icons-react";
-import React, { useMemo, useState } from "react";
+import React, { useCallback, useMemo, useState } from "react";
 import { docsUrl } from "../../shared/docs-url.js";
 import { appPath } from "../api-path.js";
 import { Tooltip, TooltipContent, TooltipTrigger, } from "../components/ui/tooltip.js";
@@ -28,7 +28,14 @@ const BUILDER_MORE_SERVICES = [
 ];
 export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegrations(), initialFirstRun = false, } = {}) {
     const previewMode = useOnboardingPreviewMode();
-    const { firstRun, loading, error, profile, completeFirstRun } = useOnboarding({ preview: previewMode, initialFirstRun });
+    const { firstRun, loading, error, profile, completeFirstRun, completeFirstRunError, } = useOnboarding({ preview: previewMode, initialFirstRun });
+    // completeFirstRun() rejects on failure — swallow it here so a Skip/
+    // Continue click never becomes an unhandled rejection; completeFirstRunError
+    // (rendered below) is the real signal, and the user stays on this screen
+    // to retry instead of being bounced to an unrelated error screen.
+    const finishOnboarding = useCallback(() => {
+        completeFirstRun().catch(() => { });
+    }, [completeFirstRun]);
     const [screen, setScreen] = useState("intro");
     const [extensionIndex, setExtensionIndex] = useState(0);
     const [integrationQuery, setIntegrationQuery] = useState("");
@@ -86,15 +93,15 @@ export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegr
             trackingFlow: "connect_llm",
         });
     };
-    const handleOpenSettings = async () => {
+    const handleOpenSettings = () => {
         window.dispatchEvent(new CustomEvent("agent-panel:open-settings", {
             detail: { section: "integrations" },
         }));
-        await completeFirstRun();
+        finishOnboarding();
     };
     const handleFinish = () => {
         if (extensions.length === 0) {
-            void completeFirstRun();
+            finishOnboarding();
             return;
         }
         setExtensionIndex(0);
@@ -155,7 +162,7 @@ export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegr
     if (screen === "extension") {
         const extension = extensions[extensionIndex];
         if (!extension) {
-            void completeFirstRun();
+            finishOnboarding();
             return null;
         }
         const Extension = extension.component;
@@ -164,9 +171,9 @@ export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegr
                 setExtensionIndex((current) => current + 1);
                 return;
             }
-            void completeFirstRun();
+            finishOnboarding();
         };
-        return (_jsx(Extension, { onComplete: advanceExtension, onSkip: () => void completeFirstRun() }));
+        return (_jsxs(_Fragment, { children: [_jsx(Extension, { onComplete: advanceExtension, onSkip: finishOnboarding }), completeFirstRunError && (_jsx(FirstRunCompletionError, { message: completeFirstRunError, onRetry: finishOnboarding }))] }));
     }
     if (screen === "intro") {
         return (_jsx(OnboardingShell, { profile: profile, screen: "intro", children: _jsxs("div", { className: "mx-auto flex w-full max-w-lg flex-col items-center text-center", children: [_jsxs("h1", { className: "text-3xl font-semibold tracking-[-0.05em] sm:text-4xl", children: ["Free forever.", _jsx("br", {}), _jsx("span", { className: "text-primary", children: "Open source for life." })] }), _jsxs("div", { className: "mt-7 grid w-full gap-2 text-left sm:grid-cols-3", children: [_jsxs("div", { className: "rounded-lg bg-muted/35 px-3 py-3", children: [_jsx("p", { className: "text-xs font-medium", children: "Fully customizable" }), _jsx("p", { className: "mt-1 text-[11px] leading-4 text-muted-foreground", children: "Change the UI, code, and behavior." })] }), _jsxs("div", { className: "rounded-lg bg-muted/35 px-3 py-3", children: [_jsx("p", { className: "text-xs font-medium", children: "Bring your own keys" }), _jsx("p", { className: "mt-1 text-[11px] leading-4 text-muted-foreground", children: "Use your own providers and accounts." })] }), _jsxs("div", { className: "rounded-lg bg-muted/35 px-3 py-3", children: [_jsx("p", { className: "text-xs font-medium", children: "Build your own" }), _jsx("p", { className: "mt-1 text-[11px] leading-4 text-muted-foreground", children: "Mix and match toolkit pieces in your own apps." })] })] }), _jsxs("button", { type: "button", className: cn(primaryButtonClass, "mt-6"), onClick: () => setScreen("choice"), children: ["Continue", _jsx(IconArrowRight, { size: 15 })] }), _jsxs("a", { href: "https://github.com/builderio/agent-native", target: "_blank", rel: "noreferrer", className: "mt-3 inline-flex items-center gap-1.5 text-xs text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [_jsx(IconBrandGithub, { size: 14 }), _jsx("span", { children: "View source" }), _jsx(IconExternalLink, { size: 13 })] })] }) }));
@@ -204,29 +211,29 @@ export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegr
     if (screen === "connecting") {
         return (_jsx(OnboardingShell, { profile: profile, screen: "choice", children: _jsxs("div", { className: "mx-auto flex w-full max-w-md flex-col items-center text-center", children: [_jsx("div", { className: "flex size-10 items-center justify-center rounded-full bg-primary/10 text-primary", children: _jsx(IconLoader2, { className: "animate-spin", size: 19 }) }), _jsx("h1", { className: "mt-5 text-xl font-semibold tracking-[-0.04em]", children: "Connecting Builder.io free credits" }), _jsx("p", { className: "mt-2 text-sm text-muted-foreground", children: "Finish the one-click connection in the new window." }), _jsxs("div", { className: "mt-7 w-full rounded-xl bg-muted/35 p-4 text-left", children: [_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx(Skeleton, { className: "h-3 w-28" }), _jsx(Skeleton, { className: "h-5 w-16 rounded-full" })] }), _jsx(Skeleton, { className: "mt-4 h-8 w-full" }), _jsxs("div", { className: "mt-3 grid grid-cols-3 gap-2", children: [_jsx(Skeleton, { className: "h-7 w-full" }), _jsx(Skeleton, { className: "h-7 w-full" }), _jsx(Skeleton, { className: "h-7 w-full" })] })] }), connectFlow.error && (_jsxs("div", { className: "mt-4 flex flex-col items-center gap-2", children: [_jsx("p", { className: "text-xs text-destructive", children: connectFlow.error }), _jsx("button", { type: "button", className: secondaryButtonClass, onClick: () => setScreen("choice"), children: "Try again" })] }))] }) }));
     }
-    return (_jsx(OnboardingShell, { profile: profile, screen: "ready", children: _jsxs("div", { className: "mx-auto flex w-full max-w-2xl flex-col items-center text-center", children: [_jsx("div", { className: "flex size-12 items-center justify-center rounded-2xl bg-primary/10 text-primary", children: _jsx(IconCheck, { size: 20 }) }), _jsx("h1", { className: "mt-5 text-xl font-semibold tracking-[-0.04em]", children: "Your agent is ready." }), _jsx("p", { className: "mt-2 max-w-md text-sm leading-6 text-muted-foreground", children: "Start with a chat, then connect more tools whenever you need them." }), _jsx("div", { className: "mt-7 grid w-full gap-2 text-left sm:grid-cols-3", children: (skipIntegrations
-                        ? [
-                            [
-                                "Workflow actions",
-                                "Use the app's buttons and sidebar to run the workflow.",
-                            ],
-                            [
-                                "AI sidebar",
-                                "Ask the agent to review or refine a step in context.",
-                            ],
-                            [
-                                "Flexible providers",
-                                "Use Builder.io free credits or your own keys.",
-                            ],
-                        ]
-                        : [
-                            ["Chat + actions", "Ask your agent to work across the app."],
-                            ["Agent integrations", "Connect tools from Settings anytime."],
-                            [
-                                "Flexible providers",
-                                "Use Builder.io free credits or your own keys.",
-                            ],
-                        ]).map(([title, description]) => (_jsxs("div", { className: "rounded-xl bg-muted/35 px-4 py-4", children: [_jsx("span", { className: "flex size-7 items-center justify-center rounded-full bg-primary/10 text-primary", children: _jsx(IconCheck, { size: 14 }) }), _jsx("p", { className: "mt-3 text-sm font-medium", children: title }), _jsx("p", { className: "mt-1 text-xs leading-5 text-muted-foreground", children: description })] }, title))) }), _jsxs("button", { type: "button", "data-testid": "first-run-open-app", className: cn(primaryButtonClass, "mt-7"), onClick: handleFinish, children: ["Open app", _jsx(IconArrowRight, { size: 15 })] })] }) }));
+    return (_jsxs(OnboardingShell, { profile: profile, screen: "ready", children: [_jsxs("div", { className: "mx-auto flex w-full max-w-2xl flex-col items-center text-center", children: [_jsx("div", { className: "flex size-12 items-center justify-center rounded-2xl bg-primary/10 text-primary", children: _jsx(IconCheck, { size: 20 }) }), _jsx("h1", { className: "mt-5 text-xl font-semibold tracking-[-0.04em]", children: "Your agent is ready." }), _jsx("p", { className: "mt-2 max-w-md text-sm leading-6 text-muted-foreground", children: "Start with a chat, then connect more tools whenever you need them." }), _jsx("div", { className: "mt-7 grid w-full gap-2 text-left sm:grid-cols-3", children: (skipIntegrations
+                            ? [
+                                [
+                                    "Workflow actions",
+                                    "Use the app's buttons and sidebar to run the workflow.",
+                                ],
+                                [
+                                    "AI sidebar",
+                                    "Ask the agent to review or refine a step in context.",
+                                ],
+                                [
+                                    "Flexible providers",
+                                    "Use Builder.io free credits or your own keys.",
+                                ],
+                            ]
+                            : [
+                                ["Chat + actions", "Ask your agent to work across the app."],
+                                ["Agent integrations", "Connect tools from Settings anytime."],
+                                [
+                                    "Flexible providers",
+                                    "Use Builder.io free credits or your own keys.",
+                                ],
+                            ]).map(([title, description]) => (_jsxs("div", { className: "rounded-xl bg-muted/35 px-4 py-4", children: [_jsx("span", { className: "flex size-7 items-center justify-center rounded-full bg-primary/10 text-primary", children: _jsx(IconCheck, { size: 14 }) }), _jsx("p", { className: "mt-3 text-sm font-medium", children: title }), _jsx("p", { className: "mt-1 text-xs leading-5 text-muted-foreground", children: description })] }, title))) }), _jsxs("button", { type: "button", "data-testid": "first-run-open-app", className: cn(primaryButtonClass, "mt-7"), onClick: handleFinish, children: ["Open app", _jsx(IconArrowRight, { size: 15 })] })] }), completeFirstRunError && (_jsx(FirstRunCompletionError, { message: completeFirstRunError, onRetry: finishOnboarding }))] }));
 }
 function OnboardingShell({ profile, screen, footer, children, }) {
     return (_jsxs("div", { className: "fixed inset-0 z-[100] flex h-full min-h-0 flex-col bg-background text-foreground", "data-onboarding-screen": screen, role: "dialog", "aria-modal": "true", "aria-label": `${profile?.appName ?? "Your app"} setup`, children: [_jsx("div", { className: "h-0.5 shrink-0 bg-muted", "data-testid": "onboarding-progress", children: _jsx("div", { className: "h-full bg-primary transition-[width] duration-200", style: {
@@ -266,6 +273,13 @@ function CapabilityInfoButton({ capability, ariaLabel, }) {
     return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": ariaLabel, className: "inline-flex size-4 items-center justify-center rounded-full text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", onClick: (event) => event.stopPropagation(), onKeyDown: (event) => event.stopPropagation(), children: _jsx(IconInfoCircle, { size: 13 }) }) }), _jsx(TooltipContent, { side: "top", className: "max-w-xs text-xs", children: capability.why })] }));
 }
 const primaryButtonClass = "inline-flex min-h-9 items-center justify-center gap-2 rounded-lg bg-primary px-4 text-xs font-medium text-primary-foreground shadow-sm transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+/** Inline failure signal for a failed completeFirstRun() call — keeps the
+ *  user on their current screen with a way forward, instead of swapping to
+ *  an unrelated full-screen error or leaving Skip/Continue looking like it
+ *  did nothing. */
+function FirstRunCompletionError({ message, onRetry, }) {
+    return (_jsxs("div", { className: "fixed inset-x-0 bottom-4 z-50 mx-auto flex w-fit max-w-[90vw] items-center gap-3 rounded-lg border border-destructive/30 bg-background px-4 py-2 text-xs shadow-lg", children: [_jsx("span", { className: "text-destructive", children: message }), _jsx("button", { type: "button", className: "font-medium underline underline-offset-2 hover:no-underline", onClick: onRetry, children: "Try again" })] }));
+}
 const secondaryButtonClass = "inline-flex min-h-9 items-center justify-center gap-2 rounded-lg border border-border bg-background px-4 text-xs font-medium text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
 function compareUrl(value) {
     try {

package/dist/client/onboarding/use-onboarding.d.ts

@@ -30,8 +30,15 @@ export interface UseOnboardingResult {
     reopen: () => Promise<void>;
     /** True until the post-signup full-screen flow is completed. */
     firstRun: boolean;
-    /** Clear the post-signup full-screen flow marker. */
+    /** Clear the post-signup full-screen flow marker. Rejects instead of
+     *  resolving silently when the server call fails — see
+     *  `completeFirstRunError` for the message to show the user. */
     completeFirstRun: () => Promise<void>;
+    /** Set when the last `completeFirstRun()` call failed. Cleared on the next
+     *  attempt (success or failure). Distinct from `error` (the initial steps
+     *  load failure) so a failed Skip/Continue doesn't swap the whole screen
+     *  for an unrelated "could not load" message. */
+    completeFirstRunError: string | null;
 }
 export declare function useOnboarding(options?: {
     preview?: boolean;

package/dist/client/onboarding/use-onboarding.js

@@ -10,6 +10,7 @@ export function useOnboarding(options = {}) {
     const [error, setError] = useState(null);
     const [dismissed, setDismissed] = useState(false);
     const [firstRun, setFirstRun] = useState(preview || initialFirstRun);
+    const [completeFirstRunError, setCompleteFirstRunError] = useState(null);
     const mountedRef = useRef(true);
     useEffect(() => {
         setFirstRun(preview || initialFirstRun);
@@ -116,14 +117,27 @@ export function useOnboarding(options = {}) {
             }
             return;
         }
-        const response = await fetch(agentNativePath("/_agent-native/onboarding/first-run/complete"), {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: "{}",
-        });
+        setCompleteFirstRunError(null);
+        // Both a rejected fetch (offline, dropped connection) and a non-ok
+        // response are real failures — neither may look like success to the
+        // caller, so both throw instead of returning as if the step advanced.
+        let response;
+        try {
+            response = await fetch(agentNativePath("/_agent-native/onboarding/first-run/complete"), {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: "{}",
+            });
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : "first-run completion request failed";
+            setCompleteFirstRunError(message);
+            throw e instanceof Error ? e : new Error(message);
+        }
         if (!response.ok) {
-            setError(`first-run completion: ${response.status}`);
-            return;
+            const message = `first-run completion failed: ${response.status}`;
+            setCompleteFirstRunError(message);
+            throw new Error(message);
         }
         setFirstRun(false);
         if (typeof window !== "undefined") {
@@ -153,5 +167,6 @@ export function useOnboarding(options = {}) {
         reopen,
         firstRun,
         completeFirstRun,
+        completeFirstRunError,
     };
 }

package/dist/client/session-replay.js

@@ -1040,6 +1040,31 @@ function isDefinitiveReplayUploadClientError(status) {
     return status === 400 || status === 409 || status === 413 || status === 422;
 }
 const MAX_TRANSIENT_REPLAY_CLIENT_FAILURES = 3;
+// A hung upload never settles, so `state.flushing` stays set, every later flush
+// early-returns while still queueing rrweb events, and the queue grows until the
+// session ends. Time the request out so the failure is observable and the lock
+// is released.
+const REPLAY_UPLOAD_TIMEOUT_MS = 15_000;
+function startReplayUploadTimeout() {
+    // Use an explicit controller/timer pair instead of relying only on
+    // AbortSignal.timeout: the controller is available in older supported
+    // browsers, and the timer can always be cleared when a normal upload
+    // settles so completed uploads do not leave timeout work behind.
+    const controller = typeof AbortController === "undefined" ? undefined : new AbortController();
+    let rejectTimeout;
+    const promise = new Promise((_, reject) => {
+        rejectTimeout = reject;
+    });
+    const timer = setTimeout(() => {
+        controller?.abort();
+        rejectTimeout(new Error("Session replay upload timed out"));
+    }, REPLAY_UPLOAD_TIMEOUT_MS);
+    return {
+        signal: controller?.signal,
+        promise,
+        done: () => clearTimeout(timer),
+    };
+}
 function isTransientReplayUploadClientError(status) {
     return status === 401 || status === 403 || status === 404;
 }
@@ -1048,12 +1073,21 @@ async function sendReplayUpload(options, body, callbacks = {}) {
         const canUseKeepalive = canUseReplayKeepalive(body);
         if (canUseKeepalive)
             callbacks.beforeKeepaliveUpload?.();
-        const response = await fetch(options.endpoint, {
-            method: "POST",
-            body,
-            keepalive: canUseKeepalive,
-            headers: { "Content-Type": "text/plain;charset=UTF-8" },
-        });
+        const timeout = startReplayUploadTimeout();
+        let response;
+        try {
+            const request = fetch(options.endpoint, {
+                method: "POST",
+                body,
+                keepalive: canUseKeepalive,
+                headers: { "Content-Type": "text/plain;charset=UTF-8" },
+                signal: timeout.signal,
+            });
+            response = await Promise.race([request, timeout.promise]);
+        }
+        finally {
+            timeout.done();
+        }
         if (!response.ok) {
             throw new ReplayUploadHttpError(response.status);
         }
@@ -1063,15 +1097,24 @@ async function sendReplayUpload(options, body, callbacks = {}) {
     const canUseKeepalive = canUseReplayKeepalive(upload.body);
     if (canUseKeepalive)
         callbacks.beforeKeepaliveUpload?.();
-    const response = await fetch(options.endpoint, {
-        method: "POST",
-        body: upload.body,
-        keepalive: canUseKeepalive,
-        headers: {
-            ...upload.headers,
-            "X-Agent-Native-Analytics-Key": options.publicKey,
-        },
-    });
+    const timeout = startReplayUploadTimeout();
+    let response;
+    try {
+        const request = fetch(options.endpoint, {
+            method: "POST",
+            body: upload.body,
+            keepalive: canUseKeepalive,
+            headers: {
+                ...upload.headers,
+                "X-Agent-Native-Analytics-Key": options.publicKey,
+            },
+            signal: timeout.signal,
+        });
+        response = await Promise.race([request, timeout.promise]);
+    }
+    finally {
+        timeout.done();
+    }
     if (!response.ok) {
         throw new ReplayUploadHttpError(response.status);
     }

package/dist/client/settings/SettingsTabsPage.js

@@ -3,6 +3,7 @@ import { Tabs, useDesignSystem } from "@agent-native/toolkit/design-system";
 import { IconArrowUpRight, IconHistory, IconSearch, IconSettings, IconUserCircle, IconUsers, IconX, } from "@tabler/icons-react";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { Link } from "react-router";
+import { appBasePath, appPath } from "../../client/api-path.js";
 import { buildSettingsRoute } from "../../navigation/index.js";
 import { cn } from "../utils.js";
 function normalizeTabId(value) {
@@ -70,12 +71,13 @@ function resolveTabId(tabs, value) {
 function activeTabFromLocation(tabs, defaultTab) {
     if (typeof window === "undefined")
         return defaultTab;
+    const pathname = appLocalPathname();
     const settingsPrefix = "/settings";
-    if (window.location.pathname === settingsPrefix) {
+    if (pathname === settingsPrefix) {
         return resolveTabId(tabs, window.location.hash) ?? defaultTab;
     }
-    if (window.location.pathname.startsWith(`${settingsPrefix}/`)) {
-        const segments = window.location.pathname
+    if (pathname.startsWith(`${settingsPrefix}/`)) {
+        const segments = pathname
             .slice(`${settingsPrefix}/`.length)
             .split("/")
             .filter(Boolean)
@@ -95,6 +97,17 @@ function activeTabFromLocation(tabs, defaultTab) {
     }
     return resolveTabId(tabs, window.location.hash) ?? defaultTab;
 }
+function appLocalPathname() {
+    if (typeof window === "undefined")
+        return "/";
+    const pathname = window.location.pathname;
+    const basePath = appBasePath();
+    if (basePath &&
+        (pathname === basePath || pathname.startsWith(`${basePath}/`))) {
+        return pathname.slice(basePath.length) || "/";
+    }
+    return pathname;
+}
 function buildSettingsEntryRoute(tabId, section) {
     const normalizedSection = section?.replace(/^#/, "").trim();
     if (!normalizedSection || normalizedSection === tabId) {
@@ -112,7 +125,7 @@ function updateRouteForTab(tabId, section) {
     if (typeof window === "undefined")
         return;
     const route = buildSettingsEntryRoute(tabId, section);
-    window.history.pushState(null, "", `${route}${window.location.search}`);
+    window.history.pushState(null, "", `${appPath(route)}${window.location.search}`);
 }
 function isEditableElement(element) {
     if (!(element instanceof HTMLElement))
@@ -233,7 +246,7 @@ export function SettingsTabsPage({ general, account, team, whatsNew, extraTabs =
             const fromPath = activeTabFromLocation(tabs, fallbackTab);
             if (fromPath)
                 setInternalTab(fromPath);
-            if (window.location.pathname.startsWith("/settings/"))
+            if (appLocalPathname().startsWith("/settings/"))
                 return;
             const hashValue = window.location.hash.replace(/^#/, "");
             const fromHash = resolveTabId(tabs, hashValue);
@@ -254,7 +267,7 @@ export function SettingsTabsPage({ general, account, team, whatsNew, extraTabs =
         if (!isControlled)
             return;
         const syncControlledLocation = () => {
-            const fromPath = window.location.pathname.startsWith("/settings/")
+            const fromPath = appLocalPathname().startsWith("/settings/")
                 ? activeTabFromLocation(tabs, defaultTab)
                 : null;
             const hashValue = window.location.hash.replace(/^#/, "");

package/dist/client/sse-event-processor.d.ts

@@ -39,10 +39,15 @@ export type ContentPart = {
      * call (opt-in `needsApproval` actions). The action did NOT run; the UI
      * renders an Approve/Deny affordance. `approvalKey` is echoed back in
      * `approvedToolCalls` to approve, `dismissed` records a local Deny.
+     * `askId` identifies THIS gate hit; it changes when a failed resume
+     * re-emits `approval_required` for the same call, which is how the UI
+     * tells that apart from the same ask simply re-rendering (see
+     * `ApprovalAffordance` in chat/tool-call-display.tsx).
      */
     approval?: {
         approvalKey: string;
         dismissed?: boolean;
+        askId?: string;
     };
     /**
      * Structured metadata from the coding-tools executor side-channel.
@@ -70,6 +75,8 @@ export interface SSEEvent {
     approvalKey?: string;
     /** Model-side tool-call id for `approval_required` (mirrors AgentChatEvent). */
     toolCallId?: string;
+    /** Identifies this `approval_required` gate hit (mirrors AgentChatEvent). */
+    askId?: string;
     error?: string;
     seq?: number;
     agent?: string;

package/dist/client/sse-event-processor.js

@@ -1182,7 +1182,10 @@ export function processEvent(ev, content, toolCallCounter, tabId, state) {
             if (idx >= 0) {
                 const part = content[idx];
                 if (part.type === "tool-call") {
-                    part.approval = { approvalKey };
+                    part.approval = {
+                        approvalKey,
+                        ...(ev.askId ? { askId: ev.askId } : {}),
+                    };
                 }
             }
         }

package/dist/client/ui/index.d.ts

@@ -12,6 +12,7 @@ export { ErrorBoundary } from "../ErrorBoundary.js";
 export { ClientOnly } from "../ClientOnly.js";
 export { DefaultSpinner } from "../DefaultSpinner.js";
 export { RuntimeConfigNotice } from "../RuntimeConfigNotice.js";
+export { EnvironmentBadge, buildEnvironmentUrl, isBuilderIoEmployee, resolveEnvironmentChannel, resolveEnvironmentTargets, type EnvironmentBadgeTargets, } from "../EnvironmentBadge.js";
 export { RouteTransitionIndicator, ROUTE_TRANSITION_INDICATOR_DELAY_MS, } from "../RouteTransitionIndicator.js";
 export { applyEmbeddedThemeUpdate, buildEmbeddedThemeUpdate, EMBEDDED_THEME_CHANGE_EVENT, EMBEDDED_THEME_UPDATE_MESSAGE, getThemeInitScript, parseEmbeddedThemeUpdate, themeInitScript, type EmbeddedThemeUpdate, type NormalizedEmbeddedThemeUpdate, type ResolvedTheme, type ThemePreference, } from "../theme.js";
 export { APPEARANCE_PRESETS, applyAppearance, getStoredAppearance, useAppearance, useAppearanceSync, type AppearancePresetId, } from "../appearance.js";

package/dist/client/ui/index.js

@@ -12,6 +12,7 @@ export { ErrorBoundary } from "../ErrorBoundary.js";
 export { ClientOnly } from "../ClientOnly.js";
 export { DefaultSpinner } from "../DefaultSpinner.js";
 export { RuntimeConfigNotice } from "../RuntimeConfigNotice.js";
+export { EnvironmentBadge, buildEnvironmentUrl, isBuilderIoEmployee, resolveEnvironmentChannel, resolveEnvironmentTargets, } from "../EnvironmentBadge.js";
 export { RouteTransitionIndicator, ROUTE_TRANSITION_INDICATOR_DELAY_MS, } from "../RouteTransitionIndicator.js";
 export { applyEmbeddedThemeUpdate, buildEmbeddedThemeUpdate, EMBEDDED_THEME_CHANGE_EVENT, EMBEDDED_THEME_UPDATE_MESSAGE, getThemeInitScript, parseEmbeddedThemeUpdate, themeInitScript, } from "../theme.js";
 export { APPEARANCE_PRESETS, applyAppearance, getStoredAppearance, useAppearance, useAppearanceSync, } from "../appearance.js";

package/dist/client/use-action.js

@@ -52,6 +52,11 @@ function isActionTimeout(error) {
         typeof error === "object" &&
         error.timedOut === true);
 }
+function isActionMethodMismatch(error) {
+    return (!!error &&
+        typeof error === "object" &&
+        error.code === "action_method_mismatch");
+}
 /** @internal exported for tests */
 export function defaultActionQueryRetry(failureCount, error) {
     if (isAuthFailure(error))
@@ -60,6 +65,9 @@ export function defaultActionQueryRetry(failureCount, error) {
     // silently retrying would multiply that wait. Surface it instead.
     if (isActionTimeout(error))
         return false;
+    // Wrong verb is deterministic — retrying sends the same wrong verb again.
+    if (isActionMethodMismatch(error))
+        return false;
     if (isBrowserResourceExhaustion(error))
         return false;
     // Network-level failures never carry an HTTP `status` (actionFetch only
@@ -338,6 +346,24 @@ async function performActionFetch(name, method, params, options) {
             (raw && raw.slice(0, 200)) ||
             res.statusText ||
             `HTTP ${res.status}`;
+        // mountActionRoutes only ever returns 405 for one reason: the verb this
+        // call sent doesn't match the action's declared `http.method`. The client
+        // has no way to look that method up ahead of time (defineAction lives in
+        // server-only modules), so callers routinely default to POST and hit this
+        // blind. Name the action and the required method instead of leaving a
+        // bare 405 for the caller to reverse-engineer from a "Use X" string.
+        if (res.status === 405) {
+            const requiredMethod = /\bUse (GET|POST|PUT|DELETE)\b/.exec(message)?.[1];
+            const error = new Error(`Action ${name} was called with ${method}, but it declares ` +
+                `http: { method: "${requiredMethod ?? "?"}" }. Pass { method: "${requiredMethod ?? "..."}" } ` +
+                `to this call (or use the hook that defaults to it) to match the action's declared method.`);
+            error.status = 405;
+            error.code = "action_method_mismatch";
+            error.sentMethod = method;
+            if (requiredMethod)
+                error.requiredMethod = requiredMethod;
+            throw error;
+        }
         const error = new Error(`Action ${name} failed: ${message}`);
         error.status = res.status;
         throw error;

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/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/config.d.ts

@@ -38,6 +38,11 @@ export interface AgentNativeRuntimeConfig {
     database?: AgentNativeRuntimeDatabaseConfig;
     environment?: AgentNativeRuntimeEnvironmentConfig;
 }
+export type AgentNativeDeploymentEnvironment = "local" | "beta" | "production" | "preview";
+export interface AgentNativeDeploymentConfig {
+    /** The release lane that produced the currently running client bundle. */
+    environment?: AgentNativeDeploymentEnvironment;
+}
 export interface AgentNativeDiagnosticsConfig {
     /** Fail a production Vite build when runtime configuration has issues. */
     failOnBuild?: boolean;
@@ -73,6 +78,7 @@ export interface AgentNativeConfig {
     version?: typeof AGENT_NATIVE_CONFIG_VERSION;
     onboarding?: AgentNativeOnboardingConfig;
     runtime?: AgentNativeRuntimeConfig;
+    deployment?: AgentNativeDeploymentConfig;
     diagnostics?: AgentNativeDiagnosticsConfig;
     instructions?: AgentNativeInstructionsConfig;
     translations?: AgentNativeTranslationsConfig;
@@ -99,3 +105,12 @@ export declare function normalizeAgentNativeConfig(input: unknown, source?: stri
 export declare function mergeAgentNativeConfigs(base: AgentNativeConfig, override: AgentNativeConfig): AgentNativeConfig;
 export declare function resolveAgentNativeConfig(input: AgentNativeConfigInput | undefined, context: AgentNativeConfigContext): AgentNativeConfig;
 export declare function resolveFirstRunOnboardingMode(setting: AgentNativeFirstRunOnboardingSetting, context: AgentNativeConfigContext): AgentNativeFirstRunOnboardingMode;
+export declare function isAgentNativeDeploymentEnvironment(value: unknown): value is AgentNativeDeploymentEnvironment;
+/**
+ * Resolve the public deployment lane from hosting facts at build time.
+ *
+ * Netlify exposes `CONTEXT` and `BRANCH` to builds. Keeping this inference in
+ * the Vite/config boundary means browser code consumes typed public config and
+ * never parses process.env itself.
+ */
+export declare function inferAgentNativeDeploymentEnvironment(env: Record<string, string | undefined>, mode?: string): AgentNativeDeploymentEnvironment | undefined;

package/dist/config.js

@@ -26,6 +26,7 @@ export function normalizeAgentNativeConfig(input, source = "agent-native config"
     }
     const onboardingValue = input.onboarding;
     const runtimeValue = input.runtime;
+    const deploymentValue = input.deployment;
     const diagnosticsValue = input.diagnostics;
     const instructionsValue = input.instructions;
     const translationsValue = input.translations;
@@ -46,6 +47,9 @@ export function normalizeAgentNativeConfig(input, source = "agent-native config"
     if (runtimeValue !== undefined) {
         normalized.runtime = normalizeRuntimeConfig(runtimeValue, `${source}.runtime`);
     }
+    if (deploymentValue !== undefined) {
+        normalized.deployment = normalizeDeploymentConfig(deploymentValue, `${source}.deployment`);
+    }
     if (diagnosticsValue !== undefined) {
         normalized.diagnostics = normalizeDiagnosticsConfig(diagnosticsValue, `${source}.diagnostics`);
     }
@@ -101,6 +105,12 @@ export function mergeAgentNativeConfigs(base, override) {
                     : undefined,
             }
             : undefined,
+        deployment: base.deployment || override.deployment
+            ? {
+                ...base.deployment,
+                ...override.deployment,
+            }
+            : undefined,
         diagnostics: base.diagnostics || override.diagnostics
             ? {
                 ...base.diagnostics,
@@ -205,6 +215,18 @@ function normalizeRuntimeConfig(value, source) {
     }
     return result;
 }
+function normalizeDeploymentConfig(value, source) {
+    if (!isRecord(value)) {
+        throw new Error(`${source} must be an object`);
+    }
+    const environment = value.environment;
+    if (environment === undefined)
+        return {};
+    if (!isAgentNativeDeploymentEnvironment(environment)) {
+        throw new Error(`${source}.environment must be "local", "beta", "production", or "preview"`);
+    }
+    return { environment };
+}
 function normalizeDiagnosticsConfig(value, source) {
     if (!isRecord(value)) {
         throw new Error(`${source} must be an object`);
@@ -338,6 +360,37 @@ function isAgentNativeHarnessRuntime(value) {
         value === "pi" ||
         value === "opencode");
 }
+export function isAgentNativeDeploymentEnvironment(value) {
+    return (value === "local" ||
+        value === "beta" ||
+        value === "production" ||
+        value === "preview");
+}
+/**
+ * Resolve the public deployment lane from hosting facts at build time.
+ *
+ * Netlify exposes `CONTEXT` and `BRANCH` to builds. Keeping this inference in
+ * the Vite/config boundary means browser code consumes typed public config and
+ * never parses process.env itself.
+ */
+export function inferAgentNativeDeploymentEnvironment(env, mode) {
+    const context = env.CONTEXT?.trim().toLowerCase();
+    const branch = env.BRANCH?.trim().toLowerCase();
+    if (branch === "production" || context === "production") {
+        return "production";
+    }
+    if (branch === "beta" || (context === "branch-deploy" && branch === "main")) {
+        return "beta";
+    }
+    if (context === "deploy-preview" ||
+        context === "branch-deploy" ||
+        branch?.startsWith("deploy-preview")) {
+        return "preview";
+    }
+    if (mode === "development")
+        return "local";
+    return undefined;
+}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }