@agent-native/core 0.77.15 → 0.77.17

package/corpus/README.md

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

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @agent-native/core
 
+## 0.77.17
+
+### Patch Changes
+
+- 6c65e7f: Show a Plan signup note for switching `/visual-plan` to local-files mode.
+- 6c65e7f: Allow apps to filter the broad action-event query invalidation from `useDbSync`.
+- 6c65e7f: Keep standalone scaffold installs stable when fresh Sentry transitive packages are published.
+
+## 0.77.16
+
+### Patch Changes
+
+- 02af11c: Extend the background-worker pre-send instrumentation: also time out the required
+  suspect branches (system prompt / `extraContext`, enriched message) and record
+  which branch hit its timeout/error fallback into the run's setup diagnostic
+  (`to=...` in `setupDetail`). The hanging op is then identifiable via
+  `/runs/active` even when the Netlify function-log drain is unreadable, and the
+  timeout lets the worker claim past a stuck required read.
+
 ## 0.77.15
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.77.15",
+  "version": "0.77.17",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

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

@@ -3963,10 +3963,15 @@ export function createProductionAgentHandler(
         );
       } catch {}
     };
-    // DIAGNOSTIC + DEFENSIVE: race an optional context read against a short
-    // timeout and fall back to a safe default, logging start/done/error/timeout.
-    // A single stuck optional read can no longer block the worker from reaching
-    // claim, and the TIMEOUT breadcrumb names the culprit in the function logs.
+    // DIAGNOSTIC: pre-send branches that hit their timeout/error fallback,
+    // recorded in memory so the FINAL run diag (setupDetail) can name them even
+    // when the Netlify function-log drain is unreadable. Readable via
+    // /runs/active once the worker claims past the stuck branch.
+    const bgTimedOut: string[] = [];
+    // DIAGNOSTIC + DEFENSIVE: race a pre-send read against a short timeout and
+    // fall back to a safe default, logging start/done/error/timeout. A single
+    // stuck read can no longer block the worker from reaching claim, and the
+    // recorded `bgTimedOut` set names the culprit in the run diag.
     const withBgFallback = <T>(
       label: string,
       ms: number,
@@ -3980,6 +3985,7 @@ export function createProductionAgentHandler(
           if (done) return;
           done = true;
           bgLog(`${label}:TIMEOUT@${ms}ms`);
+          bgTimedOut.push(`${label}:timeout`);
           resolve(fallback);
         }, ms);
         fn().then(
@@ -3997,6 +4003,7 @@ export function createProductionAgentHandler(
             bgLog(
               `${label}:error ${(e as { message?: string })?.message ?? e}`,
             );
+            bgTimedOut.push(`${label}:error`);
             resolve(fallback);
           },
         );
@@ -4270,13 +4277,12 @@ export function createProductionAgentHandler(
     // that starts but never finishes; the OPTIONAL context reads additionally
     // race a short timeout + "" fallback (withBgFallback) so one stuck read
     // cannot block the worker from reaching claim.
-    bgLog("enrich:start");
-    const enrichedMessagePromise = Promise.resolve(
-      enrichMessage(requestMessage, references),
-    ).then((v) => {
-      bgLog("enrich:done");
-      return v;
-    });
+    const enrichedMessagePromise = withBgFallback(
+      "enrich",
+      5000,
+      requestMessage,
+      () => Promise.resolve(enrichMessage(requestMessage, references)),
+    );
     bgLog("loop:start");
     const loopSettingsPromise = readAgentLoopSettings({
       userEmail: ownerEmail ?? getRequestUserEmail() ?? null,
@@ -4289,27 +4295,32 @@ export function createProductionAgentHandler(
       });
 
     let systemPromptError: any = null;
-    const systemPromptPromise = (async (): Promise<string> => {
-      const sysPromptStart = Date.now();
-      bgLog("sysprompt:start");
-      try {
-        const sp =
-          typeof options.systemPrompt === "function"
-            ? await options.systemPrompt(event)
-            : options.systemPrompt;
-        bgLog("sysprompt:done");
-        return sp;
-      } catch (error) {
-        systemPromptError = error;
-        bgLog(
-          "sysprompt:error " +
-            ((error as { message?: string })?.message ?? error),
-        );
-        return "";
-      } finally {
-        setupMarks.sysPromptMs = Date.now() - sysPromptStart;
-      }
-    })();
+    const systemPromptPromise = withBgFallback(
+      "sysprompt",
+      5000,
+      "",
+      async (): Promise<string> => {
+        const sysPromptStart = Date.now();
+        bgLog("sysprompt:start");
+        try {
+          const sp =
+            typeof options.systemPrompt === "function"
+              ? await options.systemPrompt(event)
+              : options.systemPrompt;
+          bgLog("sysprompt:done");
+          return sp;
+        } catch (error) {
+          systemPromptError = error;
+          bgLog(
+            "sysprompt:error " +
+              ((error as { message?: string })?.message ?? error),
+          );
+          return "";
+        } finally {
+          setupMarks.sysPromptMs = Date.now() - sysPromptStart;
+        }
+      },
+    );
 
     const screenContextPromise = withBgFallback(
       "screen",
@@ -5164,7 +5175,9 @@ export function createProductionAgentHandler(
     const setupDetail =
       Object.entries(setupMarks)
         .map(([k, v]) => `${k}=${v}`)
-        .join(" ") + ` total=${Date.now() - setupT0}`;
+        .join(" ") +
+      ` total=${Date.now() - setupT0}` +
+      ` to=${bgTimedOut.join(",") || "none"}`;
 
     bgLog("startRun:invoked");
     startRun(

package/corpus/core/src/client/AgentPanel.tsx

@@ -687,6 +687,7 @@ function AgentPanelInner({
   );
   const closeTabHint = isMac ? "\u2303W" : "Alt+W";
   const closeAllTabsHint = isMac ? "\u2303\u2325W" : "Ctrl+Alt+W";
+  const toggleSidebarHint = isMac ? "\u2318\\" : "Ctrl+\\";
 
   const [execMode, setExecMode] = useState<ExecMode>(() => {
     try {
@@ -1125,6 +1126,9 @@ function AgentPanelInner({
                     className="shrink-0"
                   />
                   {t("agentPanel.collapseSidebar")}
+                  <DropdownMenuShortcut>
+                    {toggleSidebarHint}
+                  </DropdownMenuShortcut>
                 </DropdownMenuItem>
                 <DropdownMenuSeparator />
               </>

package/corpus/core/src/client/org/OrgSwitcher.tsx

@@ -15,6 +15,7 @@ import {
   IconCode,
   IconContract,
   IconFileText,
+  IconLayoutBoard,
   IconLoader2,
   IconLogout,
   IconMail,
@@ -25,6 +26,7 @@ import {
   IconPhoto,
   IconPlus,
   IconPresentation,
+  IconRoute,
   IconScreenShare,
   IconSelector,
   IconSettings,
@@ -101,6 +103,7 @@ const APP_ICON_MAP: Record<string, typeof IconApps> = {
   Mail: IconMail,
   CalendarDays: IconCalendar,
   FileText: IconFileText,
+  LayoutBoard: IconLayoutBoard,
   BarChart2: IconChartBar,
   GalleryHorizontal: IconPresentation,
   Video: IconVideo,
@@ -110,6 +113,7 @@ const APP_ICON_MAP: Record<string, typeof IconApps> = {
   Code: IconCode,
   Contract: IconContract,
   MessageCircle: IconMessageCircle,
+  Route: IconRoute,
   ScreenShare: IconScreenShare,
   Brush: IconBrush,
   Brain: IconBrain,

package/corpus/core/src/client/use-db-sync.ts

@@ -8,8 +8,15 @@ import {
 } from "./embed-auth.js";
 import { bumpChangeVersion } from "./use-change-version.js";
 
+interface Query {
+  queryKey: readonly unknown[];
+}
+
 interface QueryClient {
-  invalidateQueries(opts?: { queryKey?: string[] }): void;
+  invalidateQueries(opts?: {
+    queryKey?: string[];
+    predicate?: (query: Query) => boolean;
+  }): void;
 }
 
 const POLL_ABORT_MIN_MS = 10_000;
@@ -475,6 +482,10 @@ export function _resetSyncTransportRegistryForTests(): void {
  * @param options.ignoreSource - Skip events whose `requestSource` matches this
  *   value. Use a per-tab ID so the UI ignores its own writes while still
  *   picking up changes from other tabs, agents, and scripts.
+ * @param options.actionInvalidatePredicate - Optional filter for the broad
+ *   compatibility invalidate triggered by `action` events. Use this to keep
+ *   expensive active queries on explicit-refresh semantics while still letting
+ *   normal source-versioned queries react through `useChangeVersion`.
  */
 export function useDbSync(
   options: {
@@ -489,6 +500,7 @@ export function useDbSync(
     fallbackInterval?: number;
     pauseWhenHidden?: boolean;
     ignoreSource?: string;
+    actionInvalidatePredicate?: (query: Query) => boolean;
   } = {},
 ): void {
   const {
@@ -508,6 +520,10 @@ export function useDbSync(
 
   const ignoreSourceRef = useRef(options.ignoreSource);
   ignoreSourceRef.current = options.ignoreSource;
+  const actionInvalidatePredicateRef = useRef(
+    options.actionInvalidatePredicate,
+  );
+  actionInvalidatePredicateRef.current = options.actionInvalidatePredicate;
 
   useEffect(() => {
     const id = Symbol("useDbSync");
@@ -550,7 +566,8 @@ export function useDbSync(
           // signal, so refresh active queries broadly as a compatibility
           // safety net. Other event sources stay targeted to avoid request
           // storms from noisy domain-specific writes.
-          queryClient.invalidateQueries();
+          const predicate = actionInvalidatePredicateRef.current;
+          queryClient.invalidateQueries(predicate ? { predicate } : undefined);
         }
 
         // Framework-level invalidate: a small, fixed list of query-key

package/corpus/core/src/server/auth-marketing.ts

@@ -4,8 +4,15 @@ export interface AuthMarketingContent {
   description?: string;
   features?: string[];
   runLocalCommand?: string;
+  signupLocalModeNote?: {
+    text: string;
+    command: string;
+  };
 }
 
+const PLAN_LOCAL_FILES_COMMAND =
+  "npx @agent-native/core@latest skills add visual-plan --mode local-files --scope user";
+
 export interface ResolveBuiltInAuthMarketingOptions {
   requestHost?: string;
   requestPath?: string;
@@ -71,6 +78,11 @@ export const BUILT_IN_AUTH_MARKETING: Record<string, AuthMarketingContent> = {
       "Review PR recaps with diagrams, file maps, and annotated code",
       "Share links for async comments and product review",
     ],
+    runLocalCommand: PLAN_LOCAL_FILES_COMMAND,
+    signupLocalModeNote: {
+      text: "Prefer no account or self-hosting? Switch /visual-plan to local files only:",
+      command: PLAN_LOCAL_FILES_COMMAND,
+    },
   },
   design: {
     appName: "Agent-Native Design",
@@ -169,6 +181,9 @@ function cloneMarketing(marketing: AuthMarketingContent): AuthMarketingContent {
   return {
     ...marketing,
     features: marketing.features ? [...marketing.features] : undefined,
+    signupLocalModeNote: marketing.signupLocalModeNote
+      ? { ...marketing.signupLocalModeNote }
+      : undefined,
   };
 }
 

package/corpus/core/src/server/onboarding-html.ts

@@ -1254,6 +1254,14 @@ export function getOnboardingHtml(opts: OnboardingHtmlOptions = {}): string {
         }
       : undefined;
   const runLocalCommand = marketing?.runLocalCommand?.trim();
+  const signupLocalModeNote =
+    isAgentNativeHostedHost(opts.requestHost) &&
+    marketing?.signupLocalModeNote?.command.trim()
+      ? {
+          text: marketing.signupLocalModeNote.text.trim(),
+          command: marketing.signupLocalModeNote.command.trim(),
+        }
+      : undefined;
   const brandMarkSrc = withAppBasePath("/agent-native-icon-dark.svg");
   const socialImageUrl = withAgentNativeSocialImageCacheBuster(
     opts.requestOrigin
@@ -1336,6 +1344,13 @@ ${localeMenuItemsHtml}
   const signupLegalNoteHtml = signupLegalNotice
     ? `      <p class="legal-note">${localizedValue(signupLegalNotice.prefix, "legalPrefix")} <a href="${esc(signupLegalNotice.termsUrl)}" target="_blank" rel="noreferrer"${localizedAnchorLabel(signupLegalNotice.termsLabel, "legalTerms")}</a> ${localizedValue(signupLegalNotice.connector, "legalConnector")} <a href="${esc(signupLegalNotice.privacyUrl)}" target="_blank" rel="noreferrer"${localizedAnchorLabel(signupLegalNotice.privacyLabel, "legalPrivacy")}</a>${localizedValue(signupLegalNotice.suffix, "legalSuffix")}</p>`
     : "";
+  const signupLocalModeNoteHtml = signupLocalModeNote
+    ? `      <div class="signup-local-mode-note" id="signup-local-mode-note" data-command="${esc(signupLocalModeNote.command)}">
+        <p>${esc(signupLocalModeNote.text)}</p>
+        <code>${esc(signupLocalModeNote.command)}</code>
+        <button type="button" class="copy-run-local" id="copy-signup-local-mode" onclick="__anCopySignupLocalModeCommand()"${i18nAttr("copyCommand")}>${esc(t("copyCommand"))}</button>
+      </div>`
+    : "";
   const googleSignInNotice = opts.googleSignInNotice;
   const googleNoticeBodyParts = googleSignInNotice
     ? (Array.isArray(googleSignInNotice.body)
@@ -2025,6 +2040,33 @@ ${
     text-underline-offset: 2px;
   }
   .legal-note a:hover { color: #aaa; }
+  .signup-local-mode-note {
+    margin-top: 0.75rem;
+    padding: 0.625rem;
+    color: #777;
+    background: rgba(255,255,255,0.025);
+    border: 1px solid rgba(255,255,255,0.08);
+    border-radius: 8px;
+    font-size: 0.6875rem;
+    line-height: 1.45;
+    text-align: left;
+  }
+  .signup-local-mode-note p {
+    margin: 0 0 0.5rem;
+  }
+  .signup-local-mode-note code {
+    display: block;
+    overflow-x: auto;
+    padding-bottom: 0.125rem;
+    color: #b8b8b8;
+    font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+    font-size: 0.6875rem;
+    line-height: 1.5;
+    white-space: nowrap;
+  }
+  .signup-local-mode-note .copy-run-local {
+    margin-top: 0.5rem;
+  }
   .msg { margin-top: 0.75rem; font-size: 0.8125rem; display: none; }
   .msg.error { color: #f87171; }
   .msg.success { color: #33C4FF; }
@@ -2376,6 +2418,7 @@ ${
     <input id="s-pass2" type="password" autocomplete="new-password" placeholder="${esc(t("confirmPasswordPlaceholder"))}"${i18nPlaceholderAttr("confirmPasswordPlaceholder")} required minlength="8" />
       <button type="submit"${i18nAttr("createAccount")}>${esc(t("createAccount"))}</button>
 ${signupLegalNoteHtml}
+${signupLocalModeNoteHtml}
       <p class="msg" id="s-msg"></p>
     </form>
 
@@ -3705,7 +3748,7 @@ ${
 }
 ${starfieldScript}
 ${
-  runLocalCommand
+  runLocalCommand || signupLocalModeNote
     ? `
   function __anSetRunLocalCommandOpen(open) {
     var panel = document.getElementById('run-local-panel');
@@ -3740,6 +3783,9 @@ ${
   function __anCopyRunLocalCommand() {
     __anCopyCommandFromPanel('run-local-panel', 'copy-run-local');
   }
+  function __anCopySignupLocalModeCommand() {
+    __anCopyCommandFromPanel('signup-local-mode-note', 'copy-signup-local-mode');
+  }
   function __anCopyGoogleNoticeRunLocalCommand() {
     __anCopyCommandFromPanel('google-preflight-run-local-panel', 'copy-google-preflight-run-local');
   }`

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

@@ -25,6 +25,12 @@ Legacy settings keys such as `u:<email>:dashboard-*`, `u:<email>:sql-dashboard-*
 
 Use `update-dashboard` for dashboard edits. It resolves the current user/org context, validates the config, applies JSON-pointer operations when provided, writes the SQL-backed record, and preserves sharing semantics.
 
+Never use `db-patch`, raw SQL, or settings-key edits to create or modify a
+dashboard config. Those bypass the dashboard action's access checks, SQL
+validation, collab sync, and proof-of-done return. If an `update-dashboard`
+call fails because the argument shape was wrong, fix the `update-dashboard`
+arguments and retry once — do not switch tools.
+
 ## Valid Panel Sources
 
 `panel.source` is a backend selector, not a table name. It must be one of:
@@ -174,6 +180,73 @@ 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.
 
+### Existing Dashboard Edits
+
+When the user asks to change existing panels:
+
+1. Read the current dashboard config through the dashboard/action surface.
+2. Find panel indexes by `panel.id` from the current config you just read. Do
+   not rely on seed-file order, stale memory, or screenshots.
+3. Build one `ops` array that includes every change.
+4. Call `update-dashboard` once.
+5. Verify the returned `panelCount`, `appliedOps`, and `summary`. If possible,
+   read the affected panels back and confirm the exact fields changed.
+
+For native production tools, pass `ops` as a native array:
+
+```json
+{
+  "dashboardId": "weekly-metrics",
+  "ops": [
+    {
+      "op": "replace",
+      "path": "/panels/3/sql",
+      "value": "SELECT COUNT(*) AS value FROM analytics_events"
+    },
+    {
+      "op": "replace",
+      "path": "/panels/3/config/description",
+      "value": "Updated definition."
+    }
+  ]
+}
+```
+
+The quoted JSON examples in this skill are for shell commands only. In native
+tool calls, do not pass `ops` as a string. If the tool complains about the
+shape, retry `update-dashboard` with a native array and continue from the same
+dashboard config.
+
+For SQL-only panel edits, replacing `/panels/<index>/sql` is enough. If the
+metric semantics changed, also replace `/panels/<index>/config/description` so
+the visible dashboard explains the new definition. If the title, source, chart
+type, width, or config shape changes together, replace the whole panel object at
+`/panels/<index>` in the same `ops` array.
+
+### First-Party User Metrics
+
+For first-party `/track` events, be precise about identity:
+
+| Metric intent                                | Identity expression                                      |
+| -------------------------------------------- | -------------------------------------------------------- |
+| Account users, DAU, WAU, retention, cohorts  | `NULLIF(user_id, '')` plus `NULLIF(user_id, '') IS NOT NULL`, but only on events that actually represent the activity being measured |
+| Signed-in visitor activity                   | `event_name = 'session status' AND signed_in = 'true'` keyed by `COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))`, labeled as signed-in visitors rather than account users |
+| Public traffic, visitors, clip/share viewers | `COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))` |
+
+Do not call anonymous visitors "users" in dashboard labels or descriptions.
+When a user asks for DAU, WAU, retention, repeat users, or account cohorts,
+exclude logged-out traffic unless they explicitly ask for visitor metrics. If
+the active/session events do not include account identity, do not substitute
+signup or identify events and call that DAU/WAU. Either update instrumentation to
+send account identity on active events, or label the dashboard metric as
+signed-in visitor activity.
+
+For template/app activity metrics, exclude `docs` from DAU, WAU, retention, and
+repeat-user panels. A docs event may carry `signed_in = true` from shared auth
+state or tracker context, but docs traffic is not app usage and should not appear
+as an app/template series. Use a minimum cohort-size threshold for retention
+rates so one or two identities cannot create misleading 100% or 0% spikes.
+
 ## 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).
@@ -202,6 +275,7 @@ Hosted agent runs have a **~40s budget**. Many sequential `update-dashboard` cal
 - **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`).
+  - In native tool calls, `ops` is an array, not a JSON string. Shell commands quote JSON only because shells need strings.
 - **To add a shipped template's panels, prefer `install-dashboard-template` with `mergePanels: true`** and the existing `dashboardId`. It appends only the template panels whose id is not already present (preserving existing panels and order) in one atomic save — you don't author each panel yourself.
 - **Always verify the returned proof-of-done and report it.** `update-dashboard` returns `panelCount`, `appliedOps`, and a `summary` string; `install-dashboard-template --mergePanels` returns `addedPanelIds`, `skippedExistingIds`, and `panelCount`. Tell the user the resulting panel count instead of assuming success.
 
@@ -243,6 +317,8 @@ Writes require editor access; deletes require admin access. Owners always satisf
 
 - Never fabricate data or create a dashboard from guessed schema. A panel's SQL must hit a real source; do not present figures you did not actually query.
 - Never write dashboard configs into the settings table.
+- Never use `db-patch` as a fallback for dashboard config edits. Use
+  `update-dashboard` and fix the action arguments.
 - Never set `panel.source` to a table name or unsupported backend.
 - Use `first-party` for `/track` data and `query-agent-native-analytics` for ad-hoc first-party event questions.
 - Use `update-dashboard` for creates and edits.

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

@@ -416,6 +416,7 @@ export default defineAction({
     "it resolves org vs. user scope correctly so the edit lands on the row the UI actually renders. " +
     "BATCH ALL EDITS INTO A SINGLE CALL. Never call this action repeatedly in a loop: hosted agent runs have a ~40s budget, and many sequential update-dashboard calls time out mid-way and leave the dashboard in a partial state even though earlier calls looked like they succeeded. Put every change you want to make into one `ops` array (or one `config`). " +
     "`ops` is an array of { op, path, from?, value? } applied in order in a single atomic save. " +
+    "When calling this as a native tool, pass `ops` as a real array, not a JSON string; the shell examples quote JSON only for CLI parsing. If a call fails because `ops` was stringified, retry this action with a native array instead of switching to db-patch or settings writes. " +
     "`op` is one of: set | replace | remove | insert | move | move-before. " +
     "`path` is a JSON Pointer into the config (e.g. `/panels/3` is the 4th panel, `/panels/3/title` is its title, `/name` is the dashboard name). The special index `-` means the end of an array: `/panels/-` appends. " +
     "`value` is the panel or object to set/insert. `from` is the source JSON Pointer for move / move-before. " +

package/corpus/templates/analytics/app/components/dashboard/SqlChart.tsx

@@ -850,7 +850,11 @@ export function SqlChart({
   const isSection = panel.chartType === "section";
   const shouldQuery = !isSection && loadData;
   const sql = serializePanelSql(resolvedSql ?? panel.sql);
-  const { data: result, isLoading } = useSqlQuery(
+  const {
+    data: result,
+    isLoading,
+    error: queryError,
+  } = useSqlQuery(
     ["sql-chart", panel.id, sql, panel.source],
     sql,
     panel.source,
@@ -859,7 +863,14 @@ export function SqlChart({
   );
 
   const rawRows = result?.rows ?? [];
-  const error = result?.error;
+  const queryErrorMessage =
+    queryError instanceof Error
+      ? queryError.message
+      : queryError
+        ? String(queryError)
+        : undefined;
+  const error =
+    rawRows.length === 0 ? (result?.error ?? queryErrorMessage) : undefined;
 
   const { rows, forcedYKeys } = useMemo(() => {
     if (panel.config?.pivot && rawRows.length) {

package/corpus/templates/analytics/app/i18n-data.ts

@@ -347,6 +347,7 @@ const enUS = {
     sectionOptions: "Section options",
     panelOptions: "Panel options",
     fullScreen: "Full screen",
+    refresh: "Refresh",
     downloadCsv: "Download CSV",
     viewSql: "View SQL",
     dragToReorder: "Drag to reorder",
@@ -4969,6 +4970,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "保存失败",
       formatSql: "格式 SQL",
       fullScreen: "全屏",
+      refresh: "刷新",
       hiddenDescription:
         "该仪表板在常规列表中是隐藏的。它仍然可以通过直接链接搜索和打开。",
       noActiveFilters: "当前没有活动的过滤器 - 此视图将应用默认过滤器状态。",
@@ -5142,6 +5144,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "No se pudo guardar",
       formatSql: "Formato SQL",
       fullScreen: "Pantalla completa",
+      refresh: "Actualizar",
       hiddenDescription:
         "Este panel está oculto de las listas habituales. Se puede buscar y abrir mediante enlace directo.",
       noActiveFilters:
@@ -5318,6 +5321,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "Échec de l'enregistrement",
       formatSql: "Format SQL",
       fullScreen: "Plein écran",
+      refresh: "Actualiser",
       hiddenDescription:
         "Ce tableau de bord est masqué dans les listes régulières. Il reste consultable et ouvrable par lien direct.",
       noActiveFilters:
@@ -5495,6 +5499,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "Speichern fehlgeschlagen",
       formatSql: "Formatieren Sie SQL",
       fullScreen: "Vollbild",
+      refresh: "Aktualisieren",
       hiddenDescription:
         "Dieses Dashboard ist vor regulären Listen verborgen. Es bleibt durchsuchbar und kann über einen direkten Link geöffnet werden.",
       noActiveFilters:
@@ -5667,6 +5672,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "保存に失敗しました",
       formatSql: "形式 SQL",
       fullScreen: "全画面表示",
+      refresh: "更新",
       hiddenDescription:
         "このダッシュボードは通常のリストには表示されません。引き続き検索可能で、直接リンクで開くことができます。",
       noActiveFilters:
@@ -5838,6 +5844,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "저장하지 못했습니다.",
       formatSql: "SQL 형식",
       fullScreen: "전체 화면",
+      refresh: "새로고침",
       hiddenDescription:
         "이 대시보드는 일반 목록에서 숨겨져 있습니다. 직접 링크를 통해 검색 및 열 수 있습니다.",
       noActiveFilters:
@@ -6013,6 +6020,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "Falha ao salvar",
       formatSql: "Formato SQL",
       fullScreen: "Tela cheia",
+      refresh: "Atualizar",
       hiddenDescription:
         "Este painel está oculto nas listas regulares. Ele permanece pesquisável e aberto por link direto.",
       noActiveFilters:
@@ -6184,6 +6192,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "सहेजने में विफल",
       formatSql: "प्रारूप SQL",
       fullScreen: "पूर्ण स्क्रीन",
+      refresh: "रीफ़्रेश करें",
       hiddenDescription:
         "यह डैशबोर्ड नियमित सूचियों से छिपा हुआ है. यह सीधे लिंक द्वारा खोजने योग्य और खोलने योग्य रहता है।",
       noActiveFilters:
@@ -6355,6 +6364,7 @@ const translatedAnalyticsDebtTranslations = {
       failedToSave: "فشل الحفظ",
       formatSql: "تنسيق SQL",
       fullScreen: "شاشة كاملة",
+      refresh: "تحديث",
       hiddenDescription:
         "لوحة التحكم هذه مخفية من القوائم العادية. يظل قابلاً للبحث والفتح عن طريق الرابط المباشر.",
       noActiveFilters: