@agent-native/core 0.145.8 → 0.146.1

package/dist/client/ConnectBuilderCard.js

@@ -1,27 +1,27 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { IconExternalLink, IconLoader2 } from "@tabler/icons-react";
+import { IconCheck, IconCode, IconCopy, IconExternalLink, IconLoader2, } from "@tabler/icons-react";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { withBuilderUtmTrackingParams } from "../shared/builder-link-tracking.js";
 import { agentNativePath } from "./api-path.js";
 import { BuilderBMark } from "./builder-mark.js";
+import { writeClipboardText } from "./clipboard.js";
 import { getCallbackOrigin } from "./frame.js";
 import { useBuilderConnectFlow } from "./settings/useBuilderStatus.js";
 import { cn } from "./utils.js";
 const DESKTOP_DOWNLOAD_URL = "https://www.agent-native.com/download";
 const CODE_CHANGE_FALLBACK_DETAIL = "Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.";
 const CODE_CHANGE_FALLBACK_TEXT = `This requires a code change. ${CODE_CHANGE_FALLBACK_DETAIL}`;
-function isLocalBrowserOutsideDesktop() {
-    if (typeof window === "undefined" || typeof navigator === "undefined") {
+function isLocalDevelopment() {
+    if (typeof window === "undefined") {
         return false;
     }
     const hostname = window.location.hostname;
-    const local = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
-    return local && !/AgentNativeDesktop/i.test(navigator.userAgent || "");
+    return (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1");
 }
 /**
- * Rich inline card rendered for the `connect-builder` tool call. Shows a
- * prominent Connect button that opens the Builder CLI auth flow and polls
- * /_agent-native/builder/status until credentials land.
+ * Rich inline card rendered for the `connect-builder` tool call. Shows the
+ * Builder handoff when available, or routes local development requests to the
+ * external coding agent.
  */
 export function ConnectBuilderCard({ configured: initialConfigured, builderEnabled: initialBuilderEnabled = true, connectUrl: initialConnectUrl, orgName: initialOrgName, prompt = "", }) {
     // The connect-poll state machine is shared — the tool-call result is
@@ -46,8 +46,11 @@ export function ConnectBuilderCard({ configured: initialConfigured, builderEnabl
     const [sending, setSending] = useState(false);
     const [runResult, setRunResult] = useState(null);
     const [sendErr, setSendErr] = useState(null);
-    const [localBrowser, setLocalBrowser] = useState(false);
+    const [copyErr, setCopyErr] = useState(null);
+    const [promptCopied, setPromptCopied] = useState(false);
+    const [localDevelopment] = useState(() => isLocalDevelopment());
     const mountedRef = useRef(true);
+    const copyResetRef = useRef(null);
     // Tracks whether the user clicked "Connect Builder" *this session*. When
     // the connect-then-poll round-trip lands `configured=true`, we use this
     // flag to decide whether to retry the user's pending prompt automatically
@@ -58,9 +61,10 @@ export function ConnectBuilderCard({ configured: initialConfigured, builderEnabl
     const wasConnectingRef = useRef(false);
     useEffect(() => {
         mountedRef.current = true;
-        setLocalBrowser(isLocalBrowserOutsideDesktop());
         return () => {
             mountedRef.current = false;
+            if (copyResetRef.current)
+                clearTimeout(copyResetRef.current);
         };
     }, []);
     const handleSend = useCallback(async () => {
@@ -127,8 +131,27 @@ export function ConnectBuilderCard({ configured: initialConfigured, builderEnabl
             setJoiningWaitlist(false);
         }
     }, [orgName, prompt]);
-    // Combine connect-flow errors, send errors, and waitlist errors.
-    const err = sendErr ?? waitlistErr ?? flow.error;
+    const handleCopyPrompt = useCallback(async () => {
+        if (!prompt.trim())
+            return;
+        setCopyErr(null);
+        const copied = await writeClipboardText(prompt);
+        if (!mountedRef.current)
+            return;
+        if (!copied) {
+            setCopyErr("Couldn't copy the prompt");
+            return;
+        }
+        setPromptCopied(true);
+        if (copyResetRef.current)
+            clearTimeout(copyResetRef.current);
+        copyResetRef.current = setTimeout(() => {
+            if (mountedRef.current)
+                setPromptCopied(false);
+        }, 1600);
+    }, [prompt]);
+    // Combine connect-flow errors, send errors, waitlist errors, and copy errors.
+    const err = sendErr ?? waitlistErr ?? copyErr ?? flow.error;
     const hasPrompt = prompt.trim().length > 0;
     const canSend = configured && builderEnabled && hasPrompt;
     // Auto-send the user's pending prompt the moment connecting finishes
@@ -149,7 +172,8 @@ export function ConnectBuilderCard({ configured: initialConfigured, builderEnabl
     }, [flow.connecting, canSend, sending, runResult, sendErr, handleSend]);
     // Branch creation is gated by a server-side project id, which may come
     // from deployment config or org-scoped secrets.
-    const showWaitlist = !builderEnabled && hasPrompt;
+    const showExternalAgentHandoff = localDevelopment && !builderEnabled && hasPrompt;
+    const showWaitlist = !localDevelopment && !builderEnabled && hasPrompt;
     // Title + subtitle depend on which mode we're in. We compute them up front
     // so the render tree below stays flat.
     const connectedCapabilityText = builderEnabled
@@ -161,13 +185,14 @@ export function ConnectBuilderCard({ configured: initialConfigured, builderEnabl
         title = "Builder is working on it";
         subtitle = (_jsxs(_Fragment, { children: ["Working on branch", " ", _jsx("span", { className: "font-mono text-foreground", children: runResult.branchName }), ". Click through to watch progress in the Visual Editor."] }));
     }
+    else if (showExternalAgentHandoff) {
+        title = "This requires a code change";
+        subtitle =
+            "Open your coding agent in this project, then paste this request.";
+    }
     else if (showWaitlist) {
         title = "This requires a code change";
-        subtitle = waitlistJoined ? (_jsxs(_Fragment, { children: ["You're on the waitlist. ", CODE_CHANGE_FALLBACK_DETAIL, " ", localBrowser
-                    ? "Since this project is already running locally, open it in the desktop app for local coding tools or keep editing from your clone."
-                    : "You can still clone the project locally and use the desktop app for code changes."] })) : (_jsxs(_Fragment, { children: [CODE_CHANGE_FALLBACK_DETAIL, " ", localBrowser
-                    ? "Since this project is already running locally, open it in the desktop app for local coding tools or keep editing from your clone."
-                    : "You can still clone the project locally and use the desktop app for code changes."] }));
+        subtitle = waitlistJoined ? (_jsxs(_Fragment, { children: ["You're on the waitlist. ", CODE_CHANGE_FALLBACK_DETAIL, " You can still clone the project locally and use the desktop app for code changes."] })) : (_jsxs(_Fragment, { children: [CODE_CHANGE_FALLBACK_DETAIL, " You can still clone the project locally and use the desktop app for code changes."] }));
     }
     else if (canSend) {
         title = "Send this to Builder";
@@ -181,8 +206,8 @@ export function ConnectBuilderCard({ configured: initialConfigured, builderEnabl
         title = "Connect Builder.io";
         subtitle = _jsx(_Fragment, { children: "Builder.io's free tier includes AI credits." });
     }
-    return (_jsx("div", { className: cn("my-2 rounded-lg border border-border overflow-hidden"), children: _jsxs("div", { className: "flex items-start gap-3 px-4 py-3.5 bg-gradient-to-br from-teal-500/5 via-transparent to-transparent", children: [_jsx("div", { className: cn("flex h-9 w-9 shrink-0 items-center justify-center rounded-lg", "bg-foreground text-background"), children: runResult ? (_jsx(IconLoader2, { className: "h-5 w-5 animate-spin" })) : (_jsx(BuilderBMark, { className: "h-5 w-5" })) }), _jsxs("div", { className: "flex-1 min-w-0", children: [_jsx("div", { className: "flex items-center gap-2 flex-wrap", children: _jsx("span", { className: "text-sm font-semibold text-foreground", children: title }) }), _jsx("div", { className: "mt-0.5 text-xs text-muted-foreground leading-relaxed", children: subtitle }), showWaitlist && (_jsxs("a", { href: DESKTOP_DOWNLOAD_URL, target: "_blank", rel: "noopener noreferrer", className: "mt-2 inline-flex items-center gap-1 text-[11px] font-medium text-muted-foreground no-underline hover:text-foreground", children: ["Download desktop app", _jsx(IconExternalLink, { className: "h-3 w-3" })] })), err && _jsx("div", { className: "mt-2 text-xs text-destructive", children: err }), _jsx("div", { className: "mt-3", children: runResult ? (_jsxs("a", { href: withBuilderUtmTrackingParams(runResult.url, {
+    return (_jsx("div", { className: cn("my-2 rounded-lg border border-border overflow-hidden"), children: _jsxs("div", { className: "flex items-start gap-3 px-4 py-3.5 bg-gradient-to-br from-teal-500/5 via-transparent to-transparent", children: [_jsx("div", { className: cn("flex h-9 w-9 shrink-0 items-center justify-center rounded-lg", "bg-foreground text-background"), children: runResult ? (_jsx(IconLoader2, { className: "h-5 w-5 animate-spin" })) : showExternalAgentHandoff ? (_jsx(IconCode, { className: "h-5 w-5" })) : (_jsx(BuilderBMark, { className: "h-5 w-5" })) }), _jsxs("div", { className: "flex-1 min-w-0", children: [_jsx("div", { className: "flex items-center gap-2 flex-wrap", children: _jsx("span", { className: "text-sm font-semibold text-foreground", children: title }) }), _jsx("div", { className: "mt-0.5 text-xs text-muted-foreground leading-relaxed", children: subtitle }), showWaitlist && (_jsxs("a", { href: DESKTOP_DOWNLOAD_URL, target: "_blank", rel: "noopener noreferrer", className: "mt-2 inline-flex items-center gap-1 text-[11px] font-medium text-muted-foreground no-underline hover:text-foreground", children: ["Download desktop app", _jsx(IconExternalLink, { className: "h-3 w-3" })] })), err && _jsx("div", { className: "mt-2 text-xs text-destructive", children: err }), _jsx("div", { className: "mt-3", children: runResult ? (_jsxs("a", { href: withBuilderUtmTrackingParams(runResult.url, {
                                     campaign: "product",
                                     content: "connect_builder_card_branch",
-                                }), target: "_blank", rel: "noopener noreferrer", className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90"), children: ["Open branch in Builder", _jsx(IconExternalLink, { className: "h-3.5 w-3.5" })] })) : canSend ? (_jsx("button", { type: "button", onClick: handleSend, disabled: sending, className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90", sending && "opacity-70 cursor-wait"), children: sending ? (_jsxs(_Fragment, { children: [_jsx(IconLoader2, { className: "h-3.5 w-3.5 animate-spin" }), "Sending to Builder\u2026"] })) : (_jsx(_Fragment, { children: "Send to Builder" })) })) : showWaitlist && !waitlistJoined ? (_jsx("button", { type: "button", onClick: handleJoinWaitlist, disabled: joiningWaitlist, className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90", joiningWaitlist && "opacity-70 cursor-wait"), children: joiningWaitlist ? (_jsxs(_Fragment, { children: [_jsx(IconLoader2, { className: "h-3.5 w-3.5 animate-spin" }), "Joining\u2026"] })) : (_jsx(_Fragment, { children: "Join the waitlist" })) })) : !configured ? (_jsx("button", { type: "button", onClick: () => flow.start(), disabled: connecting, className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90", connecting && "opacity-70 cursor-wait"), children: connecting ? (_jsxs(_Fragment, { children: [_jsx(IconLoader2, { className: "h-3.5 w-3.5 animate-spin" }), "Waiting for Builder\u2026"] })) : ("Connect Builder") })) : null })] })] }) }));
+                                }), target: "_blank", rel: "noopener noreferrer", className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90"), children: ["Open branch in Builder", _jsx(IconExternalLink, { className: "h-3.5 w-3.5" })] })) : canSend ? (_jsx("button", { type: "button", onClick: handleSend, disabled: sending, className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90", sending && "opacity-70 cursor-wait"), children: sending ? (_jsxs(_Fragment, { children: [_jsx(IconLoader2, { className: "h-3.5 w-3.5 animate-spin" }), "Sending to Builder\u2026"] })) : (_jsx(_Fragment, { children: "Send to Builder" })) })) : showExternalAgentHandoff ? (_jsx("button", { type: "button", onClick: () => void handleCopyPrompt(), className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90"), children: promptCopied ? (_jsxs(_Fragment, { children: [_jsx(IconCheck, { className: "h-3.5 w-3.5" }), "Prompt copied"] })) : (_jsxs(_Fragment, { children: [_jsx(IconCopy, { className: "h-3.5 w-3.5" }), "Copy prompt"] })) })) : showWaitlist && !waitlistJoined ? (_jsx("button", { type: "button", onClick: handleJoinWaitlist, disabled: joiningWaitlist, className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90", joiningWaitlist && "opacity-70 cursor-wait"), children: joiningWaitlist ? (_jsxs(_Fragment, { children: [_jsx(IconLoader2, { className: "h-3.5 w-3.5 animate-spin" }), "Joining\u2026"] })) : (_jsx(_Fragment, { children: "Join the waitlist" })) })) : !configured ? (_jsx("button", { type: "button", onClick: () => flow.start(), disabled: connecting, className: cn("inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors", "bg-foreground text-background hover:bg-foreground/90", connecting && "opacity-70 cursor-wait"), children: connecting ? (_jsxs(_Fragment, { children: [_jsx(IconLoader2, { className: "h-3.5 w-3.5 animate-spin" }), "Waiting for Builder\u2026"] })) : ("Connect Builder") })) : null })] })] }) }));
 }

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

@@ -2,7 +2,7 @@
  * Public, non-secret configuration for an Agent-Native app.
  *
  * This module is intentionally free of Node and framework imports so it can be
- * used from a typed `agent-native.ts` file and from browser code after Vite
+ * used from a typed `agent-native.config.ts` file and from browser code after Vite
  * serializes the resolved config into the client bundle.
  */
 export declare const AGENT_NATIVE_CONFIG_VERSION: 1;
@@ -42,11 +42,18 @@ export interface AgentNativeDiagnosticsConfig {
     /** Fail a production Vite build when runtime configuration has issues. */
     failOnBuild?: boolean;
 }
+export interface AgentNativeInstructionsConfig {
+    /** Relative Markdown file loaded by the in-app runtime agent. */
+    runtime?: string;
+    /** Relative Markdown file loaded by development/coding agents. */
+    development?: string;
+}
 export interface AgentNativeConfig {
     version?: typeof AGENT_NATIVE_CONFIG_VERSION;
     onboarding?: AgentNativeOnboardingConfig;
     runtime?: AgentNativeRuntimeConfig;
     diagnostics?: AgentNativeDiagnosticsConfig;
+    instructions?: AgentNativeInstructionsConfig;
 }
 export interface AgentNativeConfigContext {
     command: "serve" | "build";
@@ -57,7 +64,7 @@ export interface AgentNativeConfigContext {
 export type AgentNativeConfigFactory = (context: AgentNativeConfigContext) => AgentNativeConfig;
 export type AgentNativeConfigInput = AgentNativeConfig | AgentNativeConfigFactory;
 /**
- * Type-safe authoring helper for `agent-native.ts`.
+ * Type-safe authoring helper for `agent-native.config.ts`.
  *
  * Like Next's typed config file, this is deliberately identity-like: the
  * framework evaluates the exported object or factory in the Vite config

package/dist/config.js

@@ -2,12 +2,12 @@
  * Public, non-secret configuration for an Agent-Native app.
  *
  * This module is intentionally free of Node and framework imports so it can be
- * used from a typed `agent-native.ts` file and from browser code after Vite
+ * used from a typed `agent-native.config.ts` file and from browser code after Vite
  * serializes the resolved config into the client bundle.
  */
 export const AGENT_NATIVE_CONFIG_VERSION = 1;
 /**
- * Type-safe authoring helper for `agent-native.ts`.
+ * Type-safe authoring helper for `agent-native.config.ts`.
  *
  * Like Next's typed config file, this is deliberately identity-like: the
  * framework evaluates the exported object or factory in the Vite config
@@ -27,6 +27,7 @@ export function normalizeAgentNativeConfig(input, source = "agent-native config"
     const onboardingValue = input.onboarding;
     const runtimeValue = input.runtime;
     const diagnosticsValue = input.diagnostics;
+    const instructionsValue = input.instructions;
     const normalized = {
         ...(input.version === undefined
             ? {}
@@ -45,6 +46,9 @@ export function normalizeAgentNativeConfig(input, source = "agent-native config"
     if (diagnosticsValue !== undefined) {
         normalized.diagnostics = normalizeDiagnosticsConfig(diagnosticsValue, `${source}.diagnostics`);
     }
+    if (instructionsValue !== undefined) {
+        normalized.instructions = normalizeInstructionsConfig(instructionsValue, `${source}.instructions`);
+    }
     return normalized;
 }
 export function mergeAgentNativeConfigs(base, override) {
@@ -91,6 +95,12 @@ export function mergeAgentNativeConfigs(base, override) {
                 ...override.diagnostics,
             }
             : undefined,
+        instructions: base.instructions || override.instructions
+            ? {
+                ...base.instructions,
+                ...override.instructions,
+            }
+            : undefined,
     };
 }
 export function resolveAgentNativeConfig(input, context) {
@@ -175,6 +185,32 @@ function normalizeDiagnosticsConfig(value, source) {
         ? {}
         : { failOnBuild: value.failOnBuild };
 }
+function normalizeInstructionsConfig(value, source) {
+    if (!isRecord(value)) {
+        throw new Error(`${source} must be an object`);
+    }
+    const result = {};
+    for (const audience of ["runtime", "development"]) {
+        const pathValue = value[audience];
+        if (pathValue === undefined)
+            continue;
+        if (typeof pathValue !== "string") {
+            throw new Error(`${source}.${audience} must be a relative file path`);
+        }
+        result[audience] = normalizeRelativeFilePath(pathValue, `${source}.${audience}`);
+    }
+    return result;
+}
+function normalizeRelativeFilePath(value, source) {
+    const normalized = value.trim().replaceAll("\\", "/");
+    if (!normalized ||
+        normalized.startsWith("/") ||
+        /^[A-Za-z]:\//.test(normalized) ||
+        normalized.split("/").some((segment) => segment === "..")) {
+        throw new Error(`${source} must be a non-empty relative file path inside the app root`);
+    }
+    return normalized;
+}
 function normalizeRequiredEnvKeys(value, source) {
     if (value === undefined)
         return undefined;

package/dist/db/client.d.ts

@@ -227,7 +227,19 @@ export declare function isBackgroundFunctionPoolContext(): boolean;
  * actual context.
  */
 export declare function describeDbError(err: unknown): string;
-export declare function attachNeonPoolErrorLogger(pool: unknown, label?: string): void;
+/**
+ * Thrown INSTEAD of attempting, while an endpoint is in cooldown.
+ *
+ * The refused attempt's error is described in the message and deliberately NOT
+ * attached as `cause`: isConnectionError() walks `cause.code`/`cause.message`,
+ * so a cause would reclassify this as retryable and retryOnConnectionError
+ * would drive the storm straight back.
+ */
+export declare class DbConnectCooldownError extends Error {
+    code: string;
+    constructor(remainingMs: number, refusedBy: string);
+}
+export declare function guardNeonPool(pool: unknown, url: string, label?: string): void;
 interface ClosablePool {
     end(): Promise<unknown>;
 }

package/dist/db/client.js

@@ -613,6 +613,9 @@ export function isTransientDatabaseError(err) {
     const error = err;
     const code = String(error?.code ?? error?.cause?.code ?? "");
     if (code === "ECHECKOUTTIMEOUT" ||
+        // Shed load during a connect cooldown is transient by construction — the
+        // endpoint refused, we chose not to re-ask yet. Surfaces as 503, not 500.
+        code === "DB_CONNECT_COOLDOWN" ||
         code === "EMAXCONN" ||
         code === "53300" ||
         code === "57014" ||
@@ -960,7 +963,77 @@ export function describeDbError(err) {
     }
     return String(err);
 }
-export function attachNeonPoolErrorLogger(pool, label = "db/neon") {
+/**
+ * How long one endpoint stops ATTEMPTING to connect after an attempt failed.
+ * Jittered so concurrent function instances do not re-probe in lockstep.
+ */
+function connectCooldownMs() {
+    const raw = Number(process.env.DB_CONNECT_COOLDOWN_MS);
+    const base = Number.isFinite(raw) && raw > 0 ? raw : 2_000;
+    return Math.round(base * (0.5 + Math.random()));
+}
+/**
+ * Thrown INSTEAD of attempting, while an endpoint is in cooldown.
+ *
+ * The refused attempt's error is described in the message and deliberately NOT
+ * attached as `cause`: isConnectionError() walks `cause.code`/`cause.message`,
+ * so a cause would reclassify this as retryable and retryOnConnectionError
+ * would drive the storm straight back.
+ */
+export class DbConnectCooldownError extends Error {
+    code = "DB_CONNECT_COOLDOWN";
+    constructor(remainingMs, refusedBy) {
+        super(`Database is refusing connection attempts; not attempting again for ${remainingMs}ms. Last failure: ${refusedBy}`);
+        this.name = "DbConnectCooldownError";
+    }
+}
+const connectCooldowns = new Map();
+/**
+ * Neon rejects a connection ATTEMPT, not a connection: "Failed to acquire
+ * permit to connect to the database. Too many database connection attempts are
+ * currently ongoing." A failed acquire leaves the pool with zero idle clients,
+ * so the next execute() calls connect() again — and retryOnConnectionError
+ * backs off only 100ms. The process answers a refusal by manufacturing the next
+ * attempt, which is what keeps the refusal true. Production sat in this loop
+ * until the compute was restarted by hand.
+ *
+ * Hold a short cooldown per endpoint so a refused attempt cannot produce the
+ * next one. Checking out an ALREADY-IDLE client is not an attempt and passes
+ * through, so a cooldown degrades throughput instead of taking the process
+ * offline.
+ */
+function gateNeonConnect(pool, url, label) {
+    const connect = pool.connect;
+    if (typeof connect !== "function")
+        return;
+    const gated = function gatedConnect(...args) {
+        const idle = typeof pool.idleCount === "number" ? pool.idleCount : 0;
+        const gate = connectCooldowns.get(url);
+        if (idle === 0 && gate && Date.now() < gate.until) {
+            return Promise.reject(new DbConnectCooldownError(gate.until - Date.now(), gate.refusedBy));
+        }
+        return Promise.resolve(connect.apply(this, args)).then((client) => {
+            connectCooldowns.delete(url);
+            return client;
+        }, (err) => {
+            const refusedBy = describeDbError(err);
+            const ms = connectCooldownMs();
+            // One line per cooldown window, not per shed request.
+            if (!gate || Date.now() >= gate.until) {
+                console.warn(`[${label}] connection attempt refused; pausing attempts ${ms}ms:`, refusedBy);
+            }
+            connectCooldowns.set(url, { until: Date.now() + ms, refusedBy });
+            throw err;
+        });
+    };
+    // Carry the wrapped function's own properties onto the wrapper. A pool's
+    // `connect` may be instrumented — metrics, tracing, a test spy — and
+    // replacing it with a bare closure would silently drop that instrumentation
+    // along with any assertions built on it.
+    Object.assign(gated, connect);
+    pool.connect = gated;
+}
+export function guardNeonPool(pool, url, label = "db/neon") {
     if (!pool || typeof pool !== "object")
         return;
     if (loggedNeonPools.has(pool))
@@ -969,6 +1042,7 @@ export function attachNeonPoolErrorLogger(pool, label = "db/neon") {
     if (typeof withEvents.on !== "function")
         return;
     loggedNeonPools.add(pool);
+    gateNeonConnect(pool, url, label);
     withEvents.on("error", (err) => {
         console.warn(`[${label}] pool error (will reconnect on next query):`, describeDbError(err));
     });
@@ -1177,7 +1251,7 @@ async function createDbExecInternal(config = {}, trackSingletonResources = false
             const pool = trackSingletonResources
                 ? sharedDbPool("neon", url, makePool)
                 : makePool();
-            attachNeonPoolErrorLogger(pool);
+            guardNeonPool(pool, url);
             const httpSql = bgHttp ? neon(url, { fullResults: true }) : null;
             async function queryNeonClient(client, sql, timeoutOverrideMs) {
                 const { rawSql, args } = sqlAndArgs(sql);

package/dist/db/create-get-db.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { drizzle as drizzleD1 } from "drizzle-orm/d1";
-import { getDialect, getCloudflareD1Binding, getDatabaseUrl, getDatabaseAuthToken, isLocalSqliteUrl, isPgliteUrl, isConnectionError, getPgliteClient, loadPgliteDrizzle, prepareLocalSqliteUrl, sqliteFilenameFromUrl, pgPoolOptions, neonPoolOptions, attachNeonPoolErrorLogger, withDbTimeout, retryOnConnectionError, dbOpTimeoutMs, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "./client.js";
+import { getDialect, getCloudflareD1Binding, getDatabaseUrl, getDatabaseAuthToken, isLocalSqliteUrl, isPgliteUrl, isConnectionError, getPgliteClient, loadPgliteDrizzle, prepareLocalSqliteUrl, sqliteFilenameFromUrl, pgPoolOptions, neonPoolOptions, guardNeonPool, withDbTimeout, retryOnConnectionError, dbOpTimeoutMs, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "./client.js";
 // Lazy driver loaders — cached promises so dynamic import only runs once.
 let _pgDrizzle;
 function getPgDrizzle() {
@@ -408,7 +408,7 @@ export function createGetDb(schema) {
                     // schema module. See `sharedDbPool` in client.ts.
                     resetOnPoolClose("neon", url);
                     const rawPool = sharedDbPool("neon", url, () => new Pool({ connectionString: url, ...neonPoolOptions() }));
-                    attachNeonPoolErrorLogger(rawPool);
+                    guardNeonPool(rawPool, url);
                     // Wrap the pool with the resilience layer so Drizzle queries get the
                     // same withDbTimeout + retryOnConnectionError protection as the raw
                     // DbExec path in client.ts. Reads retry freely; writes only retry on

package/dist/db/migrations.js

@@ -245,11 +245,28 @@ function isServerlessRequestRuntime() {
         process.env.VERCEL === "1");
 }
 /**
- * A runtime that is ALLOWED to migrate: scheduled jobs and durable background
- * workers, which are off the request path and may take as long as they need.
+ * Whether this app migrates at RELEASE time, so skipping on the request path
+ * is safe.
  *
- * Set by whichever runtime claims migration duty. Analytics sets its own
- * equivalent flag before running the scheduled rollup.
+ * Without this, "skip in serverless" silently means "never migrate" for any app
+ * that has no release entrypoint — and at the time this was written exactly one
+ * of seventeen templates had one. Existing tables keep working, so nothing
+ * fails; a newly added migration just never applies, and a fresh deploy comes
+ * up with missing tables. That is a skip indistinguishable from success, which
+ * is the failure mode this repo bans.
+ *
+ * So the request-path skip is opt-in per app. An app sets this once it owns a
+ * release migration step (see templates/analytics/scripts/migrate-production.ts
+ * and the `migrate:production` build step in its netlify.toml).
+ */
+function appMigratesAtRelease() {
+    const raw = process.env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim();
+    return !!raw && ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+}
+/**
+ * A runtime that is ALLOWED to migrate: release scripts, scheduled jobs, and
+ * durable background workers, which are off the request path and may take as
+ * long as they need. Claimed with {@link withMigrationRuntime}.
  */
 function isMigrationAuthorizedRuntime() {
     return (globalThis.__AGENT_NATIVE_MIGRATION_RUNTIME__ === true);
@@ -322,6 +339,7 @@ export function runMigrations(migrations, options) {
         // the explicit opt-in for a caller that genuinely cannot defer.
         if (options?.runInServerlessRequest !== true &&
             isServerlessRequestRuntime() &&
+            appMigratesAtRelease() &&
             !isMigrationAuthorizedRuntime()) {
             console.info(`[migrations] Skipping "${table}" migrations in a serverless request runtime`);
             return;

package/dist/deploy/build.d.ts

@@ -312,3 +312,4 @@ export declare function resolveNitroBundledYjsEntry(): string;
  * the small set above bundled to keep their package manifests traceable.
  */
 export declare function nitroNoExternalsForPreset(targetPreset: string): true | readonly string[];
+export declare function resolveNitroBuildReplacements(env?: NodeJS.ProcessEnv): Record<string, string>;

package/dist/deploy/build.js

@@ -23,10 +23,11 @@ import { INTEGRATION_RECOVERY_RUNTIME_MARKER, INTEGRATION_RETRY_SWEEP_PATH, INTE
 import { isValidCron } from "../jobs/cron.js";
 import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
 import { normalizeAppBasePath } from "../server/app-base-path.js";
-import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, } from "../shared/cache-control.js";
+import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, } from "../shared/cache-control.js";
 import { mcpEmbedStaticAssetRouteRules } from "../shared/mcp-embed-headers.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, } from "../shared/social-meta.js";
 import { generateActionRegistryForProject } from "../vite/action-types-plugin.js";
+import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "../vite/agent-native-config-loader.js";
 import { cloneServerBundleForFunction, copyDir } from "./function-bundle.js";
 import { collectImmutableAssetPaths, IMMUTABLE_ASSET_CACHE_CONTROL, IMMUTABLE_ASSET_CACHE_HEADERS, prefixAssetPath, } from "./immutable-assets.js";
 import { discoverApiRoutes, discoverPlugins, discoverActionFiles, getMissingDefaultPlugins, DEFAULT_PLUGIN_REGISTRY, } from "./route-discovery.js";
@@ -651,6 +652,7 @@ export function generateWorkerEntry(routes, pluginPaths, defaultPluginStems = []
     // The worker ships as a static bundle with no access to runtime env, so the
     // deployment-wide SSR cache policy is baked in from this build's env.
     const ssrCacheHeaders = resolveSsrCacheHeaders();
+    const ssrCacheKeyHeaders = resolveSsrCacheKeyHeaders();
     const routeImports = [];
     const routeRegistrations = [];
     for (let i = 0; i < routes.length; i++) {
@@ -970,9 +972,8 @@ function injectHeadScript(html, script) {
 }
 
 // Resolved from AGENT_NATIVE_SSR_CACHE at build time.
-const SSR_CACHE_CONTROL = ${JSON.stringify(ssrCacheHeaders["cache-control"])};
-const SSR_CDN_CACHE_CONTROL = ${JSON.stringify(ssrCacheHeaders["cdn-cache-control"])};
-const SSR_NETLIFY_CDN_CACHE_CONTROL = ${JSON.stringify(ssrCacheHeaders["netlify-cdn-cache-control"])};
+const SSR_CACHE_HEADERS = ${JSON.stringify(ssrCacheHeaders)};
+const SSR_CACHE_KEY_HEADERS = ${JSON.stringify(ssrCacheKeyHeaders)};
 const DEFAULT_SPECULATION_RULES_PATH = ${JSON.stringify(DEFAULT_SPECULATION_RULES_PATH)};
 const IMMUTABLE_ASSET_CACHE_CONTROL = ${JSON.stringify(IMMUTABLE_ASSET_CACHE_CONTROL)};
 const IMMUTABLE_ASSET_PATHS = new Set(${JSON.stringify([...new Set(immutableAssetPaths)].sort())});
@@ -1056,13 +1057,12 @@ function applyDefaultSsrCacheHeader(headers, status, pathname) {
     else headers.delete("vary");
   }
 
-  headers.set("cache-control", SSR_CACHE_CONTROL);
-  headers.set("cdn-cache-control", SSR_CDN_CACHE_CONTROL);
-  // Netlify function responses are dynamic by default and can otherwise show
-  // Cache-Status fwd=bypass even with Cache-Control: public. Keep this
-  // Netlify-specific header so SSR HTML/.data are served from the shared
-  // durable CDN cache instead of stampeding origin — for every visitor.
-  headers.set("netlify-cdn-cache-control", SSR_NETLIFY_CDN_CACHE_CONTROL);
+  for (const [name, value] of Object.entries(SSR_CACHE_HEADERS)) {
+    headers.set(name, value);
+  }
+  for (const [name, value] of Object.entries(SSR_CACHE_KEY_HEADERS)) {
+    headers.set(name, value);
+  }
 }
 
 function applyDefaultSpeculationRulesHeader(headers, status, basePath) {
@@ -3463,6 +3463,22 @@ function createBrowserOnlyServerStubPlugin() {
         },
     };
 }
+export function resolveNitroBuildReplacements(env = process.env) {
+    return {
+        // Netlify exposes DEPLOY_ID only while building. Embed it into the Nitro
+        // function so preview OAuth relays can target this immutable deployment
+        // even though the value is unavailable in the function runtime.
+        "process.env.AGENT_NATIVE_BUILD_ID": JSON.stringify(env.DEPLOY_ID?.trim() || env.AGENT_NATIVE_BUILD_ID?.trim() || ""),
+        "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(env.GA_MEASUREMENT_ID?.trim() || ""),
+        "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(env.GTM_CONTAINER_ID?.trim() || ""),
+        // Netlify's netlify.toml environment is available while this deploy
+        // build runs, but is not injected into the deployed Function. Nitro is
+        // a separate server build, so embed release migration ownership here as
+        // well as in the Vite server bundle.
+        "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
+        "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(env.CONTEXT?.trim() || ""),
+    };
+}
 async function buildWithNitro() {
     console.log(`[deploy] Building for preset "${preset}" via Nitro...`);
     const appBasePath = normalizeConfiguredAppBasePath();
@@ -3493,6 +3509,7 @@ async function buildWithNitro() {
     // own virtual module registration. Both paths reuse `readAgentsBundleFromFs`
     // from `server/agents-bundle.ts` to guarantee identical content.
     const { readAgentsBundleFromFs } = await import("../server/agents-bundle.js");
+    const nitroAgentConfig = await loadResolvedAgentNativeConfig(cwd, createAgentNativeConfigContext("build", process.env.NODE_ENV === "development" ? "development" : "production"));
     // Resolve the workspace core (if present) up front so the bundle embeds
     // enterprise-wide AGENTS.md + skills alongside the template's.
     const nitroWorkspaceCore = await getWorkspaceCoreExports(cwd);
@@ -3504,7 +3521,9 @@ async function buildWithNitro() {
         }
         : null;
     const agentsBundleModuleSource = () => {
-        const bundle = readAgentsBundleFromFs(cwd, nitroWorkspaceSource);
+        const bundle = readAgentsBundleFromFs(cwd, nitroWorkspaceSource, {
+            instructions: nitroAgentConfig.instructions,
+        });
         return `// AUTO-GENERATED by @agent-native/core deploy build (Nitro virtual)
 // Contains the inlined AGENTS.md + .agents/skills/ content from the template,
 // merged with the workspace core's AGENTS.md + skills/ when present.
@@ -3543,17 +3562,7 @@ export default bundle;
         virtual: {
             "virtual:agents-bundle": agentsBundleModuleSource,
         },
-        replace: {
-            // Netlify exposes DEPLOY_ID only while building. Embed it into the Nitro
-            // function so preview OAuth relays can target this immutable deployment
-            // even though the value is unavailable in the function runtime.
-            "process.env.AGENT_NATIVE_BUILD_ID": JSON.stringify(process.env.DEPLOY_ID?.trim() ||
-                process.env.AGENT_NATIVE_BUILD_ID?.trim() ||
-                ""),
-            "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(process.env.GA_MEASUREMENT_ID?.trim() || ""),
-            "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
-            "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(process.env.CONTEXT?.trim() || ""),
-        },
+        replace: resolveNitroBuildReplacements(),
         // Replace browser-only renderers (Excalidraw/Mermaid) with an inert proxy in
         // the server bundle. Without this, Nitro's Rolldown build pulls the real
         // Excalidraw into a shared vendor chunk imported statically by the SSR render

package/dist/notifications/routes.d.ts

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

package/dist/progress/routes.d.ts

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