@agent-native/core 0.75.1 → 0.75.4

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 1160
-- template files: 4025
+- template files: 4030

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @agent-native/core
 
+## 0.75.4
+
+### Patch Changes
+
+- dbfbe42: Preserve starter-only manifest fields when syncing builder-agent-native-starter from templates/chat.
+
+## 0.75.3
+
+### Patch Changes
+
+- 8a00851: Durable background agent-chat runs now reach Netlify's 15-min async function by
+  emitting the background function INTO the scanned functions dir with a real
+  `config.path`, and excluding that path from the Nitro `server` `/*` catch-all so
+  the match is unambiguous.
+
+  Grounded in the real Netlify build output: Nitro's `netlify` preset writes no
+  `netlify.toml` and no redirects — the `/*` catch-all is an in-code Functions API
+  v2 `config.path: "/*"` on `.netlify/functions-internal/server/server.mjs`.
+  Netlify scans exactly the configured `functionsDirectory`
+  (`.netlify/functions-internal`); `.netlify/functions/` is the build OUTPUT dir
+  (where `@netlify/build` later writes the zips + `manifest.json`) and is never
+  scanned. On CI, Netlify reads each scanned function's `export const config` to
+  build the manifest routes — so per-file `background`/`path` config is honored.
+
+  The build now emits the background function into
+  `.netlify/functions-internal/server-agent-background` (the scanned dir), sharing
+  the same `main.mjs` bundle, with `export const config = { background: true, path:
+"/_agent-native/agent-chat/_process-run" }`. It also appends that path to the
+  `server` function's `config.excludedPath`, so the `/*` catch-all no longer
+  matches the process-run route. Netlify evaluates serverless functions before
+  redirects, so a POST to the framework process-run route matches only the async
+  background function (immediate 202 ack, 15-min budget) — never the synchronous
+  `server` catch-all. The entry sets
+  `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true` at cold start and
+  normalizes the request path before delegating to Nitro, preserving the method,
+  all headers (the HMAC `Authorization: Bearer` the plugin verifies), and the body.
+
+  This supersedes the two earlier approaches that failed in production: emitting
+  into `functions-internal` with a `config.path` but WITHOUT excluding it from the
+  `/*` catch-all (both functions matched the path; the synchronous `server`
+  catch-all won, returning a sync 401 instead of a 202), and emitting a standalone
+  function into `.netlify/functions/` (never scanned, returned 404). The foreground
+  self-dispatch now always targets the framework process-run route on every host
+  via `resolveAgentChatProcessRunDispatchPath`. The graceful inline 40s fallback on
+  a dispatch fast-fail is unchanged.
+
+## 0.75.2
+
+### Patch Changes
+
+- 4b3543d: Durable background agent-chat runs now actually receive Netlify's 15-min async
+  budget by reaching a STANDALONE background function at its DIRECT url, bypassing
+  Nitro's synchronous `/*` catch-all.
+
+  The previous emit wrote the background function into `.netlify/functions-internal`
+  with a custom `config.path` of the `_process-run` route. A custom `config.path`
+  makes a function reachable ONLY at that path (not at its default function url),
+  `functions-internal` is not exposed at a default url, and Netlify routed
+  `/_agent-native/agent-chat/_process-run` to the synchronous Nitro `server`
+  catch-all instead — so the worker was capped at the ~60s wall and degraded to
+  40s-chunked runs (confirmed live: a POST to the process-run path returned a
+  synchronous 401 from the handler rather than a 202 async ack).
+
+  The build now emits a standalone function into the STANDARD
+  `.netlify/functions/server-agent-background` dir with `background: true` and NO
+  custom `path`, so Netlify exposes it at `/.netlify/functions/server-agent-background`
+  and invokes it asynchronously (immediate 202 ack, 15-min budget). Its entry sets
+  `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true` at cold start and rewrites
+  the incoming request path back to the `_process-run` route before delegating to
+  the Nitro handler, preserving the method, all headers (the HMAC
+  `Authorization: Bearer` the plugin verifies survives the rewrite), and the body.
+  The foreground self-dispatch (and server-driven continuation chunks) now target
+  that direct url on hosted Netlify via a shared `resolveAgentChatProcessRunDispatchPath`
+  helper, and stay on the framework route everywhere else. The graceful inline
+  40s fallback on a dispatch fast-fail is unchanged.
+
 ## 0.75.1
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.75.1",
+  "version": "0.75.4",
   "type": "module",
   "engines": {
     "node": ">=22"

package/corpus/core/src/agent/durable-background.ts

@@ -51,6 +51,60 @@ import {
 export const AGENT_CHAT_PROCESS_RUN_PATH =
   "/_agent-native/agent-chat/_process-run";
 
+/**
+ * Name of the standalone Netlify background function the build emits (see
+ * `emitSingleTemplateNetlifyBackgroundFunction` in deploy/build.ts). Shared so
+ * the emit and the dispatch-path helper below can never drift on the name.
+ *
+ * MUST end in `-background` — both because that is the conventional Netlify
+ * async-function suffix and because `isInBackgroundFunctionRuntime()` reads the
+ * `AWS_LAMBDA_FUNCTION_NAME` `-background` suffix as a secondary runtime signal.
+ */
+export const AGENT_BACKGROUND_FUNCTION_NAME = "server-agent-background";
+
+/**
+ * Default function URL of the background function on Netlify, kept for
+ * diagnostics/tests. Every Netlify function is ALSO reachable at
+ * `/.netlify/functions/<name>` unless a custom `config.path` removes the default
+ * url. The emitted background function declares `config.path =
+ * AGENT_CHAT_PROCESS_RUN_PATH`, which means Netlify routes the process-run path
+ * to it directly AND (per Netlify docs) removes this default url — so the
+ * foreground does NOT dispatch here; it dispatches to the framework route (see
+ * `resolveAgentChatProcessRunDispatchPath`). This constant is retained only so
+ * the name/url shape stays asserted and discoverable.
+ */
+export const AGENT_BACKGROUND_FUNCTION_URL_PATH = `/.netlify/functions/${AGENT_BACKGROUND_FUNCTION_NAME}`;
+
+/**
+ * Resolve the path the foreground POST should self-dispatch the chat background
+ * worker to.
+ *
+ * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT: the background function is emitted
+ * INTO the scanned dir (`.netlify/functions-internal/server-agent-background`)
+ * with `export const config = { background: true, path:
+ * AGENT_CHAT_PROCESS_RUN_PATH }`. Netlify evaluates serverless functions BEFORE
+ * redirects (request-chain step 10 vs 11), and the build excludes this exact path
+ * from the `server` `/*` catch-all — so a POST to `AGENT_CHAT_PROCESS_RUN_PATH`
+ * matches ONLY the async background function (immediate 202, 15-min budget),
+ * never the synchronous `server` catch-all.
+ *
+ * So the dispatch path is the SAME framework route on every host. On hosted
+ * Netlify it lands on the async function (because of the exclude + the
+ * background function's `config.path`); everywhere else (local dev, `netlify
+ * dev`, non-Netlify hosts where no second function exists) the same in-process
+ * catch-all handles it inline. The HMAC token (signed over the runId) is
+ * unchanged.
+ *
+ * NOTE: this is a deliberate change from the earlier "dispatch to the direct
+ * `/.netlify/functions/<name>` url" attempt, which only worked if the function
+ * was reachable at its default url. With a custom `config.path` the default url
+ * is removed, and there is no shadowing to bypass anyway, so dispatching to the
+ * framework route is both correct and simpler.
+ */
+export function resolveAgentChatProcessRunDispatchPath(): string {
+  return AGENT_CHAT_PROCESS_RUN_PATH;
+}
+
 /**
  * Env flag for durable background runs. DEFAULT-ON: unset means enabled; an app
  * opts OUT with an explicit falsy value (`false`/`0`/`no`/`off`).

package/corpus/core/src/agent/production-agent.ts

@@ -65,10 +65,10 @@ import {
 } from "./run-manager.js";
 import type { ActiveRun } from "./run-manager.js";
 import {
-  AGENT_CHAT_PROCESS_RUN_PATH,
   AGENT_CHAT_BACKGROUND_RUN_FIELD,
   isAgentChatDurableBackgroundEnabled,
   isInBackgroundFunctionRuntime,
+  resolveAgentChatProcessRunDispatchPath,
 } from "./durable-background.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { readBody } from "../server/h3-helpers.js";
@@ -4394,7 +4394,14 @@ export function createProductionAgentHandler(
       try {
         await fireInternalDispatch({
           event,
-          path: AGENT_CHAT_PROCESS_RUN_PATH,
+          // The framework `_process-run` route on every host. On hosted Netlify
+          // the build emits an async background function (in the scanned dir)
+          // that CLAIMS this exact path via `config.path` AND excludes it from
+          // the `server` /* catch-all, so this POST matches ONLY the async
+          // function (immediate 202, 15-min budget) — Netlify matches functions
+          // before redirects. Off-Netlify the same in-process catch-all handles
+          // it. The Authorization Bearer HMAC is preserved either way.
+          path: resolveAgentChatProcessRunDispatchPath(),
           taskId: runId,
           body: {
             ...body,
@@ -4636,7 +4643,12 @@ export function createProductionAgentHandler(
                 try {
                   await fireInternalDispatch({
                     event,
-                    path: AGENT_CHAT_PROCESS_RUN_PATH,
+                    // Continuation chunks dispatch to the same framework
+                    // `_process-run` route; on hosted Netlify it matches the
+                    // async background function (config.path + excluded from the
+                    // /* catch-all) so each chunk keeps the 15-min budget. Same
+                    // path-resolution as the initial dispatch.
+                    path: resolveAgentChatProcessRunDispatchPath(),
                     taskId: nextRunId,
                     body: {
                       ...body,

package/corpus/core/src/cli/sync-builder-starter-manifest.ts

@@ -59,6 +59,26 @@ export function generateStandaloneChatManifest(repoRoot?: string): {
   }
 }
 
+function mergePackageJsonRecords(
+  canonical: Record<string, string> | undefined,
+  starter: Record<string, string> | undefined,
+  starterPinnedKeys: string[] = [],
+): Record<string, string> {
+  const merged = { ...(canonical ?? {}) };
+  for (const [key, value] of Object.entries(starter ?? {})) {
+    if (!(key in merged)) {
+      merged[key] = value;
+    }
+  }
+  for (const key of starterPinnedKeys) {
+    const pinned = starter?.[key];
+    if (pinned) {
+      merged[key] = pinned;
+    }
+  }
+  return merged;
+}
+
 export function mergeStarterManifest(
   starterPackageJson: PackageJson,
   canonicalPackageJson: PackageJson,
@@ -75,19 +95,23 @@ export function mergeStarterManifest(
   if (starterPackageJson.private !== undefined) {
     merged.private = starterPackageJson.private;
   }
+  if (typeof starterPackageJson.packageManager === "string") {
+    merged.packageManager = starterPackageJson.packageManager;
+  }
 
-  const starterDeps =
-    (starterPackageJson.dependencies as Record<string, string> | undefined) ??
-    {};
-  const canonicalDeps =
-    (canonicalPackageJson.dependencies as Record<string, string> | undefined) ??
-    {};
-  merged.dependencies = {
-    ...canonicalDeps,
-    ...(starterDeps["@agent-native/core"]
-      ? { "@agent-native/core": starterDeps["@agent-native/core"] }
-      : {}),
-  };
+  merged.dependencies = mergePackageJsonRecords(
+    canonicalPackageJson.dependencies as Record<string, string> | undefined,
+    starterPackageJson.dependencies as Record<string, string> | undefined,
+    ["@agent-native/core"],
+  );
+  merged.devDependencies = mergePackageJsonRecords(
+    canonicalPackageJson.devDependencies as Record<string, string> | undefined,
+    starterPackageJson.devDependencies as Record<string, string> | undefined,
+  );
+  merged.scripts = mergePackageJsonRecords(
+    canonicalPackageJson.scripts as Record<string, string> | undefined,
+    starterPackageJson.scripts as Record<string, string> | undefined,
+  );
 
   return merged;
 }

package/corpus/core/src/deploy/build.ts

@@ -34,7 +34,10 @@ import {
 } from "./workspace-core.js";
 import { generateActionRegistryForProject } from "../vite/action-types-plugin.js";
 import { mcpEmbedStaticAssetRouteRules } from "../shared/mcp-embed-headers.js";
-import { AGENT_CHAT_PROCESS_RUN_PATH } from "../agent/durable-background.js";
+import {
+  AGENT_BACKGROUND_FUNCTION_NAME,
+  AGENT_CHAT_PROCESS_RUN_PATH,
+} from "../agent/durable-background.js";
 import {
   AGENT_NATIVE_SOCIAL_IMAGE_ALT,
   AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER,
@@ -1502,36 +1505,76 @@ export function isDurableBackgroundDeployEnabled(): boolean {
 }
 
 /**
- * Single-template Netlify build: emit a SECOND function whose name ends in
- * `-background`, re-exporting the same `main.mjs` handler bundle, so the chat
- * `_process-run` POST lands on Netlify's async (15-min) function instead of the
- * synchronous one. Additive + flag-gated (see `isDurableBackgroundDeployEnabled`).
+ * Single-template Netlify build: emit an async (background) function INSIDE the
+ * scanned functions dir so the chat `_process-run` worker runs on Netlify's
+ * 15-min async function instead of the synchronous `/*` catch-all.
+ * Additive + flag-gated (see `isDurableBackgroundDeployEnabled`).
+ *
+ * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT (verified from a local Nitro build):
+ *   - Nitro's `netlify` preset emits exactly ONE function source at
+ *     `.netlify/functions-internal/server/`. `server.mjs` re-exports `main.mjs`
+ *     and declares `export const config = { path: "/*", excludedPath:
+ *     ["/.netlify/*"], preferStatic: true, ... }`. Nitro writes NO `netlify.toml`
+ *     and NO `[[redirects]]`; the `/*` catch-all is an IN-CODE Functions-API-v2
+ *     `config.path`.
+ *   - The generated `.netlify/netlify.toml` sets
+ *     `functionsDirectory = ".netlify/functions-internal"`. Netlify scans EXACTLY
+ *     that dir; functions placed anywhere else (e.g. `.netlify/functions/`, which
+ *     is the BUILD OUTPUT dir where `@netlify/build` later writes the zipped
+ *     functions + `manifest.json`) are NEVER deployed.
+ *   - On Netlify CI, `@netlify/build` reads each scanned function's
+ *     `export const config`, zips it, and materializes
+ *     `.netlify/functions/manifest.json` with `routes` derived from each
+ *     `config.path`. So per-file `export const config` (including `background` and
+ *     `path`) IS honored — the `server` manifest entry's `routes: [{ pattern:
+ *     "/*" }]` came straight from `server.mjs`'s `config.path`.
  *
- * Nitro's `netlify` preset emits a single function at
- * `.netlify/functions-internal/server` (`server.mjs` → `main.mjs`). We copy
- * that directory to a sibling `<...>-background` function and write an entry
- * with a `config.path` of the process-run route.
+ * THEREFORE we:
+ *   1. Emit the background function INTO the scanned dir
+ *      (`.netlify/functions-internal/server-agent-background/`), sharing the same
+ *      built `main.mjs` bundle, so Netlify discovers it and honors its config.
+ *   2. Give its `export const config` BOTH `background: true` (→ async invoke,
+ *      immediate 202, 15-min budget) AND `path: AGENT_CHAT_PROCESS_RUN_PATH` (so
+ *      it claims that exact path at function-matching time, which Netlify
+ *      evaluates BEFORE redirects — step 10 vs 11 in the request chain).
+ *   3. PATCH the Nitro `server` function's own `server.mjs` so its catch-all
+ *      `config.path: "/*"` EXCLUDES `AGENT_CHAT_PROCESS_RUN_PATH` (append it to
+ *      `excludedPath`). Netlify does NOT define a winner when two serverless
+ *      functions both match a path; rather than rely on that undocumented order,
+ *      we make the match UNAMBIGUOUS — only the background function matches
+ *      `_process-run`, and `server` matches everything else exactly as before.
+ *   4. Set `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true` at cold start
+ *      (read back by `isInBackgroundFunctionRuntime()` so the worker takes the
+ *      ~13-min soft-timeout). A `globalThis` flag — NOT `process.env` — keeps the
+ *      no-env-mutation guard satisfied and carries no cross-request state.
  *
- * The function declares `background: true` so Netlify invokes it ASYNC (HTTP
- * 202 ack) with the 15-min budget, and a `config.path` of the process-run route
- * so the `_process-run` self-dispatch lands on it. The earlier version set the
- * path but omitted `background: true` and relied on the legacy `-background`
- * filename — which the `config` object overrides — so Netlify served it
- * SYNCHRONOUSLY (~60s) and the durable worker never got the 15-min budget
- * (confirmed live: a POST to the process-run path returned a synchronous 401
- * from the handler instead of a 202 async ack).
+ * With a real `config.path` the function is reachable at that path directly, so
+ * the foreground POSTs to `AGENT_CHAT_PROCESS_RUN_PATH`
+ * (`resolveAgentChatProcessRunDispatchPath`) and the request entry no longer
+ * needs to rewrite the path — it already arrives at the framework route. We keep
+ * a defensive normalize-to-PROCESS_RUN_PATH in the entry anyway (cheap, and it
+ * makes the function correct even if reached via its default function url).
  *
- * ⚠️ One Netlify runtime behavior still resolves only on a real deploy: the
- * routing precedence between this function's `config.path` and Nitro's catch-all
- * for that exact path. If the catch-all wins, the run still completes via the
- * 40s soft-timeout path on the sync function (no durable win, no regression).
- * See docs/design/durable-agent-runs.md (Open risks #1).
+ * WHY THIS BEATS ALL THREE PRIOR FAILURES:
+ *   - Attempts 1 & 2 emitted into `functions-internal` (correct dir) with a
+ *     `config.path` but did NOT exclude that path from the `server` `/*`
+ *     catch-all. Two functions matched `_process-run`; the order is undocumented
+ *     and the catch-all `server` (priority 0, synchronous) won → SYNC 401, not a
+ *     202. We now exclude the path from `server`, so only the async function
+ *     matches.
+ *   - Attempt 3 emitted a standalone function into `.netlify/functions/` — the
+ *     OUTPUT dir, which Netlify does not scan — so it never entered the manifest
+ *     → 404. We now emit into the SCANNED `functions-internal` dir.
+ *
+ * Safety net regardless of Netlify routing nuance: if the dispatch fast-fails
+ * (e.g. the function was not emitted), the foreground handler degrades to an
+ * inline 40s synchronous run (see production-agent.ts).
  */
 export function emitSingleTemplateNetlifyBackgroundFunction(
   projectCwd: string,
 ): void {
-  const functionsDir = path.join(projectCwd, ".netlify", "functions-internal");
-  const serverDir = path.join(functionsDir, "server");
+  const internalDir = path.join(projectCwd, ".netlify", "functions-internal");
+  const serverDir = path.join(internalDir, "server");
   if (!fs.existsSync(path.join(serverDir, "main.mjs"))) {
     // Nitro output layout differs from what we expected — skip rather than
     // guess. The single-function deploy is unaffected.
@@ -1541,13 +1584,24 @@ export function emitSingleTemplateNetlifyBackgroundFunction(
     );
     return;
   }
-  const backgroundName = "server-agent-background";
-  const dest = path.join(functionsDir, backgroundName);
+  const backgroundName = AGENT_BACKGROUND_FUNCTION_NAME;
+  // Emit INTO the SCANNED functions dir (functions-internal) so Netlify discovers
+  // the function and honors its `export const config`. `.netlify/functions/` is
+  // the build OUTPUT dir (where @netlify/build writes the zip + manifest) and is
+  // NOT scanned — emitting there is why the standalone attempt 404'd.
+  const dest = path.join(internalDir, backgroundName);
   fs.rmSync(dest, { recursive: true, force: true });
   copyDir(serverDir, dest);
-  // Drop the original Nitro entry so our background entry is the entrypoint.
+  // Drop the original Nitro `/*` entry so our entry is the entrypoint and the
+  // copied bundle does NOT re-register the catch-all `config.path`.
   fs.rmSync(path.join(dest, "server.mjs"), { force: true });
 
+  // Make the `server` `/*` catch-all NOT match the process-run path, so only the
+  // async background function matches it (function-vs-function path order is
+  // undocumented on Netlify — don't rely on it).
+  excludeProcessRunPathFromServerCatchAll(serverDir);
+
+  const processRunPath = JSON.stringify(AGENT_CHAT_PROCESS_RUN_PATH);
   const entry = `// Mark this isolate as the durable background runtime BEFORE the handler
 // bundle is imported, so isInBackgroundFunctionRuntime() reliably returns true
 // in this function. The deployed Lambda name is NOT guaranteed to end in
@@ -1557,26 +1611,48 @@ export function emitSingleTemplateNetlifyBackgroundFunction(
 // set-once isolate marker read back by isInBackgroundFunctionRuntime().
 globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
 
+// The framework route the Nitro router dispatches to (the _process-run plugin).
+const PROCESS_RUN_PATH = ${processRunPath};
+
 let cachedHandler;
 
-export default async function handler(...args) {
+// Netlify v2 invokes this as (request, context). The Nitro netlify handler is a
+// Web-standard \`async (Request) => Response\` (see nitro/presets/netlify/runtime).
+// Because this function declares \`config.path = PROCESS_RUN_PATH\`, Netlify routes
+// that exact path here and the request already arrives as PROCESS_RUN_PATH — no
+// rewrite is needed. We still NORMALIZE the pathname to PROCESS_RUN_PATH so the
+// function stays correct even if it is ever reached via its default function url
+// (/.netlify/functions/${backgroundName}). Method, ALL headers (the HMAC
+// Authorization: Bearer MUST survive — the plugin verifies it) and the body are
+// preserved by cloning the incoming Request with only its URL pathname set.
+export default async function handler(request) {
   cachedHandler ??= (await import("./main.mjs")).default;
-  return cachedHandler(...args);
+  const url = new URL(request.url);
+  url.pathname = PROCESS_RUN_PATH;
+  // Read the body once and pass it through. GET/HEAD have no body.
+  const method = request.method || "POST";
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await request.text() : undefined;
+  const rewritten = new Request(url.toString(), {
+    method,
+    headers: request.headers,
+    body,
+  });
+  return cachedHandler(rewritten);
 }
 
 export const config = {
   name: "agent background handler",
   generator: "agent-native build",
-  // background: true is what actually makes Netlify invoke this ASYNCHRONOUSLY
-  // (immediate HTTP 202 ack) with the 15-minute budget. Without it, a function
-  // that declares a custom \`path\` is served SYNCHRONOUSLY (~60s) even when its
-  // file name ends in "-background" — the \`config\` object overrides the legacy
-  // filename convention. That omission is why the durable worker was capped at
-  // ~60s in prod (verified live: POST to the process-run path returned a
-  // synchronous 401 from the handler, not a 202 async ack). See Netlify docs:
-  // build/functions/background-functions + build/functions/configuration.
+  // background: true makes Netlify invoke this ASYNCHRONOUSLY (immediate HTTP
+  // 202 ack) with the 15-minute budget (Netlify docs:
+  // build/functions/background-functions + build/functions/api). path claims the
+  // process-run route directly; Netlify evaluates serverless functions BEFORE
+  // redirects (request-chain step 10 vs 11), and we exclude this path from the
+  // \`server\` /* catch-all so only THIS function matches it — no ambiguous
+  // function-vs-function order.
   background: true,
-  path: ${JSON.stringify([AGENT_CHAT_PROCESS_RUN_PATH])},
+  path: PROCESS_RUN_PATH,
   nodeBundler: "none",
   includedFiles: ["**"],
   preferStatic: false,
@@ -1584,9 +1660,68 @@ export const config = {
 `;
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), entry);
   console.log(
-    `[build] Emitted durable-background function "${backgroundName}" ` +
-      `(path ${AGENT_CHAT_PROCESS_RUN_PATH}). REQUIRES real-deploy verification ` +
-      `of Netlify async routing — see docs/design/durable-agent-runs.md.`,
+    `[build] Emitted durable-background function "${backgroundName}" into the ` +
+      `scanned dir .netlify/functions-internal with config { background:true, ` +
+      `path:"${AGENT_CHAT_PROCESS_RUN_PATH}" } and excluded that path from the ` +
+      `server /* catch-all. REQUIRES real-deploy verification of Netlify async ` +
+      `(202) invocation — see docs/design/durable-agent-runs.md.`,
+  );
+}
+
+/**
+ * Append `AGENT_CHAT_PROCESS_RUN_PATH` to the Nitro `server` function's
+ * `config.excludedPath` so its `/*` catch-all does NOT match the process-run
+ * path. That guarantees the async background function (which declares
+ * `config.path = AGENT_CHAT_PROCESS_RUN_PATH`) is the ONLY function that matches
+ * that path — Netlify does not define a winner when two serverless functions
+ * both match, so we make the match unambiguous instead of relying on order.
+ *
+ * The Nitro-generated `server/server.mjs` is small and deterministic:
+ *   export { default } from "./main.mjs";
+ *   export const config = { ... excludedPath: ["/.netlify/*"], ... };
+ * We parse the `excludedPath: [...]` array literal and add our path if absent.
+ * If the shape ever changes and we can't find/parse it, we log and leave the
+ * file untouched (the inline-40s fallback still keeps chat working).
+ */
+function excludeProcessRunPathFromServerCatchAll(serverDir: string): void {
+  const serverEntry = path.join(serverDir, "server.mjs");
+  if (!fs.existsSync(serverEntry)) {
+    console.warn(
+      "[build] Durable-background: server/server.mjs not found; cannot exclude " +
+        `${AGENT_CHAT_PROCESS_RUN_PATH} from the /* catch-all.`,
+    );
+    return;
+  }
+  const original = fs.readFileSync(serverEntry, "utf8");
+  if (original.includes(AGENT_CHAT_PROCESS_RUN_PATH)) {
+    // Already excluded (idempotent — emit may run on a re-used output tree).
+    return;
+  }
+  const excludedPathRe = /excludedPath:\s*\[([^\]]*)\]/;
+  const match = original.match(excludedPathRe);
+  const quotedPath = JSON.stringify(AGENT_CHAT_PROCESS_RUN_PATH);
+  if (match) {
+    const existing = match[1].trim();
+    const next = existing
+      ? `excludedPath: [${existing.replace(/,\s*$/, "")}, ${quotedPath}]`
+      : `excludedPath: [${quotedPath}]`;
+    fs.writeFileSync(serverEntry, original.replace(excludedPathRe, next));
+    return;
+  }
+  // No existing `excludedPath` — inject one into the config object. Match the
+  // `path: "/*"` line and add `excludedPath` right after it.
+  const pathLineRe = /(path:\s*("\/\*"|'\/\*'),?)/;
+  if (pathLineRe.test(original)) {
+    fs.writeFileSync(
+      serverEntry,
+      original.replace(pathLineRe, `$1\n  excludedPath: [${quotedPath}],`),
+    );
+    return;
+  }
+  console.warn(
+    "[build] Durable-background: could not locate excludedPath/path in " +
+      "server/server.mjs; leaving the /* catch-all unchanged (the background " +
+      "function may be shadowed — the inline-40s fallback still applies).",
   );
 }
 

package/corpus/templates/analytics/actions/get-sql-dashboard.ts

@@ -24,10 +24,6 @@ function seededResponse(
   };
 }
 
-function isEmptyConfig(config: Record<string, unknown>): boolean {
-  return !Array.isArray(config.panels) || config.panels.length === 0;
-}
-
 export default defineAction({
   description:
     "Get a SQL analytics dashboard by ID, including its full panel config, visibility, and access metadata.",
@@ -78,10 +74,6 @@ export default defineAction({
       });
     }
     const config = dash.config as Record<string, unknown>;
-    if (isEmptyConfig(config)) {
-      const seed = loadDashboardSeed(args.id);
-      if (seed) return seededResponse(args.id, seed);
-    }
     return {
       id: args.id,
       ...config,

package/corpus/templates/analytics/actions/update-dashboard.ts

@@ -466,7 +466,9 @@ export default defineAction({
       .optional()
       .describe("Replace the whole dashboard config (or a JSON string)."),
   }),
-  http: false,
+  // The SQL dashboard editor persists user edits through callAction(), which
+  // needs this action mounted under /_agent-native/actions/update-dashboard.
+  http: { method: "POST" },
   mcpApp: {
     compactCatalog: true,
     resource: embedApp({

package/corpus/templates/analytics/app/components/SqlEditor.tsx

@@ -0,0 +1,57 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+import { SqlHighlight } from "@/components/SqlHighlight";
+
+export interface SqlEditorProps extends Omit<
+  React.TextareaHTMLAttributes<HTMLTextAreaElement>,
+  "value"
+> {
+  value: string;
+}
+
+export const SqlEditor = React.forwardRef<HTMLTextAreaElement, SqlEditorProps>(
+  ({ className, onScroll, value, disabled, readOnly, ...props }, ref) => {
+    const highlightRef = React.useRef<HTMLPreElement | null>(null);
+
+    const handleScroll = (event: React.UIEvent<HTMLTextAreaElement>) => {
+      const highlight = highlightRef.current;
+      if (highlight) {
+        highlight.scrollTop = event.currentTarget.scrollTop;
+        highlight.scrollLeft = event.currentTarget.scrollLeft;
+      }
+      onScroll?.(event);
+    };
+
+    return (
+      <div
+        className={cn(
+          "relative min-h-[200px] rounded-md border border-input bg-background ring-offset-background focus-within:outline-none focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2",
+          disabled && "cursor-not-allowed opacity-50",
+          className,
+        )}
+      >
+        <SqlHighlight
+          ref={highlightRef}
+          aria-hidden="true"
+          sql={value || " "}
+          preClassName="pointer-events-none absolute inset-0 overflow-hidden rounded-md bg-transparent p-3 text-xs leading-5"
+          className="text-foreground"
+        />
+        <textarea
+          ref={ref}
+          value={value}
+          disabled={disabled}
+          readOnly={readOnly}
+          onScroll={handleScroll}
+          spellCheck={false}
+          className={cn(
+            "relative z-10 min-h-[inherit] w-full resize-y rounded-md border-0 bg-transparent p-3 font-mono text-xs leading-5 text-transparent caret-foreground outline-none selection:bg-primary/30 placeholder:text-muted-foreground focus:outline-none disabled:cursor-not-allowed",
+            readOnly && "cursor-default",
+          )}
+          {...props}
+        />
+      </div>
+    );
+  },
+);
+SqlEditor.displayName = "SqlEditor";