@agent-native/core 0.70.2 → 0.71.0

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

@@ -34,6 +34,7 @@ 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_NATIVE_SOCIAL_IMAGE_ALT,
   AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER,
@@ -1476,6 +1477,85 @@ export function findInstalledResvgPackages(
     .map(([packageName, packageDir]) => ({ packageName, packageDir }));
 }
 
+/**
+ * Deploy-time gate for emitting the second `-background` Netlify function.
+ * Reads the same env flag the runtime gate uses
+ * (`AGENT_CHAT_DURABLE_BACKGROUND`). Off by default — when off, the deploy
+ * emits exactly one function (today's behavior, byte-for-byte).
+ */
+export function isDurableBackgroundDeployEnabled(): boolean {
+  const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
+  if (raw == null) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+/**
+ * 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`).
+ *
+ * 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.
+ *
+ * ⚠️ REAL-DEPLOY VERIFICATION REQUIRED. Whether Netlify routes
+ * `/_agent-native/agent-chat/_process-run` to this `-background` function (and
+ * invokes it asynchronously with the 15-min budget) vs the synchronous Nitro
+ * function cannot be verified in this environment — Nitro owns the primary
+ * function's routing manifest, and the precedence between the two functions for
+ * that path is a Netlify runtime behavior. If routing resolves to the
+ * synchronous function, the run still completes via the existing 40s
+ * soft-timeout path (no durable win, no regression). See
+ * docs/design/durable-agent-runs.md (Open risks #1).
+ */
+export function emitSingleTemplateNetlifyBackgroundFunction(
+  projectCwd: string,
+): void {
+  const functionsDir = path.join(projectCwd, ".netlify", "functions-internal");
+  const serverDir = path.join(functionsDir, "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.
+    console.warn(
+      "[build] Durable-background emit skipped: expected Nitro Netlify function " +
+        "at .netlify/functions-internal/server/main.mjs was not found.",
+    );
+    return;
+  }
+  const backgroundName = "server-agent-background";
+  const dest = path.join(functionsDir, backgroundName);
+  fs.rmSync(dest, { recursive: true, force: true });
+  copyDir(serverDir, dest);
+  // Drop the original Nitro entry so our background entry is the entrypoint.
+  fs.rmSync(path.join(dest, "server.mjs"), { force: true });
+
+  const entry = `let cachedHandler;
+
+export default async function handler(...args) {
+  cachedHandler ??= (await import("./main.mjs")).default;
+  return cachedHandler(...args);
+}
+
+export const config = {
+  name: "agent background handler",
+  generator: "agent-native build",
+  path: ${JSON.stringify([AGENT_CHAT_PROCESS_RUN_PATH])},
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+  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.`,
+  );
+}
+
 function copyInstalledLibsqlNativePackages(serverDir: string | undefined) {
   if (!serverDir || !fs.existsSync(serverDir)) return;
   const nodeModulesRoots = nodeModulesAncestors(cwd);
@@ -1938,6 +2018,22 @@ export default bundle;
     copyInstalledFfmpegStaticPackage(nitro.options.output.serverDir);
   }
 
+  // Durable background agent runs (off by default). Additive ONLY: emits a
+  // SECOND Netlify function whose name ends in `-background` re-exporting the
+  // same handler bundle, so the chat `_process-run` POST lands on Netlify's
+  // async (15-min) function. When the flag is off this is a no-op and the
+  // single-function deploy is byte-for-byte unchanged.
+  if (preset === "netlify" && isDurableBackgroundDeployEnabled()) {
+    try {
+      emitSingleTemplateNetlifyBackgroundFunction(cwd);
+    } catch (err) {
+      console.warn(
+        "[build] Failed to emit durable-background Netlify function (non-fatal):",
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+
   // Resolve remaining bare npm imports by bundling them into _libs/.
   // Nitro sometimes leaves small packages as externals even with noExternals.
   if (preset.startsWith("cloudflare") || preset.startsWith("deno")) {

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

@@ -32,6 +32,7 @@ import {
   collectImmutableAssetPaths,
   IMMUTABLE_ASSET_CACHE_HEADERS,
 } from "./immutable-assets.js";
+import { AGENT_CHAT_PROCESS_RUN_PATH } from "../agent/durable-background.js";
 
 export type WorkspaceDeployPreset = "cloudflare_pages" | "netlify" | "vercel";
 
@@ -665,6 +666,126 @@ function copyNetlifyFunctionIntoWorkspace(
   fs.rmSync(dest, { recursive: true, force: true });
   copyDir(src, dest);
   patchNetlifyFunctionEntry(dest, app, workspaceApps, staticDir);
+
+  // Durable background agent runs (off by default). Additive ONLY: when the
+  // flag is off this emits nothing and the single-function deploy is unchanged.
+  if (isDurableBackgroundDeployEnabled()) {
+    emitNetlifyBackgroundFunction(workspaceRoot, app, src, workspaceApps);
+  }
+}
+
+/**
+ * Deploy-time gate for emitting the second `-background` Netlify function. Reads
+ * the same env flag the runtime gate uses (`AGENT_CHAT_DURABLE_BACKGROUND`).
+ * Off by default — when off, the deploy emits exactly one function per app
+ * (today's behavior, byte-for-byte).
+ */
+function isDurableBackgroundDeployEnabled(): boolean {
+  const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
+  if (raw == null) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * ⚠️ 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.
+ */
+function emitNetlifyBackgroundFunction(
+  workspaceRoot: string,
+  app: string,
+  srcServerDir: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+): void {
+  // Name MUST end in `-background` for Netlify async invocation.
+  const backgroundName = `${app}-agent-background`;
+  const dest = path.join(netlifyFunctionsDir(workspaceRoot), backgroundName);
+  fs.rmSync(dest, { recursive: true, force: true });
+  copyDir(srcServerDir, dest);
+
+  const basePath = `/${app}`;
+  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
+  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
+    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`.
+  const processRunPath = `${basePath}${AGENT_CHAT_PROCESS_RUN_PATH}`;
+  const pathConfig = [processRunPath];
+  const server = `const basePath = ${JSON.stringify(basePath)};
+
+function setBasePathEnv() {
+  const processRef = globalThis.process ??= { env: {} };
+  processRef.env ??= {};
+  Object.assign(processRef.env, {
+    AGENT_NATIVE_WORKSPACE: "1",
+    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    APP_BASE_PATH: basePath,
+    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE: "1",
+    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    VITE_APP_BASE_PATH: basePath,
+    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
+    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
+  });
+}
+
+setBasePathEnv();
+
+let cachedHandler;
+
+export default async function handler(...args) {
+  setBasePathEnv();
+  cachedHandler ??= (await import("./main.mjs")).default;
+  return cachedHandler(...args);
+}
+
+export const config = {
+  name: ${JSON.stringify(`${app} agent background handler`)},
+  generator: "agent-native workspace deploy",
+  path: ${JSON.stringify(pathConfig)},
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+  // Remove the original Nitro entry (server.mjs) so only our background entry
+  // is the function entrypoint, mirroring patchNetlifyFunctionEntry.
+  fs.rmSync(path.join(dest, "server.mjs"), { force: true });
+  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.`,
+  );
 }
 
 function patchNetlifyFunctionEntry(

package/corpus/core/src/mcp/build-server.ts

@@ -952,12 +952,13 @@ async function resolveMcpAppResource(
 ): Promise<ResolvedMcpAppResource | null> {
   const resource = entry.mcpApp?.resource;
   if (!resource) return null;
-  // Inline MCP App embeds are gated behind the deploy-toggleable kill switch
-  // (default off). When disabled, advertise no resource and attach no embed
-  // reference so hosts fall back to the tool's deep-link text instead of an
-  // iframe. This is the single chokepoint for every embed surface: tools/list
-  // descriptor meta, tools/call result meta, resources/list, resources/read.
-  if (!requestMeta?.inlineMcpApps) return null;
+  // NB: the inline kill switch is intentionally NOT enforced here. This
+  // resolver also backs `resources/read`, which must keep serving the shell
+  // for a URI the host already holds (e.g. a cached descriptor) so it degrades
+  // gracefully instead of throwing a hard `-32603`. The switch is enforced at
+  // the *advertisement/render* sites (`tools/list` descriptor meta,
+  // `tools/call` result meta, `resources/list`) so disabled embeds never get
+  // advertised in the first place.
   const resolvedUri = getMcpAppResourceUri(config, actionName, entry);
   if (!resolvedUri) return null;
   const description = resource.description ?? entry.tool.description;
@@ -1006,6 +1007,9 @@ async function getMcpAppResources(
   actions: Record<string, ActionEntry>,
   requestMeta?: MCPRequestMeta,
 ): Promise<ResolvedMcpAppResource[]> {
+  // Advertisement path (resources/list + resources/templates/list): suppressed
+  // by the inline kill switch so disabled embeds are never listed.
+  if (!requestMeta?.inlineMcpApps) return [];
   const resources = await Promise.all(
     Object.entries(actions).map(([name, entry]) =>
       resolveMcpAppResourceSafely(config, name, entry, requestMeta),
@@ -1383,7 +1387,10 @@ export async function createMCPServerForRequest(
               : {};
           const toolMeta = {
             ...rawToolMeta,
-            ...(mcpAppResource
+            // Advertisement path: only tag the tool with its inline-embed
+            // descriptor when the kill switch is on, so disabled embeds never
+            // prompt a host to render/read the `ui://` resource.
+            ...(mcpAppResource && requestMeta?.inlineMcpApps
               ? {
                   ...openAiToolDescriptorMeta(mcpAppResource),
                   [MCP_APP_RESOURCE_URI_META_KEY]: mcpAppResource.uri,
@@ -1533,12 +1540,14 @@ export async function createMCPServerForRequest(
           !!mcpResult.raw &&
           typeof mcpResult.raw === "object" &&
           (mcpResult.raw as Record<string, unknown>).isError === true;
-        const mcpAppResource = await resolveMcpAppResourceSafely(
-          config,
-          name,
-          entry,
-          requestMeta,
-        );
+        // Render path: only treat the result as an inline embed when the kill
+        // switch is on. When off, `mcpAppResource` is null so every embed
+        // branch below degrades to the plain deep-link artifacts the tool would
+        // otherwise return — no `openai/outputTemplate`, no minted embed-start,
+        // no embed structuredContent — so the host shows a link, not an iframe.
+        const mcpAppResource = requestMeta?.inlineMcpApps
+          ? await resolveMcpAppResourceSafely(config, name, entry, requestMeta)
+          : null;
         const rawResultForClient = mcpAppResource
           ? await withServerMintedMcpAppEmbedStart(rawResult, requestMeta)
           : rawResult;

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -150,6 +150,10 @@ import {
   hasConfiguredA2ASecret,
   isA2AProductionRuntime,
 } from "../a2a/auth-policy.js";
+import {
+  AGENT_CHAT_PROCESS_RUN_PATH,
+  prepareProcessRunRequest,
+} from "../agent/durable-background.js";
 import {
   getBuilderBrowserConnectUrlForOwner,
   resolveBuilderBranchProjectId,
@@ -7695,6 +7699,134 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
         }),
       );
 
+      // Shared per-request invocation: resolve auth/org/timezone context, then
+      // pick the dev/prod/anonymous handler and run it inside the request
+      // context. Used by the main chat POST and by the durable-background
+      // `_process-run` processor route (which re-enters the same handler set as
+      // the background worker), so both go through identical context + handler
+      // selection.
+      const invokeAgentChatHandler = async (event: any) => {
+        // Resolve per-request auth context
+        const ownerContext = await resolveOwnerContext(event);
+        const owner = ownerContext.owner;
+
+        // Resolve org ID: explicit callback > session.orgId from Better Auth
+        // > implicit org membership. Better Auth leaves session.orgId null
+        // until the user explicitly switches orgs, so a fresh signup with
+        // implicit membership (e.g. domain-matched org) would otherwise see
+        // no org-scoped credentials. getOrgContext() does the same DB lookup
+        // the /builder/status endpoint uses to decide "Connected".
+        let resolvedOrgId: string | undefined;
+        if (options?.resolveOrgId) {
+          resolvedOrgId = (await options.resolveOrgId(event)) ?? undefined;
+        } else {
+          try {
+            const session = await getSession(event);
+            resolvedOrgId = session?.orgId ?? undefined;
+          } catch {
+            // Session not available
+          }
+          if (!resolvedOrgId) {
+            try {
+              const { getOrgContext } = await import("../org/context.js");
+              const ctx = await getOrgContext(event);
+              resolvedOrgId = ctx.orgId ?? undefined;
+            } catch {
+              // org_members table may not exist yet on first boot
+            }
+          }
+        }
+
+        // Propagate the caller's IANA timezone from `x-user-timezone` so that
+        // tool calls made by the agent (e.g. log-meal with no explicit date)
+        // resolve "today" in the user's local timezone instead of server UTC.
+        const tzRaw = getHeader(event, "x-user-timezone");
+        const timezone =
+          typeof tzRaw === "string" &&
+          tzRaw.trim().length > 0 &&
+          tzRaw.trim().length < 64
+            ? tzRaw.trim()
+            : undefined;
+
+        return runWithRequestContext(
+          {
+            userEmail: owner,
+            userName: ownerContext.name,
+            orgId: resolvedOrgId,
+            timezone,
+          },
+          () => {
+            // App-rendered chat can't host direct code edits — HMR/full
+            // reloads would kill the same chat surface mid-run. Force the
+            // prod handler (no shell / no fs); the prompt block injected by
+            // `prodHandler.systemPrompt` then steers source changes to a
+            // separate agent surface such as Builder or the dev frame.
+            const blockInProductCodeEditing =
+              shouldBlockInProductCodeEditing(event);
+            const handler =
+              ownerContext.anonymous && anonymousHandler
+                ? anonymousHandler
+                : !blockInProductCodeEditing && currentDevMode && devHandler
+                  ? devHandler
+                  : prodHandler;
+            return handler(event);
+          },
+        );
+      };
+
+      // ─── Durable background agent-chat run processor ──────────────────────
+      // Self-fire target for a long chat turn. The foreground POST claims the
+      // run slot, inserts the run row, and `fireInternalDispatch`es here; this
+      // route runs INSIDE the Netlify background function (15-min budget). It
+      // HMAC-verifies the dispatch (same internal-token scheme as the agent-
+      // teams / A2A / webhook processors), injects the background-run marker,
+      // and re-enters the SAME agent-chat handler as the background worker,
+      // which runs the full multi-step turn inline with the ~13min soft
+      // timeout. With AGENT_CHAT_DURABLE_BACKGROUND off, the foreground never
+      // dispatches here, so this route is never exercised.
+      getH3App(nitroApp).use(
+        AGENT_CHAT_PROCESS_RUN_PATH,
+        defineEventHandler(async (event) => {
+          if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+          }
+          // Consume the body ONCE (h3 v2's web Request stream is single-use).
+          let processBody: any;
+          try {
+            processBody = await readBody(event);
+          } catch {
+            setResponseStatus(event, 400);
+            return { error: "Invalid request body" };
+          }
+
+          // Validate + HMAC-authenticate the self-dispatch and prepare the
+          // background-worker body. Pure decision (unit-tested in
+          // durable-background.spec.ts); the route only wires it to h3.
+          const prepared = prepareProcessRunRequest(
+            processBody,
+            getHeader(event, "authorization"),
+          );
+          if (!prepared.ok) {
+            setResponseStatus(event, prepared.status);
+            return { error: prepared.error };
+          }
+
+          // Stash the verified+augmented body for the handler — the body stream
+          // is already consumed, so the handler reads this instead.
+          (event as any).context = (event as any).context ?? {};
+          (event as any).context.__agentChatBackgroundBody = prepared.body;
+
+          try {
+            return await invokeAgentChatHandler(event);
+          } catch (err: any) {
+            console.error("[agent-chat] _process-run failed:", err);
+            setResponseStatus(event, 500);
+            return { error: "process-run failed" };
+          }
+        }),
+      );
+
       // Mount the main chat handler — delegates to dev or prod handler based on current mode.
       // This is mounted last because h3's use() is prefix-based, meaning /_agent-native/agent-chat
       // also matches /_agent-native/agent-chat/threads/... — we skip sub-path requests here so the
@@ -7713,72 +7845,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             return { error: "Not found" };
           }
 
-          // Resolve per-request auth context
-          const ownerContext = await resolveOwnerContext(event);
-          const owner = ownerContext.owner;
-
-          // Resolve org ID: explicit callback > session.orgId from Better Auth
-          // > implicit org membership. Better Auth leaves session.orgId null
-          // until the user explicitly switches orgs, so a fresh signup with
-          // implicit membership (e.g. domain-matched org) would otherwise see
-          // no org-scoped credentials. getOrgContext() does the same DB lookup
-          // the /builder/status endpoint uses to decide "Connected".
-          let resolvedOrgId: string | undefined;
-          if (options?.resolveOrgId) {
-            resolvedOrgId = (await options.resolveOrgId(event)) ?? undefined;
-          } else {
-            try {
-              const session = await getSession(event);
-              resolvedOrgId = session?.orgId ?? undefined;
-            } catch {
-              // Session not available
-            }
-            if (!resolvedOrgId) {
-              try {
-                const { getOrgContext } = await import("../org/context.js");
-                const ctx = await getOrgContext(event);
-                resolvedOrgId = ctx.orgId ?? undefined;
-              } catch {
-                // org_members table may not exist yet on first boot
-              }
-            }
-          }
-
-          // Propagate the caller's IANA timezone from `x-user-timezone` so that
-          // tool calls made by the agent (e.g. log-meal with no explicit date)
-          // resolve "today" in the user's local timezone instead of server UTC.
-          const tzRaw = getHeader(event, "x-user-timezone");
-          const timezone =
-            typeof tzRaw === "string" &&
-            tzRaw.trim().length > 0 &&
-            tzRaw.trim().length < 64
-              ? tzRaw.trim()
-              : undefined;
-
-          return runWithRequestContext(
-            {
-              userEmail: owner,
-              userName: ownerContext.name,
-              orgId: resolvedOrgId,
-              timezone,
-            },
-            () => {
-              // App-rendered chat can't host direct code edits — HMR/full
-              // reloads would kill the same chat surface mid-run. Force the
-              // prod handler (no shell / no fs); the prompt block injected by
-              // `prodHandler.systemPrompt` then steers source changes to a
-              // separate agent surface such as Builder or the dev frame.
-              const blockInProductCodeEditing =
-                shouldBlockInProductCodeEditing(event);
-              const handler =
-                ownerContext.anonymous && anonymousHandler
-                  ? anonymousHandler
-                  : !blockInProductCodeEditing && currentDevMode && devHandler
-                    ? devHandler
-                    : prodHandler;
-              return handler(event);
-            },
-          );
+          return invokeAgentChatHandler(event);
         }),
       );
 

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -174,12 +174,31 @@ pnpm action update-dashboard --dashboardId weekly-metrics --config '<full json>'
 
 After a mutation, navigate to the dashboard if the user is elsewhere. The app syncs through the framework's polling/query invalidation path.
 
+## Building Large First-Party Dashboards (compose-dashboard)
+
+For a **first-party analytics** dashboard, prefer `compose-dashboard` over hand-authoring a big `update-dashboard` config. You name the metrics; the SERVER expands each into a full, validated panel (SQL + chart config) from the shipped metric catalog and saves them in ONE atomic call. This avoids the failure mode where the agent must stream a giant multi-panel `update-dashboard` argument inside the ~40s budget — that big tool-call can't be resumed mid-stream and is all-or-nothing on validation, so the agent thrashes (repeated update-dashboard + tool-search, never landing).
+
+- **Never hand-author large first-party configs panel-by-panel.** Call `compose-dashboard` with the metric keys instead.
+- Unknown metric keys are skipped and reported in `unknownMetrics` (not fatal). Each panel's SQL is validated independently — valid panels save, invalid ones are reported in `invalidMetrics`.
+- By default (no `overwrite`), composing into an existing dashboard APPENDS the new panels and skips ids already present. `overwrite: true` replaces the whole config.
+- Each metric accepts an optional per-metric `window` of `'30d' | '90d' | 'all'` (only affects windowed virality/time metrics) and `title` / `chartType` / `width` overrides.
+- Returns `{ dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, skippedExistingIds }` — report `panelCount` as proof-of-done.
+
+Available metric keys: `total-signups`, `signups-over-time`, `signups-by-template`, `sessions-by-app`, `sessions-over-time`, `signed-in-vs-anon`, `total-template-clicks`, `total-demo-clicks`, `total-cli-copies`, `template-interest-over-time`, `clicks-by-template`, `demo-clicks-by-template`, `cli-copies-by-template`, `cli-copies-over-time`, `pageviews-over-time`, `referred-signups-30d`, `viral-signup-share-30d`, `clip-share-signups-30d`, `signups-by-referral-source`, `referred-signups-over-time`, `top-referrers`, `share-funnel-30d`, `viral-participation-rate-90d`, `viral-coefficient-90d`, `activated-referrers-90d`.
+
+```bash
+# Build a large first-party dashboard in ONE call (server generates the panels)
+pnpm action compose-dashboard --dashboardId first-party-overview --title "First-Party Overview" \
+  --metrics '["total-signups","signups-over-time","signups-by-template","sessions-by-app","viral-coefficient-90d","top-referrers","share-funnel-30d"]'
+```
+
 ## Reliable Bulk Edits
 
 This is the dashboard-specific application of the framework-wide `reliable-mutations` skill — read that for the general rule (one atomic write, verify end state, report proof-of-done).
 
 Hosted agent runs have a **~40s budget**. Many sequential `update-dashboard` calls (one per panel, plus schema-discovery calls) will blow that budget and leave the dashboard in a partial state — earlier inserts looked like they succeeded (✓), but nothing actually persisted. Avoid this:
 
+- **For a large first-party dashboard, use `compose-dashboard`** (see the section above): name the metrics, the server generates the panels in one call. Do not hand-author the big config.
 - **Batch ALL changes into ONE `update-dashboard` call.** A single `update-dashboard` is atomic: it applies every op to an in-memory config, validates all panel SQL, then upserts once. Never loop the action.
   - To add N panels, pass N ops in one call: `ops: [{op:"insert", path:"/panels/-", value:<panel>}, … ]` (`/panels/-` appends to the end).
   - The `ops` format needs no discovery: each op is `{ op, path, from?, value? }`, `op ∈ set | replace | remove | insert | move | move-before`, and `path` is a JSON Pointer (e.g. `/panels/3`, `/panels/3/title`, `/name`).

package/corpus/templates/analytics/AGENTS.md

@@ -83,6 +83,14 @@ details live in `.agents/skills/`.
 
 ## Dashboard Template Catalog
 
+- To build or extend a LARGE first-party dashboard, prefer `compose-dashboard`:
+  name the metrics and the server generates the validated SQL/config for every
+  panel in ONE fast call. Do NOT hand-author big `update-dashboard` configs
+  panel-by-panel or loop `update-dashboard` — streaming a giant multi-panel
+  argument inside the ~40s budget fails and thrashes. Unknown metric keys are
+  skipped and reported; per-panel SQL validates independently; existing
+  dashboards append by default (`overwrite: true` replaces). Report the returned
+  `panelCount` as proof-of-done.
 - `list-dashboard-templates` lists source-controlled dashboard templates with
   `id`, category, data sources, panel count, and installed dashboard IDs.
 - `install-dashboard-template` installs a catalog template into normal