@agent-native/core 0.75.0 → 0.75.2

package/corpus/README.md

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

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @agent-native/core
 
+## 0.75.2
+
+### Patch Changes
+
+- 4b3543d: Durable background agent-chat runs now actually receive Netlify's 15-min async
+  budget by reaching a STANDALONE background function at its DIRECT url, bypassing
+  Nitro's synchronous `/*` catch-all.
+
+  The previous emit wrote the background function into `.netlify/functions-internal`
+  with a custom `config.path` of the `_process-run` route. A custom `config.path`
+  makes a function reachable ONLY at that path (not at its default function url),
+  `functions-internal` is not exposed at a default url, and Netlify routed
+  `/_agent-native/agent-chat/_process-run` to the synchronous Nitro `server`
+  catch-all instead — so the worker was capped at the ~60s wall and degraded to
+  40s-chunked runs (confirmed live: a POST to the process-run path returned a
+  synchronous 401 from the handler rather than a 202 async ack).
+
+  The build now emits a standalone function into the STANDARD
+  `.netlify/functions/server-agent-background` dir with `background: true` and NO
+  custom `path`, so Netlify exposes it at `/.netlify/functions/server-agent-background`
+  and invokes it asynchronously (immediate 202 ack, 15-min budget). Its entry sets
+  `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true` at cold start and rewrites
+  the incoming request path back to the `_process-run` route before delegating to
+  the Nitro handler, preserving the method, all headers (the HMAC
+  `Authorization: Bearer` the plugin verifies survives the rewrite), and the body.
+  The foreground self-dispatch (and server-driven continuation chunks) now target
+  that direct url on hosted Netlify via a shared `resolveAgentChatProcessRunDispatchPath`
+  helper, and stay on the framework route everywhere else. The graceful inline
+  40s fallback on a dispatch fast-fail is unchanged.
+
+## 0.75.1
+
+### Patch Changes
+
+- 98b89e2: Durable background agent-chat runs now actually receive Netlify's 15-min async
+  budget. The emitted `-background` function declared a custom `config.path` but
+  omitted `background: true`, so Netlify served it SYNCHRONOUSLY (~60s) — the
+  `config` object overrides the legacy `-background` filename convention — and the
+  durable worker was capped at the 60s wall (it degraded to 40s-chunked runs and
+  never used the 15-min budget). The emit now sets `background: true` (immediate
+  202 ack + 15-min execution) and force-marks the background runtime in the
+  function entry so the worker reliably takes the ~13-min soft-timeout regardless
+  of the deployed Lambda name. Root cause confirmed with a live prod routing probe
+  (POST to the process-run path returned a synchronous 401 from the handler
+  instead of a 202 async ack).
+
 ## 0.75.0
 
 ### Minor Changes

package/corpus/core/package.json

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

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

@@ -51,6 +51,62 @@ import {
 export const AGENT_CHAT_PROCESS_RUN_PATH =
   "/_agent-native/agent-chat/_process-run";
 
+/**
+ * Name of the standalone Netlify background function the build emits (see
+ * `emitSingleTemplateNetlifyBackgroundFunction` in deploy/build.ts). Shared so
+ * the emit and the dispatch-path helper below can never drift on the name.
+ *
+ * MUST end in `-background` — both because that is the conventional Netlify
+ * async-function suffix and because `isInBackgroundFunctionRuntime()` reads the
+ * `AWS_LAMBDA_FUNCTION_NAME` `-background` suffix as a secondary runtime signal.
+ */
+export const AGENT_BACKGROUND_FUNCTION_NAME = "server-agent-background";
+
+/**
+ * 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).
+ */
+export const AGENT_BACKGROUND_FUNCTION_URL_PATH = `/.netlify/functions/${AGENT_BACKGROUND_FUNCTION_NAME}`;
+
+/**
+ * Resolve the path the foreground POST should self-dispatch the chat background
+ * worker to.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export function resolveAgentChatProcessRunDispatchPath(): string {
+  if (
+    process.env.NETLIFY &&
+    process.env.NETLIFY !== "false" &&
+    process.env.NETLIFY_LOCAL !== "true"
+  ) {
+    return AGENT_BACKGROUND_FUNCTION_URL_PATH;
+  }
+  return AGENT_CHAT_PROCESS_RUN_PATH;
+}
+
 /**
  * Env flag for durable background runs. DEFAULT-ON: unset means enabled; an app
  * opts OUT with an explicit falsy value (`false`/`0`/`no`/`off`).
@@ -112,11 +168,23 @@ export function isHostedRuntimeForDurableBackground(): boolean {
  * hard wall and get killed at 60s, then re-dispatch/resume in a wasteful loop.
  * So the 13-min budget is taken ONLY when this returns true.
  *
- * Falls back to the explicit `AGENT_CHAT_FORCE_BACKGROUND_RUNTIME` env (truthy)
- * for hosts that don't expose a `-background`-suffixed function name but where
- * the operator has confirmed a long async budget. Off by default.
+ * The PRIMARY signal is a `globalThis` marker the emitted background function's
+ * entry sets at cold start — the deployed Lambda name is not guaranteed to end
+ * in `-background` on Netlify, so the entry marks its own runtime. A `globalThis`
+ * flag (not `process.env`) keeps the no-env-mutation guard satisfied and carries
+ * no cross-request state (set once per isolate). The `AWS_LAMBDA_FUNCTION_NAME`
+ * suffix and the explicit `AGENT_CHAT_FORCE_BACKGROUND_RUNTIME` env (truthy) are
+ * additional signals — the latter an operator escape hatch. Off by default.
  */
 export function isInBackgroundFunctionRuntime(): boolean {
+  // Set by the emitted `-background` function entry at cold start (the primary,
+  // most reliable signal — see the emit in deploy/build.ts).
+  if (
+    (globalThis as Record<string, unknown>)
+      .__AGENT_NATIVE_BACKGROUND_RUNTIME__ === true
+  ) {
+    return true;
+  }
   const lambdaName = process.env.AWS_LAMBDA_FUNCTION_NAME;
   if (
     typeof lambdaName === "string" &&

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

@@ -65,10 +65,10 @@ import {
 } from "./run-manager.js";
 import type { ActiveRun } from "./run-manager.js";
 import {
-  AGENT_CHAT_PROCESS_RUN_PATH,
   AGENT_CHAT_BACKGROUND_RUN_FIELD,
   isAgentChatDurableBackgroundEnabled,
   isInBackgroundFunctionRuntime,
+  resolveAgentChatProcessRunDispatchPath,
 } from "./durable-background.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { readBody } from "../server/h3-helpers.js";
@@ -4394,7 +4394,15 @@ export function createProductionAgentHandler(
       try {
         await fireInternalDispatch({
           event,
-          path: AGENT_CHAT_PROCESS_RUN_PATH,
+          // 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).
+          path: resolveAgentChatProcessRunDispatchPath(),
           taskId: runId,
           body: {
             ...body,
@@ -4636,7 +4644,12 @@ export function createProductionAgentHandler(
                 try {
                   await fireInternalDispatch({
                     event,
-                    path: AGENT_CHAT_PROCESS_RUN_PATH,
+                    // 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.
+                    path: resolveAgentChatProcessRunDispatchPath(),
                     taskId: nextRunId,
                     body: {
                       ...body,

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

@@ -394,14 +394,16 @@ sign-in at setup — this is intended), so the first tool call in that client do
 not hit an OAuth wall:
 
 \`\`\`bash
-npx @agent-native/core@latest skills add visual-plan
+npx @agent-native/core@latest skills add visual-plans
 \`\`\`
 
 After that, \`/visual-plan\` and \`/visual-recap\` are the two installed slash
-commands. The other planning modes (\`create-ui-plan\`, \`create-prototype-plan\`,
-\`create-plan-design\`, \`create-visual-questions\`) are MCP tools reachable from
-\`/visual-plan\`, not separate slash commands. Pass \`--no-connect\` to register
-the connector without authenticating, then run
+commands. If you only need one command, use \`skills add visual-plan\` or
+\`skills add visual-recap\` instead. The other planning modes
+(\`create-ui-plan\`, \`create-prototype-plan\`, \`create-plan-design\`,
+\`create-visual-questions\`) are MCP tools reachable from \`/visual-plan\`, not
+separate slash commands. Pass \`--no-connect\` to register the connector without
+authenticating, then run
 \`npx @agent-native/core@latest connect https://plan.agent-native.com --client all\`
 whenever you are ready, or choose a narrower \`--client\`. Auth and MCP tool
 loading are per client config/session.
@@ -410,7 +412,7 @@ loading are per client config/session.
 install with \`--mode local-files\`:
 
 \`\`\`bash
-npx @agent-native/core@latest skills add visual-plan --mode local-files
+npx @agent-native/core@latest skills add visual-plans --mode local-files
 \`\`\`
 
 This mode does not register the Plan MCP connector. Before authoring structured
@@ -1648,14 +1650,16 @@ sign-in at setup — this is intended), so the first tool call in that client do
 not hit an OAuth wall:
 
 \`\`\`bash
-npx @agent-native/core@latest skills add visual-plan
+npx @agent-native/core@latest skills add visual-plans
 \`\`\`
 
 After that, \`/visual-plan\` and \`/visual-recap\` are the two installed slash
-commands. The other planning modes (\`create-ui-plan\`, \`create-prototype-plan\`,
-\`create-plan-design\`, \`create-visual-questions\`) are MCP tools reachable from
-\`/visual-plan\`, not separate slash commands. Pass \`--no-connect\` to register
-the connector without authenticating, then run
+commands. If you only need one command, use \`skills add visual-plan\` or
+\`skills add visual-recap\` instead. The other planning modes
+(\`create-ui-plan\`, \`create-prototype-plan\`, \`create-plan-design\`,
+\`create-visual-questions\`) are MCP tools reachable from \`/visual-plan\`, not
+separate slash commands. Pass \`--no-connect\` to register the connector without
+authenticating, then run
 \`npx @agent-native/core@latest connect https://plan.agent-native.com --client all\`
 whenever you are ready, or choose a narrower \`--client\`. Auth and MCP tool
 loading are per client config/session.

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

@@ -34,7 +34,10 @@ import {
 } from "./workspace-core.js";
 import { generateActionRegistryForProject } from "../vite/action-types-plugin.js";
 import { mcpEmbedStaticAssetRouteRules } from "../shared/mcp-embed-headers.js";
-import { AGENT_CHAT_PROCESS_RUN_PATH } from "../agent/durable-background.js";
+import {
+  AGENT_BACKGROUND_FUNCTION_NAME,
+  AGENT_CHAT_PROCESS_RUN_PATH,
+} from "../agent/durable-background.js";
 import {
   AGENT_NATIVE_SOCIAL_IMAGE_ALT,
   AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER,
@@ -1502,31 +1505,52 @@ export function isDurableBackgroundDeployEnabled(): boolean {
 }
 
 /**
- * Single-template Netlify build: emit a SECOND function whose name ends in
- * `-background`, re-exporting the same `main.mjs` handler bundle, so the chat
- * `_process-run` POST lands on Netlify's async (15-min) function instead of the
- * synchronous one. Additive + flag-gated (see `isDurableBackgroundDeployEnabled`).
+ * Single-template Netlify build: emit 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.
+ * 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
+ *      (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.
  *
- * 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.
+ * 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.
  *
- * ⚠️ 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).
+ * 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).
  */
 export function emitSingleTemplateNetlifyBackgroundFunction(
   projectCwd: string,
 ): void {
-  const functionsDir = path.join(projectCwd, ".netlify", "functions-internal");
-  const serverDir = path.join(functionsDir, "server");
+  const internalDir = path.join(projectCwd, ".netlify", "functions-internal");
+  const serverDir = path.join(internalDir, "server");
   if (!fs.existsSync(path.join(serverDir, "main.mjs"))) {
     // Nitro output layout differs from what we expected — skip rather than
     // guess. The single-function deploy is unaffected.
@@ -1536,24 +1560,69 @@ export function emitSingleTemplateNetlifyBackgroundFunction(
     );
     return;
   }
-  const backgroundName = "server-agent-background";
+  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 });
   fs.rmSync(dest, { recursive: true, force: true });
   copyDir(serverDir, dest);
-  // Drop the original Nitro entry so our background entry is the entrypoint.
+  // Drop the original Nitro `/*` entry so our standalone 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 entry = `let cachedHandler;
-
-export default async function handler(...args) {
+  const processRunPath = JSON.stringify(AGENT_CHAT_PROCESS_RUN_PATH);
+  const entry = `// Mark this isolate as the durable background runtime BEFORE the handler
+// bundle is imported, so isInBackgroundFunctionRuntime() reliably returns true
+// in this function. The deployed Lambda name is NOT guaranteed to end in
+// "-background" (Netlify may mangle/prefix it), so we cannot depend on
+// AWS_LAMBDA_FUNCTION_NAME alone. A globalThis flag (NOT process.env) avoids the
+// no-env-mutation guard and carries no cross-request state — it is a static,
+// set-once isolate marker read back by isInBackgroundFunctionRuntime().
+globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
+
+// The framework route the Nitro router dispatches to (the _process-run plugin).
+const PROCESS_RUN_PATH = ${processRunPath};
+
+let cachedHandler;
+
+// 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.
+export default async function handler(request) {
   cachedHandler ??= (await import("./main.mjs")).default;
-  return cachedHandler(...args);
+  const url = new URL(request.url);
+  url.pathname = PROCESS_RUN_PATH;
+  // Read the body once and pass it through. GET/HEAD have no body.
+  const method = request.method || "POST";
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await request.text() : undefined;
+  const rewritten = new Request(url.toString(), {
+    method,
+    headers: request.headers,
+    body,
+  });
+  return cachedHandler(rewritten);
 }
 
 export const config = {
   name: "agent background handler",
   generator: "agent-native build",
-  path: ${JSON.stringify([AGENT_CHAT_PROCESS_RUN_PATH])},
+  // 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.
+  background: true,
   nodeBundler: "none",
   includedFiles: ["**"],
   preferStatic: false,
@@ -1561,9 +1630,10 @@ export const config = {
 `;
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), entry);
   console.log(
-    `[build] Emitted durable-background function "${backgroundName}" ` +
-      `(path ${AGENT_CHAT_PROCESS_RUN_PATH}). REQUIRES real-deploy verification ` +
-      `of Netlify async routing — see docs/design/durable-agent-runs.md.`,
+    `[build] Emitted 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.`,
   );
 }
 

package/corpus/core/src/templates/default/_gitignore

@@ -10,6 +10,7 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+node-compile-cache/
 dist
 dist-ssr
 *.local

package/corpus/core/src/templates/headless/_gitignore

@@ -7,6 +7,7 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+node-compile-cache/
 dist
 *.local
 

package/corpus/core/src/templates/workspace-root/_gitignore

@@ -28,6 +28,7 @@ packages/*/.env
 # pnpm
 .pnpm-store/
 pnpm-debug.log*
+node-compile-cache/
 
 # Local workspace data
 data/

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

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

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
 import { cn } from "@/lib/utils";
 
 const KEYWORDS = new Set([
@@ -266,36 +266,35 @@ const TOKEN_CLASS: Record<TokenType, string> = {
   plain: "",
 };
 
-interface SqlHighlightProps {
+interface SqlHighlightProps extends HTMLAttributes<HTMLPreElement> {
   sql: string;
-  className?: string;
   preClassName?: string;
 }
 
-export function SqlHighlight({
-  sql,
-  className,
-  preClassName,
-}: SqlHighlightProps) {
-  const tokens = tokenize(sql);
-  const nodes: ReactNode[] = tokens.map((tok, idx) => {
-    const cls = TOKEN_CLASS[tok.type];
-    if (!cls) return tok.value;
+export const SqlHighlight = forwardRef<HTMLPreElement, SqlHighlightProps>(
+  function SqlHighlight({ sql, className, preClassName, ...props }, ref) {
+    const tokens = tokenize(sql);
+    const nodes: ReactNode[] = tokens.map((tok, idx) => {
+      const cls = TOKEN_CLASS[tok.type];
+      if (!cls) return tok.value;
+      return (
+        <span key={idx} className={cls}>
+          {tok.value}
+        </span>
+      );
+    });
     return (
-      <span key={idx} className={cls}>
-        {tok.value}
-      </span>
+      <pre
+        ref={ref}
+        {...props}
+        className={cn(
+          "font-mono text-xs leading-5 whitespace-pre-wrap break-words",
+          preClassName,
+          className,
+        )}
+      >
+        <code>{nodes}</code>
+      </pre>
     );
-  });
-  return (
-    <pre
-      className={cn(
-        "font-mono text-xs leading-5 whitespace-pre-wrap break-words",
-        preClassName,
-        className,
-      )}
-    >
-      <code>{nodes}</code>
-    </pre>
-  );
-}
+  },
+);