@agent-native/core 0.75.2 → 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: 4029
+- template files: 4031

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @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
+
+- 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

package/corpus/core/package.json

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

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

@@ -63,38 +63,67 @@ export const AGENT_CHAT_PROCESS_RUN_PATH =
 export const AGENT_BACKGROUND_FUNCTION_NAME = "server-agent-background";
 
 /**
- * Direct invocation URL of the standalone background function on Netlify.
- *
- * The function is emitted into the STANDARD functions dir with `background:true`
- * and NO custom `config.path`, so Netlify exposes it (and ONLY it) at the
- * default function URL `/.netlify/functions/<name>` and invokes it
- * asynchronously (immediate HTTP 202 ack, 15-min budget). Hitting this URL
- * directly BYPASSES Nitro's `/*` catch-all `server` function — which is the
- * whole point: the previous approach put a custom `config.path` on the function
- * and Netlify routed `/_agent-native/agent-chat/_process-run` to the synchronous
- * `server` catch-all instead (verified live: a synchronous 401 from the handler
- * rather than a 202 async ack).
+ * 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.
  *
- * On hosted Netlify (`NETLIFY` truthy and not `netlify dev`) the standalone
- * async background function is reachable ONLY at its direct function URL
- * (`/.netlify/functions/server-agent-background`); POSTing the framework route
- * `AGENT_CHAT_PROCESS_RUN_PATH` would land on Nitro's synchronous `/*` catch-all
- * (the ~60s `server` function) and NEVER get the 15-min budget. The standalone
- * function's entry rewrites the incoming path back to `AGENT_CHAT_PROCESS_RUN_PATH`
- * before delegating to the Nitro handler, so the `_process-run` plugin still
- * dispatches it — only the OUTER URL differs.
+ * 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.
+ *
+ * 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.
  *
- * Everywhere else (local dev, `netlify dev`, non-Netlify hosts where the
- * standalone function does not exist) we keep dispatching to the framework route
- * directly — the same in-process catch-all handles it, and there is no separate
- * async function to reach. The HMAC token (signed over the runId) is unchanged
- * either way; only the URL path differs.
+ * 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 (
@@ -102,7 +131,10 @@ export function resolveAgentChatProcessRunDispatchPath(): string {
     process.env.NETLIFY !== "false" &&
     process.env.NETLIFY_LOCAL !== "true"
   ) {
-    return AGENT_BACKGROUND_FUNCTION_URL_PATH;
+    return (
+      resolveWorkspaceBackgroundFunctionUrlPath() ??
+      AGENT_BACKGROUND_FUNCTION_URL_PATH
+    );
   }
   return AGENT_CHAT_PROCESS_RUN_PATH;
 }

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

@@ -4394,14 +4394,16 @@ export function createProductionAgentHandler(
       try {
         await fireInternalDispatch({
           event,
-          // On hosted Netlify this is the standalone background function's DIRECT
-          // url (`/.netlify/functions/server-agent-background`) — POSTing the
-          // framework `_process-run` path would land on Nitro's synchronous `/*`
-          // catch-all and never get the 15-min budget. The function's entry
-          // rewrites the path back to AGENT_CHAT_PROCESS_RUN_PATH before
-          // delegating to Nitro, so the `_process-run` plugin still runs and the
-          // Authorization Bearer HMAC survives. Off-Netlify it stays the
-          // framework path (handled in-process).
+          // 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: {
@@ -4644,11 +4646,12 @@ export function createProductionAgentHandler(
                 try {
                   await fireInternalDispatch({
                     event,
-                    // Continuation chunks must also land on the standalone async
-                    // background function (its direct url on hosted Netlify) so
-                    // each chunk keeps the 15-min budget; same path-resolution as
-                    // the initial dispatch. The function entry rewrites the path
-                    // back to `_process-run` for the Nitro router.
+                    // 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/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

@@ -1505,46 +1505,66 @@ export function isDurableBackgroundDeployEnabled(): boolean {
 }
 
 /**
- * Single-template Netlify build: emit a STANDALONE async background function so
- * the chat `_process-run` worker runs on Netlify's async (15-min) function
- * reached at its DIRECT url, instead of the synchronous `/*` catch-all.
+ * 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`).
  *
- * Nitro's `netlify` preset emits a single synchronous function at
- * `.netlify/functions-internal/server` (`server.mjs` → `main.mjs`, `config.path`
- * `/*`). We copy that bundle to a STANDALONE function in the STANDARD functions
- * dir `.netlify/functions/server-agent-background` and write an entry that:
- *   1. Sets `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true` at cold start
+ * 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, ... }`. 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.
+ *   - 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` `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.
- *   2. Declares `export const config = { background: true }` with NO `path`. With
- *      no custom `path`, Netlify exposes the function at the DEFAULT url
- *      `/.netlify/functions/server-agent-background` and `background:true` makes
- *      it ASYNC (immediate HTTP 202 ack, 15-min budget). The foreground POST
- *      self-dispatches to that direct url
- *      (`resolveAgentChatProcessRunDispatchPath`), BYPASSING Nitro's `/*`
- *      catch-all entirely.
- *   3. REWRITES the incoming request path to `AGENT_CHAT_PROCESS_RUN_PATH` before
- *      delegating to the Nitro handler (`./main.mjs` default export — a Netlify
- *      v2 / Web-standard `async (Request) => Response` handler), so the Nitro
- *      router dispatches it to the `_process-run` plugin. Method, ALL headers
- *      (critically the HMAC `Authorization: Bearer` the plugin verifies) and the
- *      body are preserved by cloning the incoming `Request` with only its URL
- *      pathname rewritten.
  *
- * WHY this replaced the previous `config.path` approach: a function with a custom
- * `config.path` is reachable ONLY at that path (not at its default function url)
- * and `functions-internal` is not exposed at the default url at all. In prod,
- * Netlify routed `/_agent-native/agent-chat/_process-run` to the synchronous
- * Nitro `server` catch-all, NOT to the background function — verified live: a
- * POST to the process-run path returned a SYNCHRONOUS 401 from the handler
- * (the Nitro plugin ran) instead of a 202 async ack. A standalone function at
- * its direct url cannot be shadowed by the catch-all.
+ * The foreground dispatches to this DEFAULT url on hosted Netlify
+ * (`resolveAgentChatProcessRunDispatchPath` → `AGENT_BACKGROUND_FUNCTION_URL_PATH`).
+ *
+ * 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 direct-url dispatch
- * fast-fails (e.g. 404 when this function was not emitted), the foreground
- * handler degrades to an inline 40s synchronous run (see production-agent.ts).
+ * 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,
@@ -1561,15 +1581,15 @@ export function emitSingleTemplateNetlifyBackgroundFunction(
     return;
   }
   const backgroundName = AGENT_BACKGROUND_FUNCTION_NAME;
-  // Emit into the STANDARD functions dir (NOT functions-internal) so Netlify
-  // exposes the function at its default url `/.netlify/functions/<name>`.
-  const functionsDir = path.join(projectCwd, ".netlify", "functions");
-  const dest = path.join(functionsDir, backgroundName);
-  fs.mkdirSync(functionsDir, { recursive: true });
+  // 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 standalone entry is the entrypoint
-  // and the copied bundle does NOT re-register the catch-all `config.path`.
+  // 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 });
 
   const processRunPath = JSON.stringify(AGENT_CHAT_PROCESS_RUN_PATH);
@@ -1589,12 +1609,12 @@ 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).
-// We are reached at this function's DIRECT url
-// (/.netlify/functions/${backgroundName}); rewrite the path to PROCESS_RUN_PATH
-// so Nitro routes it to the _process-run plugin, preserving method, ALL headers
-// (the HMAC Authorization: Bearer MUST survive — the plugin verifies it) and the
-// body. We clone the incoming Request with only its URL pathname rewritten;
-// query + origin are preserved.
+// 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) {
   cachedHandler ??= (await import("./main.mjs")).default;
   const url = new URL(request.url);
@@ -1615,13 +1635,12 @@ export const config = {
   name: "agent background handler",
   generator: "agent-native build",
   // background: true makes Netlify invoke this ASYNCHRONOUSLY (immediate HTTP
-  // 202 ack) with the 15-minute budget. NO custom \`path\`: that keeps the
-  // function reachable at its DEFAULT url /.netlify/functions/${backgroundName},
-  // which BYPASSES Nitro's /* catch-all. The previous version set a custom
-  // \`config.path\` and Netlify routed the process-run path to the SYNCHRONOUS
-  // catch-all instead (verified live: a synchronous 401 from the handler, not a
-  // 202 async ack). See Netlify docs: build/functions/background-functions +
-  // build/functions/configuration.
+  // 202 ack) with the 15-minute budget (Netlify docs:
+  // 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,
   nodeBundler: "none",
   includedFiles: ["**"],
@@ -1630,10 +1649,13 @@ export const config = {
 `;
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), entry);
   console.log(
-    `[build] Emitted standalone durable-background function "${backgroundName}" ` +
-      `at /.netlify/functions/${backgroundName} (async, rewrites to ` +
-      `${AGENT_CHAT_PROCESS_RUN_PATH}). REQUIRES real-deploy verification of ` +
-      `Netlify async invocation — see docs/design/durable-agent-runs.md.`,
+    `[build] Emitted durable-background function "${backgroundName}" into the ` +
+      `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.`,
   );
 }