@agent-native/core 0.75.4 → 0.75.5

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: 4030
+- template files: 4031

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @agent-native/core
 
+## 0.75.5
+
+### Patch Changes
+
+- 25802f2: Durable background agent-chat runs now reach Netlify's 15-min async function via
+  the function's DEFAULT url (`/.netlify/functions/<name>`) with NO custom
+  `config.path` and NO catch-all patch — the doc-correct approach per the Netlify
+  docs.
+
+  Every Netlify function is reachable at `/.netlify/functions/<name>` by default;
+  a custom `config.path` REMOVES that default url. The build now emits the
+  background function into the scanned dir
+  (`.netlify/functions-internal/server-agent-background`, or per-app
+  `<app>-agent-background` for workspaces), sharing the same `main.mjs` bundle,
+  with `export const config = { background: true, ... }` and NO custom path. The
+  function therefore keeps its default url, and `background: true` makes any
+  invocation of that url asynchronous (immediate 202 ack, 15-min budget). The
+  Nitro `server` function's `/*` catch-all already excludes `/.netlify/*`, so the
+  default-url namespace is never shadowed by the synchronous function — there is
+  nothing to patch.
+
+  The function entry rewrites the incoming pathname to the framework
+  `_process-run` route (base-path-prefixed for workspaces) before delegating to
+  Nitro, preserving the method, all headers (the HMAC `Authorization: Bearer` the
+  plugin verifies), and the body. It also sets
+  `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true` at cold start so the
+  worker takes the 15-min soft-timeout. The foreground self-dispatch resolves the
+  function's default url on hosted Netlify (per-app name from
+  `AGENT_NATIVE_WORKSPACE_APP_ID`), and `fireInternalDispatch` strips the app base
+  path for `/.netlify/*` targets so the request reaches the host-root function
+  url. Off-Netlify (local dev, `netlify dev`, non-Netlify hosts), the foreground
+  dispatches to the framework process-run route, handled inline by the same
+  in-process catch-all.
+
+  This supersedes the earlier attempt that gave the function a custom
+  `config.path` (the framework route) plus a `server` `excludedPath` patch — that
+  custom path was not honored as a route in production (a probe of
+  `POST /_agent-native/agent-chat/_process-run` returned 404). The graceful inline
+  40s fallback on a dispatch fast-fail is unchanged.
+
 ## 0.75.4
 
 ### Patch Changes

package/corpus/core/package.json

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

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

@@ -63,45 +63,79 @@ export const AGENT_CHAT_PROCESS_RUN_PATH =
 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.
+ * Default function URL of the background function on Netlify. Every Netlify
+ * function is reachable at `/.netlify/functions/<name>` BY DEFAULT; that default
+ * url is removed ONLY if the function declares a custom `config.path`. The
+ * emitted background function declares NO custom `config.path` (it sets
+ * `background: true` and nothing else routing-related), so it KEEPS this default
+ * url — and the Nitro `server` function already excludes `/.netlify/*` from its
+ * `/*` catch-all, so this namespace is never shadowed. The foreground therefore
+ * dispatches HERE on hosted Netlify (see `resolveAgentChatProcessRunDispatchPath`).
  */
 export const AGENT_BACKGROUND_FUNCTION_URL_PATH = `/.netlify/functions/${AGENT_BACKGROUND_FUNCTION_NAME}`;
 
+/**
+ * The per-app workspace background function URL path. Workspace deploy emits one
+ * background function per app named `<app>-agent-background`, reachable at its
+ * DEFAULT url `/.netlify/functions/<app>-agent-background` (no custom
+ * `config.path`). The foreground resolves the current workspace app id from
+ * `AGENT_NATIVE_WORKSPACE_APP_ID` (set by the workspace function entry) so it can
+ * dispatch to the right per-app function url. Returns `null` when no workspace
+ * app id is configured (single-template deploy).
+ */
+function resolveWorkspaceBackgroundFunctionUrlPath(): string | null {
+  const raw = process.env.AGENT_NATIVE_WORKSPACE_APP_ID;
+  if (typeof raw !== "string") return null;
+  // Mirror the workspace app-id normalization (resources/store.ts): take the
+  // first path segment and accept only the safe slug shape used for function
+  // names. Anything else falls back to the single-template name.
+  const candidate = raw.trim().replace(/^\/+/, "").split("/")[0] ?? "";
+  if (!/^[a-z0-9][a-z0-9-]{0,127}$/.test(candidate)) return null;
+  return `/.netlify/functions/${candidate}-agent-background`;
+}
+
 /**
  * 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.
+ * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT + THE NETLIFY DOCS DEFAULT-URL RULE:
+ * the background function is emitted INTO the scanned dir
+ * (`.netlify/functions-internal/server-agent-background`, or per-app
+ * `<app>-agent-background` for workspaces) with `export const config = {
+ * background: true, ... }` and NO custom `config.path`. Because it has no custom
+ * path, Netlify keeps its DEFAULT function url `/.netlify/functions/<name>`, and
+ * `background: true` makes any invocation of that url ASYNC (immediate 202,
+ * 15-min budget). The Nitro `server` function already excludes `/.netlify/*`
+ * from its `/*` catch-all, so the default-url namespace is NEVER shadowed by the
+ * synchronous function.
  *
- * 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.
+ * Therefore on hosted Netlify the foreground dispatches to the function's DEFAULT
+ * url (`/.netlify/functions/<name>`); the function entry then rewrites the
+ * incoming pathname to `AGENT_CHAT_PROCESS_RUN_PATH` (base-path-prefixed for
+ * workspaces) before delegating to the Nitro router, so the `_process-run`
+ * plugin runs with the async 15-min budget. Everywhere else (local dev, `netlify
+ * dev`, non-Netlify hosts where no second function exists) there is no second
+ * function, so the foreground dispatches to the framework route
+ * `AGENT_CHAT_PROCESS_RUN_PATH` and the same in-process catch-all handles it
+ * inline. The HMAC token (signed over the runId) is unchanged either way.
  *
- * 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.
+ * NOTE: this is the DOC-CORRECT approach. An earlier attempt gave the function a
+ * custom `config.path` + a catch-all `excludedPath` patch; the custom path was
+ * NOT honored as a route in prod (probe → 404). Using the default function url
+ * (no custom path) is what Netlify documents and is simpler — there is nothing
+ * to shadow because `/.netlify/*` is already excluded from the `server` catch-all.
  */
 export function resolveAgentChatProcessRunDispatchPath(): string {
+  if (
+    process.env.NETLIFY &&
+    process.env.NETLIFY !== "false" &&
+    process.env.NETLIFY_LOCAL !== "true"
+  ) {
+    return (
+      resolveWorkspaceBackgroundFunctionUrlPath() ??
+      AGENT_BACKGROUND_FUNCTION_URL_PATH
+    );
+  }
   return AGENT_CHAT_PROCESS_RUN_PATH;
 }
 

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

@@ -4394,13 +4394,16 @@ export function createProductionAgentHandler(
       try {
         await fireInternalDispatch({
           event,
-          // 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.
+          // On hosted Netlify this resolves to the background function's DEFAULT
+          // url (/.netlify/functions/<name>, or per-app <app>-agent-background for
+          // workspaces) — the function declares NO custom config.path, so it keeps
+          // its default url, and `background: true` makes that url async (202,
+          // 15-min budget). The `server` /* catch-all already excludes /.netlify/*
+          // so it never shadows it. Off-Netlify this resolves to the framework
+          // `_process-run` route and the same in-process catch-all handles it
+          // inline. `fireInternalDispatch` strips the app base path for
+          // /.netlify/* targets so the request reaches the host-root function url;
+          // the Authorization Bearer HMAC is preserved either way.
           path: resolveAgentChatProcessRunDispatchPath(),
           taskId: runId,
           body: {
@@ -4643,11 +4646,12 @@ export function createProductionAgentHandler(
                 try {
                   await fireInternalDispatch({
                     event,
-                    // 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.
+                    // Continuation chunks use the same path resolution as the
+                    // initial dispatch: on hosted Netlify the background
+                    // function's DEFAULT url (no custom config.path; async via
+                    // background:true; never shadowed because /.netlify/* is
+                    // excluded from the /* catch-all) so each chunk keeps the
+                    // 15-min budget; off-Netlify the in-process framework route.
                     path: resolveAgentChatProcessRunDispatchPath(),
                     taskId: nextRunId,
                     body: {

package/corpus/core/src/cli/skills.ts

@@ -526,6 +526,13 @@ themes. For any inline border, background, or text color, reference a token:
 and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
 renderer owns the sketch/clean font.
 
+**Use literal CSS lengths for spacing.** The \`--wf-*\` tokens are for colors and
+renderer-owned visual styling, not layout spacing. Do not use guessed spacing
+tokens such as \`var(--wf-space-4)\`, Tailwind spacing classes, or theme spacing
+variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
+padding collapses and content hugs the border. Use explicit CSS lengths for
+layout: \`padding:16px\`, \`gap:12px\`, \`margin-top:18px\`, \`minmax(0,1fr)\`.
+
 **Lay out with inline \`style\` flex/grid.** You write the real layout —
 \`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
 renderer never repositions anything. Compose the actual product: reproduce the
@@ -610,10 +617,21 @@ check/serve or verify command for \`<plan-dir>\`.
 **Treat the wireframe border as part of the visible design.** Always wrap HTML
 wireframe content in a root container with real inner padding before drawing
 cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
-\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows so the
-first row never sits flush against the screen border. Keep text away from
-borders: every container, field, button, menu item, and annotation needs enough
-padding and line-height to read cleanly in the rendered Plan view.
+\`box-sizing: border-box\`, \`height: 100%\`, and \`gap\` between child rows on the
+root node itself so the first row never sits flush against the screen border. Do
+not rely on padding on a nested page section as the first visible inset; the
+outermost element must create the breathing room. Keep text away from borders:
+every container, field, button, menu item, and annotation needs enough padding
+and line-height to read cleanly in the rendered Plan view.
+
+**For feature-cloud or abundance visuals, optimize the composition over line-by-line
+reading.** Some marketing/product sections need to feel like a large surface area
+of capability rather than a precise app workflow. In those cases, use one padded
+root with a short headline and a dense, aesthetic cloud of short feature labels,
+chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
+and let many labels be glanceable rather than individually essential. Do not
+force dozens of features into equal cards with long wrapped sentences; that
+usually creates a messy unreadable mockup.
 
 **Lay out children safely so they never collide.** Use HTML flex/grid with
 \`gap\`, \`min-width: 0\`, and sensible overflow. Avoid negative margins, absolute

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

@@ -1510,61 +1510,57 @@ export function isDurableBackgroundDeployEnabled(): boolean {
  * 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):
+ * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT (verified from a local Nitro build)
+ * AND THE NETLIFY DOCS DEFAULT-URL RULE:
  *   - 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`.
+ *     ["/.netlify/*"], preferStatic: true, ... }`. The `/*` catch-all is an
+ *     IN-CODE Functions-API-v2 `config.path` and it ALREADY EXCLUDES
+ *     `/.netlify/*`.
  *   - 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`.
+ *   - Every scanned function is reachable at its DEFAULT url
+ *     `/.netlify/functions/<name>` BY DEFAULT. A custom `config.path` REMOVES
+ *     that default url; declaring NO custom `config.path` KEEPS it.
  *
  * 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.
+ *   2. Give its `export const config` `background: true` (→ async invoke,
+ *      immediate 202, 15-min budget) and NO custom `config.path`. With no custom
+ *      path the function keeps its DEFAULT url
+ *      `/.netlify/functions/server-agent-background`, and because the Nitro
+ *      `server` function's `/*` catch-all already excludes `/.netlify/*`, that
+ *      default-url namespace is NEVER shadowed by the synchronous function — no
+ *      catch-all patch is needed.
+ *   3. The entry NORMALIZES/rewrites the incoming request pathname to
+ *      `AGENT_CHAT_PROCESS_RUN_PATH` before delegating to `./main.mjs`. The
+ *      function is reached at its default url
+ *      (`/.netlify/functions/server-agent-background`), so the Nitro router needs
+ *      the path rewritten to the framework `_process-run` route, preserving the
+ *      method, ALL headers (the HMAC `Authorization: Bearer` MUST survive), and
+ *      the body.
  *   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.
  *
- * 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).
+ * The foreground dispatches to this DEFAULT url on hosted Netlify
+ * (`resolveAgentChatProcessRunDispatchPath` → `AGENT_BACKGROUND_FUNCTION_URL_PATH`).
  *
- * 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.
+ * WHY THIS IS THE DOC-CORRECT FIX: a prior attempt gave the function a custom
+ * `config.path` (= the framework route) plus a catch-all `excludedPath` patch.
+ * The custom `config.path` was NOT honored as a route in prod — a probe of
+ * `POST /_agent-native/agent-chat/_process-run` returned 404. The doc-correct
+ * approach (confirmed against the Netlify docs) is to use the DEFAULT function
+ * url with no custom path: the function stays reachable at
+ * `/.netlify/functions/<name>` and is never shadowed because `/.netlify/*` is
+ * already excluded from the `server` catch-all.
  *
  * 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
@@ -1596,11 +1592,6 @@ export function emitSingleTemplateNetlifyBackgroundFunction(
   // 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
@@ -1618,11 +1609,10 @@ let cachedHandler;
 
 // 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
+// This function declares NO custom \`config.path\`, so it is reached at its
+// DEFAULT url (/.netlify/functions/${backgroundName}). The Nitro router only
+// knows the framework route, so we REWRITE the incoming pathname to
+// PROCESS_RUN_PATH before delegating. 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) {
@@ -1646,13 +1636,12 @@ export const config = {
   generator: "agent-native build",
   // 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.
+  // build/functions/background-functions + build/functions/api). We declare NO
+  // custom path, so the function keeps its DEFAULT url
+  // /.netlify/functions/${backgroundName}; the Nitro \`server\` /* catch-all
+  // already excludes /.netlify/* so that default url is never shadowed by the
+  // synchronous function. The foreground dispatches to that default url.
   background: true,
-  path: PROCESS_RUN_PATH,
   nodeBundler: "none",
   includedFiles: ["**"],
   preferStatic: false,
@@ -1661,67 +1650,12 @@ export const config = {
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), entry);
   console.log(
     `[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).",
+      `scanned dir .netlify/functions-internal with config { background:true } ` +
+      `and NO custom path — reachable at its default url ` +
+      `/.netlify/functions/${backgroundName} (never shadowed; the server /* ` +
+      `catch-all already excludes /.netlify/*). REQUIRES real-deploy ` +
+      `verification of Netlify async (202) invocation — see ` +
+      `docs/design/durable-agent-runs.md.`,
   );
 }
 

package/corpus/core/src/deploy/workspace-deploy.ts

@@ -696,24 +696,30 @@ function isDurableBackgroundDeployEnabled(): boolean {
 /**
  * Emit a SECOND Netlify function for `app` whose name ends in `-background`,
  * re-exporting the SAME `main.mjs` handler bundle. Netlify invokes any function
- * whose deployed name ends in `-background` asynchronously (202 immediately, up
- * to 15-min budget), which is exactly what the durable-background chat
- * dispatch (`fireInternalDispatch` → AGENT_CHAT_PROCESS_RUN_PATH) needs.
+ * with `config.background: true` asynchronously (202 immediately, up to 15-min
+ * budget), which is exactly what the durable-background chat dispatch
+ * (`fireInternalDispatch` → the function's default url) needs.
  *
- * The function is given a `config.path` of the chat process-run route so
- * Netlify routes that POST to this async function instead of the synchronous
- * `<app>-server` function. It shares the same bundle (`includedFiles: ["**"]`)
- * so `A2A_SECRET`, the DB URL, and the rest of the env/bundle are present.
+ * DOC-CORRECT DEFAULT-URL APPROACH (mirrors the single-template emit in
+ * deploy/build.ts): the function declares NO custom `config.path`, so it keeps
+ * its DEFAULT url `/.netlify/functions/<app>-agent-background`. The `<app>-server`
+ * function's catch-all already excludes `/.netlify/*`, so that default-url
+ * namespace is NEVER shadowed by the synchronous function — no overlapping
+ * `config.path` and no catch-all patch are needed. The foreground dispatches to
+ * that default url (`resolveAgentChatProcessRunDispatchPath` resolves the per-app
+ * name from `AGENT_NATIVE_WORKSPACE_APP_ID`); `fireInternalDispatch` strips the
+ * app base path for `/.netlify/*` targets so the request reaches the host-root
+ * function url. The entry then REWRITES the incoming pathname to the
+ * base-path-prefixed `_process-run` route before delegating to the Nitro router.
  *
- * ⚠️ REAL-DEPLOY VERIFICATION REQUIRED. The exact Netlify routing/precedence
- * between this `-background` function's `config.path` and the synchronous
- * `<app>-server` function's broader `config.path` (which also matches
- * `/_agent-native/*` for the dispatch app, or `/<app>/*` otherwise) cannot be
- * verified in this environment. It is emitted additively and only under the
- * flag; if Netlify resolves the overlap to the wrong function, the dispatch
- * would land on the synchronous function (no 15-min budget) — the run would
- * still work via the existing 40s soft-timeout path, just without the durable
- * win. See packages/core/docs/design/durable-agent-runs.md.
+ * It shares the same bundle (`includedFiles: ["**"]`) so `A2A_SECRET`, the DB
+ * URL, and the rest of the env/bundle are present. A prior attempt gave the
+ * function a custom `config.path` (the framework route) that overlapped the
+ * synchronous `<app>-server` catch-all; that path was not honored as a route in
+ * prod (probe → 404). The default url is the doc-correct fix.
+ *
+ * Safety net: if the dispatch fast-fails the foreground degrades to an inline
+ * 40s synchronous run (see production-agent.ts).
  */
 function emitNetlifyBackgroundFunction(
   workspaceRoot: string,
@@ -721,7 +727,9 @@ function emitNetlifyBackgroundFunction(
   srcServerDir: string,
   workspaceApps: WorkspaceAppManifestEntry[],
 ): void {
-  // Name MUST end in `-background` for Netlify async invocation.
+  // Name MUST end in `-background` (Netlify async convention + the runtime guard
+  // reads the -background Lambda-name suffix as a fallback). It is reached at its
+  // DEFAULT url /.netlify/functions/<app>-agent-background.
   const backgroundName = `${app}-agent-background`;
   const dest = path.join(netlifyFunctionsDir(workspaceRoot), backgroundName);
   fs.rmSync(dest, { recursive: true, force: true });
@@ -733,14 +741,20 @@ function emitNetlifyBackgroundFunction(
     workspaceApps,
     app,
   );
-  // Only the chat process-run route needs the async function. Keeping the path
-  // narrow avoids stealing any other traffic from the synchronous function.
-  // The dispatch URL is app-base-path-prefixed (same as the agent-teams
-  // processor dispatch), so the route Netlify must map to this async function
-  // is `/<app>/_agent-native/agent-chat/_process-run`.
+  // The Nitro router for this app expects the base-path-prefixed framework route.
+  // The function is reached at its default url, so the entry rewrites the
+  // incoming pathname to `/<app>/_agent-native/agent-chat/_process-run`.
   const processRunPath = `${basePath}${AGENT_CHAT_PROCESS_RUN_PATH}`;
-  const pathConfig = [processRunPath];
-  const server = `const basePath = ${JSON.stringify(basePath)};
+  const server = `// 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 -background). A
+// globalThis flag (NOT process.env) avoids the no-env-mutation guard and carries
+// no cross-request state.
+globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
+
+const basePath = ${JSON.stringify(basePath)};
+// The base-path-prefixed framework route the Nitro router dispatches to.
+const PROCESS_RUN_PATH = ${JSON.stringify(processRunPath)};
 
 function setBasePathEnv() {
   const processRef = globalThis.process ??= { env: {} };
@@ -767,16 +781,33 @@ setBasePathEnv();
 
 let cachedHandler;
 
-export default async function handler(...args) {
+// Reached at the DEFAULT url /.netlify/functions/${backgroundName}; REWRITE the
+// incoming pathname to the base-path-prefixed _process-run route so the Nitro
+// router runs the plugin. Method, ALL headers (the HMAC Authorization: Bearer
+// MUST survive) and the body are preserved.
+export default async function handler(request) {
   setBasePathEnv();
   cachedHandler ??= (await import("./main.mjs")).default;
-  return cachedHandler(...args);
+  const url = new URL(request.url);
+  url.pathname = PROCESS_RUN_PATH;
+  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: ${JSON.stringify(`${app} agent background handler`)},
   generator: "agent-native workspace deploy",
-  path: ${JSON.stringify(pathConfig)},
+  // background: true → async invoke (202, 15-min budget). NO custom path: the
+  // function keeps its default url /.netlify/functions/${backgroundName}, which
+  // the <app>-server catch-all never shadows (it excludes /.netlify/*).
+  background: true,
   nodeBundler: "none",
   includedFiles: ["**"],
   preferStatic: false,
@@ -788,9 +819,10 @@ export const config = {
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), server);
   console.log(
     `[workspace-deploy] Emitted durable-background function "${backgroundName}" ` +
-      `for app "${app}" (path ${processRunPath}). ` +
-      `REQUIRES real-deploy verification of Netlify async routing — see ` +
-      `docs/design/durable-agent-runs.md.`,
+      `for app "${app}" with config { background:true } and NO custom path — ` +
+      `reachable at its default url /.netlify/functions/${backgroundName} ` +
+      `(rewrites to ${processRunPath}). REQUIRES real-deploy verification of ` +
+      `Netlify async (202) invocation — see docs/design/durable-agent-runs.md.`,
   );
 }