@agent-native/core 0.145.8 → 0.146.0

package/corpus/templates/slides/shared/api.ts

@@ -82,6 +82,8 @@ export interface SharedDeckResponse {
   title: string;
   slides: SharedDeckSlide[];
   aspectRatio?: import("./aspect-ratios").AspectRatio;
+  /** Resolved at share creation so public links keep the deck's styling. */
+  designSystem?: DesignSystemData;
 }
 
 export type SharedSlideTransition =

package/corpus/templates/tasks/.agents/skills/turn-into-app/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Turn visible project context, a proven thread, skill, or workflow into a
   runnable Agent-Native app with simple buttons, visible agent steps, preview,
   and deployment handoff. Use when a user invokes `/turn-into-app` or asks to
-  make a workflow into an app.
+  make a workflow into an app, including from Claude or ChatGPT on the web.
 user-invocable: true
 scope: both
 metadata:
@@ -13,9 +13,32 @@ metadata:
 
 # Turn Into App
 
+## Host execution boundary
+
+The build location depends on the host. Treat this as a hard routing rule:
+
+- In Claude Web, ChatGPT Web, or a Claude/ChatGPT Project on the web, you are
+  the source analyst and handoff orchestrator. You must not build the app in
+  the host sandbox. Do not run `npm`, `pnpm`, `npx`, `agent-native create`, or
+  `add-app`; do not edit files, create artifacts, or start a local dev server.
+  After writing the bounded source brief, call the connected Dispatch action
+  `start-workspace-app-creation`. Pass the brief and repeatable workflow in
+  `prompt`, plus the inferred `appId`, `description`, `template`, and selected
+  `resourceIds` when available. This is the Builder handoff.
+- Do not substitute the generic `create_workspace_app` MCP tool in an online
+  host. That tool is a local workspace scaffolder, not the Builder handoff.
+- If `start-workspace-app-creation` is not available or Dispatch is not
+  authenticated, stop with the connector setup needed. Do not fall back to a
+  local build or claim that the app exists.
+- In Claude Code, Codex Code, or another local code-agent runtime with a target
+  workspace, follow the local implementation steps below. The local agent may
+  scaffold, edit, run, and verify the app there.
+
 ## Default behavior
 
-This is an end-to-end build skill, not a request for an app proposal.
+For a local code-agent runtime this is an end-to-end build skill, not a request
+for an app proposal. For an online host, the end-to-end result is a verified
+Builder handoff and the resulting workspace app, not code written in the host.
 
 - With no argument, choose the source in this order: visible project context,
   then the current thread. A fresh Claude or ChatGPT Project is a valid source
@@ -47,9 +70,12 @@ private web access, invent an importer, add fake OAuth, or scrape a logged-in
 page. If the needed context is not visible, ask for an export, transcript, or
 attachment and treat that artifact as imported source material.
 
-Deliver a fresh app in a new directory, implement the repeatable workflow with
-buttons and agent handoffs, start its dev server, verify the main path, and
-continue through build/deployment handoff. Do not stop at a plan.
+For local code-agent runtimes, deliver a fresh app in a new directory,
+implement the repeatable workflow with buttons and agent handoffs, start its dev
+server, verify the main path, and continue through build/deployment handoff. Do
+not stop at a plan. For online hosts, call Dispatch first after the source brief,
+then report the returned Builder branch/path and verify the workspace app through
+Dispatch when it becomes available.
 
 ## Fresh project context mode
 
@@ -190,12 +216,12 @@ Do not use `create` for an existing workspace; it scaffolds a new standalone
 workspace rather than adding an app to the current one.
 
 When the source came from a fresh external Project and the target is a Builder
-workspace, prefer the available Dispatch MCP workspace handoff after writing
-the source brief. Call `start-workspace-app-creation` with a concise prompt,
-the inferred app id, and the brief's repeatable workflow. Pass selected
-workspace resource IDs when they are available, rather than pasting entire
-knowledge files. Continue from the returned workspace path or Builder handoff
-and report the actual verification result.
+workspace, the online host path is mandatory: after writing the source brief,
+call `start-workspace-app-creation` with a concise prompt, the inferred app id,
+and the brief's repeatable workflow. Pass selected workspace resource IDs when
+they are available, rather than pasting entire knowledge files. Continue from
+the returned workspace path or Builder branch handoff and report the actual
+verification result. Do not run the local scaffold commands in this host mode.
 
 Use a first-party template only when it materially fits the workflow. Keep the
 new app independent from the source thread's working tree unless the user

package/corpus/templates/tasks/.agents/skills/turn-into-app/references/fresh-project.md

@@ -51,13 +51,24 @@ also place the skill instructions or this reference in the Project
 instructions/knowledge files. Then add and authenticate the Dispatch MCP
 connector from the packaged `adapters/chatgpt-mcp/connector.json`.
 
+For Claude Web, ChatGPT Web, and their web Projects, the host is an
+orchestrator, not the build environment. After forming the source brief, call
+the Dispatch `start-workspace-app-creation` action so Builder creates the app
+in the connected workspace. Do not use the host's code interpreter, shell,
+artifact editor, `create_workspace_app`, or local `pnpm`/`npm` commands. If the
+handoff action is unavailable, stop and ask the user to authenticate Dispatch;
+do not fall back to a local sandbox build. Claude Code and Codex Code are the
+local-agent exception and may follow the implementation steps in the main
+skill.
+
 In a new Project chat, say:
 
 ```text
 Turn this project into an app. Use the visible Project instructions,
 knowledge files, and any selected successful runs as the source. Create the
-app in the connected Agent-Native workspace, keep the source brief bounded,
-and report the real path and verification result.
+app in the connected Agent-Native workspace through Dispatch and Builder, keep
+the source brief bounded, and report the real Builder branch/path and
+verification result. Do not build it in this chat's sandbox.
 ```
 
 If the host does not show the Project instructions or files to the model, stop

package/dist/cli/code-agent-executor.js

@@ -13,6 +13,7 @@ import { buildMergedConfig, McpClientManager, mcpToolsToActionEntries, } from ".
 import { readAgentsBundleFromFs, generateDevelopmentSkillsPromptBlock, } from "../server/agents-bundle.js";
 import { getAmbientOrgId, getAmbientUserEmail, runWithRequestContext, } from "../server/request-context.js";
 import { isReasoningEffort, } from "../shared/reasoning-effort.js";
+import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "../vite/agent-native-config-loader.js";
 import { createCodeAgentOutputSmoother } from "./code-agent-output-smoother.js";
 import { addCodeAgentCommandToAllowlist, appendCodeAgentTranscriptEvent, dequeueCodeAgentFollowUp, getCodeAgentRunRecord, isCodeAgentCommandAllowed, listCodeAgentTranscriptEvents, updateCodeAgentRunRecord, } from "./code-agent-runs.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
@@ -1295,11 +1296,15 @@ const AGENTS_MD_INLINE_CAP = 16_000;
  */
 /** @internal exported for unit tests */
 export async function buildCodeAgentSystemPrompt(cwd, permissionMode) {
-    const bundle = readAgentsBundleFromFs(cwd);
+    const appConfig = await loadResolvedAgentNativeConfig(cwd, createAgentNativeConfigContext("serve", "development"));
+    const bundle = readAgentsBundleFromFs(cwd, null, {
+        instructions: appConfig.instructions,
+    });
     // If the bundle has no AGENTS.md, try CLAUDE.md as a fallback — many repos
     // use that name for agent instructions (e.g. Claude Code projects).
-    let agentsMdContent = bundle.agentsMd;
-    if (!agentsMdContent.trim()) {
+    let agentsMdContent = bundle.developmentAgentsMd ?? bundle.agentsMd;
+    if (!agentsMdContent.trim() &&
+        appConfig.instructions?.development === undefined) {
         try {
             const fs = await import("node:fs");
             const path = await import("node:path");

package/dist/client/ConnectBuilderCard.d.ts

@@ -3,19 +3,19 @@ export interface ConnectBuilderCardProps {
     configured: boolean;
     /**
      * True when the server has a Builder branch project configured for this
-     * request. When false, the card shows a waitlist CTA instead of a Send
-     * button — the /builder/run endpoint would 403 anyway.
+     * request. When false, the card shows a hosted waitlist CTA or a local code
+     * external coding-agent handoff instead of a Send button.
      */
     builderEnabled?: boolean;
     connectUrl: string;
     orgName?: string | null;
-    /** The user's feature/change request, forwarded to Builder's cloud agent
-     *  when they click Send. Empty for generic "connect Builder" prompts. */
+    /** The user's feature/change request, forwarded to the selected coding
+     *  agent when they click Send. Empty for generic "connect Builder" prompts. */
     prompt?: string;
 }
 /**
- * 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 declare function ConnectBuilderCard({ configured: initialConfigured, builderEnabled: initialBuilderEnabled, connectUrl: initialConnectUrl, orgName: initialOrgName, prompt, }: ConnectBuilderCardProps): React.JSX.Element;

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

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

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/deploy/build.js

@@ -27,6 +27,7 @@ import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, } from "../shar
 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";
@@ -3493,6 +3494,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 +3506,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.

package/dist/file-upload/actions/upload-image.d.ts

@@ -17,11 +17,11 @@ declare const _default: import("../../action.js").ActionDefinition<{
     id?: undefined;
     provider?: undefined;
 } | {
-    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
+    error?: undefined;
 }>;
 export default _default;