@agent-native/core 0.146.3 → 0.146.4

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7904
+- template files: 7921

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

@@ -464,9 +464,10 @@ Filters auto-apply on change — there is no Apply button. Each filter change wr
 ## Modifying A Dashboard
 
 For existing dashboard edits, default to `mutate-dashboard`. It gives the
-agent a small typed script API without exposing arbitrary JavaScript execution.
-The main action payload is a string, so it avoids native-array serialization
-traps in tool calls while still giving the agent a code-like editing surface.
+agent a typed mutation API without exposing arbitrary JavaScript execution.
+Pass structured `operations` for normal agent calls; keep the legacy `code`
+form for short layout/config edits only. Large SQL payloads belong in the
+server-side first-party metric catalog, not in a prompt argument.
 The server parses only documented `dashboard.*` method calls, applies the
 resulting operations in memory, validates the final dashboard config, writes
 SQL once, syncs collab, and returns compact proof.
@@ -670,8 +671,9 @@ After a mutation, navigate to the dashboard if the user is elsewhere. The app sy
 
 ### Reordering Panels
 
-For simple "move this chart/section" requests, prefer `mutate-dashboard` with a
-string script:
+For simple "move this chart/section" requests, prefer `mutate-dashboard` with
+structured operations. The short script form is also supported for one compact
+move:
 
 ```json
 {
@@ -694,9 +696,9 @@ When the user asks to change existing panels:
 
 1. Read the current dashboard with `get-sql-dashboard` compact mode unless full
    SQL/config is required.
-2. Call `mutate-dashboard` once with every change in one script. Use
-   `panel(...)`, `panels([...])`, or `panelsMatching({...})` selectors by id or
-   metadata; do not compute shifted array indexes.
+2. Call `mutate-dashboard` once with every change in `operations`. Use panel
+   ids, not shifted array indexes. The short `code` form is only for compact
+   layout/config edits; do not stream a large multi-panel SQL script.
 3. Verify the returned `panelCount`, `appliedOps`, `firstPanelIds`, and
    `summary`. If possible, read the affected panels back and confirm the exact
    fields changed.
@@ -742,8 +744,9 @@ For a **first-party analytics** dashboard, prefer `compose-dashboard` over hand-
 - **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.
+- Set `refreshExisting: true` when refreshing a catalog-backed dashboard. Matching metric panels are replaced in place, unrelated panels and layout order are preserved, and the server returns `refreshedExistingIds`.
 - Each metric accepts an optional per-metric `window` of `'30d' | '90d' | 'all'` (only affects windowed virality/time metrics) and `title` / `chartType` / `width` overrides. Request `'all'` only when the user asks for all-time coverage, and describe it as full available history.
-- Returns `{ dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, skippedExistingIds }` — report `panelCount` as proof-of-done.
+- Returns `{ saved, dashboardId, panelCount, createdMetrics, refreshedExistingIds, unknownMetrics, invalidMetrics, skippedExistingIds }` — report `saved: true`, `panelCount`, and any invalid/unknown metrics as proof-of-done.
 
 Available metric keys: `total-signups`, `signups-over-time`, `signups-by-template`, `sessions-by-app`, `sessions-over-time`, `replay-sessions`, `replay-chunks-over-time`, `recent-replay-sessions`, `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`, `top-referrer-domains`, `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`.
 
@@ -760,7 +763,7 @@ This is the dashboard-specific application of the framework-wide `reliable-mutat
 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 edits into ONE `mutate-dashboard` call.** One script can move,
+- **Batch ALL edits into ONE `mutate-dashboard` call.** Structured operations can move,
   insert, remove, duplicate, and update many panels. Never loop dashboard edit
   actions panel-by-panel.
   - To bulk edit existing panels, use selectors:

package/corpus/templates/analytics/.agents/skills/self-modifying-code/SKILL.md

@@ -36,8 +36,10 @@ Tier 4 includes **all** of the following — not only editing package source:
 - Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
 - `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
   target any `@agent-native/*` package
-- Local package patches or invented "dispatch/core behavior" shims meant to
-  paper over a version skew or failed upgrade
+- `pnpm patch`, `pnpm patch-commit`, or local package patch artifacts for any
+  dependency
+- Invented "dispatch/core behavior" shims meant to paper over a version skew
+  or failed upgrade
 
 This does not prohibit intentional app-owned UI customization. When public
 props and composition are insufficient, the `customizing-agent-native` skill
@@ -100,8 +102,10 @@ inline strings in components.
 - Don't confuse readable package source with app-owned code: use
   `customizing-agent-native` and `agent-native eject` for supported ownership
   transfer
+- Don't use `pnpm patch` / `pnpm patch-commit`, commit `patches/` artifacts, or
+  add `pnpm.patchedDependencies` to "make the app run" after a version bump
 - Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
-  `@agent-native/*` to "make the app run" after a version bump
+  `@agent-native/*` to paper over a broken upgrade
 - Don't invent local dispatch/core behavior overrides when upgrade fails —
   run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
 - Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested

package/corpus/templates/analytics/.agents/skills/upgrade-agent-native/SKILL.md

@@ -15,8 +15,9 @@ metadata:
 
 When an older Agent Native app/branch needs to run on current packages, use
 `agent-native upgrade`. Never "fix" upgrade breakage with
-`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
-edits under `node_modules/@agent-native/*` — especially not against
+`pnpm patch`, `pnpm patch-commit`, `pnpm.patchedDependencies`,
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patch artifacts,
+or edits under `node_modules/@agent-native/*` — especially not against
 `@agent-native/core` or `@agent-native/dispatch`.
 
 ## Why
@@ -109,6 +110,8 @@ install → refresh scaffold skills → verify, then fix **app** code only.
 
 - Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
   `patchedDependencies` for any `@agent-native/*` package
+- Don't run `pnpm patch` or `pnpm patch-commit`, or commit files under
+  `patches/`, for any dependency
 - Don't edit `node_modules/@agent-native/core` or
   `node_modules/@agent-native/dispatch`
 - Don't invent local "dispatch behavior" shims to paper over version skew

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

@@ -111,8 +111,8 @@ export default defineAction({
     "Build a large first-party analytics dashboard in ONE fast call: name the metrics you want and the SERVER generates the validated SQL + chart config for every panel. " +
     "Do NOT hand-author large `update-dashboard` configs panel-by-panel — producing/streaming a big multi-panel config inside the ~40s run budget fails and thrashes. " +
     "Each metric expands into a complete first-party panel from the shipped, already-validated metric catalog. Unknown metric keys are skipped and reported (not fatal); each panel's SQL is validated independently (valid panels are saved, invalid ones reported), and the dashboard is assembled and saved in a single atomic store write. " +
-    "If the dashboard already exists and `overwrite` is false (default), the new panels are APPENDED (panels whose id is already present are skipped); with `overwrite: true` the config is replaced. " +
-    "Returns { dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, urlPath, deepLink, message } — use panelCount as proof-of-done. " +
+    "If the dashboard already exists and `overwrite` is false (default), the new panels are APPENDED (panels whose id is already present are skipped). Set `refreshExisting: true` to atomically replace matching catalog panels in place while preserving unrelated panels. With `overwrite: true` the config is replaced. " +
+    "Returns { dashboardId, panelCount, createdMetrics, refreshedExistingIds, unknownMetrics, invalidMetrics, urlPath, deepLink, message } — use panelCount as proof-of-done. " +
     `Available metric keys: ${METRIC_KEYS.join(", ")}. ` +
     "Each metric accepts an optional per-metric `window` of '30d' | '90d' | 'all' (only affects windowed virality/time metrics). Catalog panels are time-scoped by construction; custom first-party SQL added later must use `{{timeRange}}` or declare `config.timeScope`.",
   schema: z.object({
@@ -142,6 +142,12 @@ export default defineAction({
       .describe(
         "If true, replace the whole dashboard config. If false (default) and the dashboard exists, APPEND the new panels (skipping ids already present).",
       ),
+    refreshExisting: z
+      .boolean()
+      .optional()
+      .describe(
+        "When appending to an existing dashboard, replace panels whose ids match the requested catalog metrics in place, preserving unrelated panels and layout order. Use this to refresh a catalog-backed dashboard without sending SQL through the prompt.",
+      ),
   }),
   mcpApp: {
     compactCatalog: true,
@@ -238,6 +244,7 @@ export default defineAction({
     let finalConfig: Record<string, unknown>;
     let appendedCount = composedPanels.length;
     let skippedExistingIds: string[] = [];
+    let refreshedExistingIds: string[] = [];
 
     if (existing && !args.overwrite) {
       // Append: preserve existing panels + order, add only new panel ids.
@@ -260,18 +267,36 @@ export default defineAction({
               .map((p) => (typeof p?.id === "string" ? p.id : null))
               .filter((id): id is string => !!id),
           );
+          const composedById = new Map(
+            composedPanels.map((panel) => [panel.id, panel]),
+          );
+          const refreshed = new Set<string>();
+          const mergedExistingPanels = existingPanels.map((panel) => {
+            const id = typeof panel?.id === "string" ? panel.id : "";
+            const replacement = args.refreshExisting
+              ? composedById.get(id)
+              : undefined;
+            if (!replacement) return panel;
+            refreshed.add(id);
+            return replacement;
+          });
           const toAppend: ComposedPanel[] = [];
           const skipped: string[] = [];
+          const appendedIds = new Set<string>();
           for (const panel of composedPanels) {
+            if (refreshed.has(panel.id)) continue;
             if (existingIds.has(panel.id)) {
               skipped.push(panel.id);
               continue;
             }
+            if (appendedIds.has(panel.id)) continue;
             toAppend.push(panel);
+            appendedIds.add(panel.id);
             existingIds.add(panel.id);
           }
           appendedCount = toAppend.length;
-          skippedExistingIds = skipped;
+          skippedExistingIds = Array.from(new Set(skipped));
+          refreshedExistingIds = Array.from(refreshed);
           const merged = withFilters({
             ...existingConfig,
             name:
@@ -279,7 +304,7 @@ export default defineAction({
               existingConfig.name.trim()
                 ? existingConfig.name
                 : dashboardName,
-            panels: [...existingPanels, ...toAppend],
+            panels: [...mergedExistingPanels, ...toAppend],
           });
           return { kind: "sql" as const, body: merged };
         },
@@ -304,11 +329,30 @@ export default defineAction({
       ? (finalConfig.panels as unknown[]).length
       : 0;
 
-    queueDashboardCollabSync(args.dashboardId, finalConfig, "agent");
+    const changed =
+      !existing ||
+      args.overwrite === true ||
+      appendedCount > 0 ||
+      refreshedExistingIds.length > 0;
+
+    if (changed) {
+      queueDashboardCollabSync(args.dashboardId, finalConfig, "agent");
+    }
 
     const parts: string[] = [];
     if (existing && !args.overwrite) {
-      parts.push(`Appended ${appendedCount} panel(s) to "${args.dashboardId}"`);
+      if (!changed) {
+        parts.push(`No changes were needed for "${args.dashboardId}"`);
+      } else if (refreshedExistingIds.length > 0) {
+        parts.push(
+          `Refreshed ${refreshedExistingIds.length} existing panel(s)`,
+        );
+      }
+      if (changed) {
+        parts.push(
+          `Appended ${appendedCount} panel(s) to "${args.dashboardId}"`,
+        );
+      }
       if (skippedExistingIds.length > 0) {
         parts.push(`${skippedExistingIds.length} already present`);
       }
@@ -330,11 +374,14 @@ export default defineAction({
     parts.push(`Dashboard now has ${panelCount} panel(s).`);
 
     return {
+      saved: true,
+      changed,
       id: args.dashboardId,
       dashboardId: args.dashboardId,
       name: dashboardName,
       panelCount,
       createdMetrics,
+      refreshedExistingIds,
       unknownMetrics,
       invalidMetrics,
       skippedExistingIds,

package/corpus/templates/analytics/actions/dashboard-mutation-api.ts

@@ -136,6 +136,10 @@ export const DASHBOARD_MUTATION_EXAMPLES = [
   'dashboard.insertPanel({"id":"personal-widget-slot","title":"Personal Widget Slot","chartType":"extension","width":3,"config":{"extensionSlotId":"analytics.dashboard.<dashboard-id>.panel.personal-widget-slot"}}).atBottom();',
 ] as const;
 
+/** Keep the legacy script surface bounded before it reaches the parser. */
+export const MAX_DASHBOARD_MUTATION_CODE_LENGTH = 12_000;
+export const MAX_DASHBOARD_MUTATION_OPERATIONS = 100;
+
 export type DashboardMutationOperation =
   | {
       op: "movePanels";
@@ -1494,8 +1498,10 @@ export function parseDashboardMutationScript(
   config: Record<string, unknown>,
   code: string,
 ): DashboardMutationOperation[] {
-  if (code.length > 12_000) {
-    throw new Error("mutation script is too large; keep it under 12000 chars");
+  if (code.length > MAX_DASHBOARD_MUTATION_CODE_LENGTH) {
+    throw new Error(
+      `mutation script is too large; keep it under ${MAX_DASHBOARD_MUTATION_CODE_LENGTH} chars or use structured operations/compose-dashboard`,
+    );
   }
   if (hasTemplateLiteralSyntax(code)) {
     throw new Error("mutation script does not support template literals");

package/corpus/templates/analytics/actions/migrate-first-party-analytics-to-bigquery.ts

@@ -44,7 +44,9 @@ const migrationSchema = z.object({
     .min(1)
     .max(750)
     .optional()
-    .describe("Optional per-page limit used when mode is prepare."),
+    .describe(
+      "Optional per-page limit used when mode is prepare; for an existing job, it can only increase the bounded batch size.",
+    ),
   confirm: z.boolean().optional(),
 });
 

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

@@ -19,6 +19,8 @@ import {
   applyDashboardMutationOperations,
   DASHBOARD_MUTATION_API_TYPES,
   DASHBOARD_MUTATION_EXAMPLES,
+  MAX_DASHBOARD_MUTATION_CODE_LENGTH,
+  MAX_DASHBOARD_MUTATION_OPERATIONS,
   parseDashboardMutationScript,
   type DashboardMutationOperation,
   type DashboardMutationResult,
@@ -104,6 +106,11 @@ function parseJsonArrayString(
   if (!Array.isArray(parsed)) {
     throw new Error(`${fieldName} must be a JSON array`);
   }
+  if (parsed.length > MAX_DASHBOARD_MUTATION_OPERATIONS) {
+    throw new Error(
+      `${fieldName} has ${parsed.length} operations; keep it at or below ${MAX_DASHBOARD_MUTATION_OPERATIONS}`,
+    );
+  }
   return parsed.map((op, index) => {
     try {
       return mutationOperationSchema.parse(op) as DashboardMutationOperation;
@@ -115,7 +122,7 @@ function parseJsonArrayString(
 
 const operationsInputSchema = z
   .union([
-    z.array(mutationOperationSchema),
+    z.array(mutationOperationSchema).max(MAX_DASHBOARD_MUTATION_OPERATIONS),
     z.string().transform((value) => {
       const trimmed = value.trim();
       return trimmed ? parseJsonArrayString(trimmed, "operations") : undefined;
@@ -134,7 +141,7 @@ function nonEmptyOperations(
 }
 
 const apiHelp =
-  "Constrained TypeScript-like dashboard mutation script. The server parses only calls on `dashboard`; it does not execute arbitrary JavaScript. " +
+  "Short, constrained TypeScript-like dashboard mutation script for compatibility. Prefer structured `operations` for agent calls; use this only for small layout/config edits. The server parses only calls on `dashboard`; it does not execute arbitrary JavaScript. " +
   "No variables, imports, loops, functions, templates, network, filesystem, or DB access. Arguments must be JSON-compatible literals, so quote object keys. " +
   "Subjects: dashboard.set, dashboard.setFilterDefault, dashboard.panel, dashboard.panels, dashboard.panelsMatching, dashboard.section, dashboard.insertPanel. " +
   'For a simple default-filter change, use `dashboard.setFilterDefault("emailFilter","exclude_builder");`; it verifies the filter and option value without resending every filter or revalidating unchanged panel SQL. ' +
@@ -148,7 +155,26 @@ const agentInputSchema = z.object({
     .string()
     .min(1)
     .describe("Dashboard id, e.g. 'agent-native-templates-first-party'."),
-  code: z.string().min(1).describe(apiHelp),
+  operations: z
+    .array(mutationOperationSchema)
+    .max(MAX_DASHBOARD_MUTATION_OPERATIONS)
+    .optional()
+    .describe(
+      "Preferred agent input: structured dashboard edits applied atomically in one save. Use panel ids, not array indexes. For first-party metric refreshes, use compose-dashboard with metric keys instead of embedding SQL here.",
+    ),
+  code: z
+    .string()
+    .max(MAX_DASHBOARD_MUTATION_CODE_LENGTH)
+    .optional()
+    .describe(apiHelp),
+  dryRun: z
+    .boolean()
+    .optional()
+    .describe("Validate the mutation without saving it."),
+  returnConfig: z
+    .boolean()
+    .optional()
+    .describe("Include the full resulting config only when it is needed."),
 });
 
 function resolveScope() {
@@ -212,10 +238,13 @@ function sqlValidationScope(
 async function validateMutationSql(
   config: Record<string, unknown>,
   operations: DashboardMutationOperation[],
+  signal?: AbortSignal,
 ): Promise<string | null> {
   const scope = sqlValidationScope(operations);
   if (scope === null) return null;
-  return validatePanelSql(config, scope === "all" ? undefined : scope);
+  return validatePanelSql(config, scope === "all" ? undefined : scope, {
+    signal,
+  });
 }
 
 function movedPanelIdsFrom(operations: DashboardMutationOperation[]): string[] {
@@ -239,11 +268,11 @@ function helpResult() {
 
 export default defineAction({
   description:
-    "Apply general SQL dashboard edits through a small typed mutation API in ONE atomic save. " +
+    "Apply general SQL dashboard edits through a small typed mutation API in ONE atomic save. Prefer structured `operations` for agent calls; use the short `code` form only for compact layout/config edits. " +
     "Prefer this for dashboard layout and panel edits: move panels by id, edit titles/SQL/width/config, remove panels, duplicate panels, insert panels, or patch dashboard fields. " +
     "For user placement requests like 'second row' or 'next to return rates', use row-aware placement such as `dashboard.insertPanel(...).nextTo(\"retention-over-time\")` or `.atRow(2)`, then verify rendered rows from `get-sql-dashboard.layout.groups`. " +
     "This is code-shaped but not arbitrary code execution: the server parses the allowed dashboard methods, validates the resulting config with the same invariants as update-dashboard, saves once, syncs collab, and returns compact proof. First-party SQL must be explicitly time-bound as described in the API help; server validation rejects unbound first-party SQL. " +
-    "The main code argument is a string, so it avoids brittle JSON-pointer indexes and native-array serialization issues. " +
+    "Structured operations avoid brittle JSON-pointer indexes and native-array serialization issues. Do not put a large multi-panel SQL payload in `code`; use `compose-dashboard` for catalog metrics or structured operations for a bounded custom edit. " +
     `Common example: ${DASHBOARD_MUTATION_EXAMPLES[0]}`,
   schema: z.object({
     dashboardId: z
@@ -254,7 +283,11 @@ export default defineAction({
       .string()
       .optional()
       .describe("Legacy alias for dashboardId. Prefer dashboardId."),
-    code: z.string().optional().describe(apiHelp),
+    code: z
+      .string()
+      .max(MAX_DASHBOARD_MUTATION_CODE_LENGTH)
+      .optional()
+      .describe(apiHelp),
     operations: operationsInputSchema.describe(
       "Structured equivalent of the typed script. Native callers should pass an array of mutation ops; shell/legacy callers may pass a JSON string. " +
         "Supported ops: movePanels, removePanels, updatePanel, updatePanelPath, insertPanel, duplicatePanel, setDashboard, setFilterDefault.",
@@ -288,7 +321,8 @@ export default defineAction({
       height: 680,
     }),
   },
-  run: async (args) => {
+  timeoutMs: 35_000,
+  run: async (args, actionContext) => {
     const code = nonEmptyCode(args.code);
     const requestedOperations = nonEmptyOperations(args.operations);
     const wantsHelpOnly =
@@ -357,7 +391,11 @@ export default defineAction({
       root = computed.nextRoot;
       operations = computed.nextOperations;
       mutation = computed.nextMutation;
-      const sqlError = await validateMutationSql(root, operations);
+      const sqlError = await validateMutationSql(
+        root,
+        operations,
+        actionContext?.signal,
+      );
       if (sqlError) throw new Error(sqlError);
     } else {
       const saved = await upsertDashboardWithRetry(
@@ -368,6 +406,7 @@ export default defineAction({
           const sqlError = await validateMutationSql(
             computed.nextRoot,
             computed.nextOperations,
+            actionContext?.signal,
           );
           if (sqlError) throw new Error(sqlError);
           root = computed.nextRoot;

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

@@ -16,6 +16,7 @@ import {
 } from "../server/lib/dashboards-store";
 import { parseDemoDescriptor } from "../server/lib/demo-source";
 import { validateFirstPartyAnalyticsSql } from "../server/lib/first-party-analytics.js";
+import { DASHBOARD_SQL_VALIDATION_TIMEOUT_MS } from "../shared/dashboard-report-timeouts.js";
 import {
   applyPanelOrder,
   compactDashboardResult,
@@ -388,15 +389,30 @@ export function validateDashboardConfig(
   return null;
 }
 
+const MAX_CONCURRENT_SQL_VALIDATIONS = 8;
+
+export interface ValidatePanelSqlOptions {
+  signal?: AbortSignal;
+}
+
 /** Validate every query panel, or only the supplied ids for a targeted edit. */
 export async function validatePanelSql(
   config: Record<string, unknown>,
   panelIds?: ReadonlySet<string>,
+  options: ValidatePanelSqlOptions = {},
 ): Promise<string | null> {
   const panels = config.panels;
   if (!Array.isArray(panels)) return null;
   const vars = buildDryRunVars(config);
+  const bigQueryPanels: Array<{
+    index: number;
+    panel: Record<string, unknown>;
+    sql: string;
+  }> = [];
   for (let i = 0; i < panels.length; i++) {
+    if (options.signal?.aborted) {
+      throw new Error("Dashboard SQL validation was cancelled");
+    }
     const p = panels[i] as Record<string, unknown>;
     if (panelIds && (typeof p.id !== "string" || !panelIds.has(p.id))) {
       continue;
@@ -458,14 +474,72 @@ export async function validatePanelSql(
     if (!raw.trim()) continue;
     const sql = interpolate(raw, vars);
     if (!sql.trim()) continue;
-    let err: string | null;
-    try {
-      err = await dryRunQuery(sql);
-    } catch (e: any) {
-      err = e?.message ?? String(e);
+    bigQueryPanels.push({ index: i, panel: p, sql });
+  }
+
+  if (bigQueryPanels.length === 0) return null;
+
+  // A dashboard save is one logical operation. Validate the selected BigQuery
+  // panels as one bounded batch so a slow panel cannot multiply the per-query
+  // timeout by the number of panels in the mutation.
+  const validationController = new AbortController();
+  const abortFromCaller = () => validationController.abort();
+  options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    validationController.abort();
+  }, DASHBOARD_SQL_VALIDATION_TIMEOUT_MS);
+  const errors: Array<string | null> = Array(bigQueryPanels.length).fill(null);
+  let nextIndex = 0;
+
+  const worker = async () => {
+    while (!validationController.signal.aborted) {
+      const taskIndex = nextIndex++;
+      const task = bigQueryPanels[taskIndex];
+      if (!task) return;
+
+      let err: string | null;
+      try {
+        err = await dryRunQuery(task.sql, {
+          signal: validationController.signal,
+        });
+      } catch (e: any) {
+        err = e?.message ?? String(e);
+      }
+      errors[taskIndex] = err;
     }
+  };
+
+  try {
+    await Promise.all(
+      Array.from(
+        {
+          length: Math.min(
+            MAX_CONCURRENT_SQL_VALIDATIONS,
+            bigQueryPanels.length,
+          ),
+        },
+        () => worker(),
+      ),
+    );
+  } finally {
+    clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", abortFromCaller);
+  }
+
+  if (options.signal?.aborted && !timedOut) {
+    throw new Error("Dashboard SQL validation was cancelled");
+  }
+  if (timedOut) {
+    return `Dashboard SQL validation timed out after ${Math.round(DASHBOARD_SQL_VALIDATION_TIMEOUT_MS / 1000)} seconds`;
+  }
+
+  for (let i = 0; i < bigQueryPanels.length; i++) {
+    const err = errors[i];
     if (err) {
-      return `panel[${i}] "${p.title || p.id}" SQL is invalid: ${err}`;
+      const task = bigQueryPanels[i];
+      return `panel[${task.index}] "${task.panel.title || task.panel.id}" SQL is invalid: ${err}`;
     }
   }
   return null;

package/corpus/templates/analytics/changelog/2026-08-07-dashboard-creation-and-edits-now-save-faster-with-reliable-s.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-07
+---
+
+Dashboard creation and edits now save faster with reliable structured mutations