@agent-native/core-corpus 0.209.2 → 0.209.3-nightly-20261016183441

package/corpus/templates/analytics/app/lib/sql-query.ts

@@ -1,5 +1,12 @@
 import { callAction, useSession } from "@agent-native/core/client/hooks";
 import { DASHBOARD_REPORT_ACTION_TIMEOUT_MS } from "@shared/dashboard-report-timeouts";
+import {
+  isConfirmedPreQueryFailure,
+  isSqlQueryAccessDenied,
+  SqlQueryRefusalError,
+  supportsSqlQueryCacheBypass,
+  type SqlQueryExecutionMetadata,
+} from "@shared/sql-query-contract";
 import {
   MAX_CONCURRENT_FIRST_PARTY_SQL_QUERIES,
   MAX_CONCURRENT_SQL_QUERIES,
@@ -9,15 +16,27 @@ import { useEffect, useRef } from "react";
 
 import type { DataSourceType } from "@/pages/adhoc/sql-dashboard/types";
 
-import { addBytesProcessed } from "./cost-tracker";
+import { recordQueryCost } from "./cost-tracker";
 import {
   DASHBOARD_SESSION_LOADING_SCOPE,
   dashboardCacheScope,
 } from "./prefetch-keys";
+import {
+  describeSqlQueryFreshness,
+  type SqlQueryFreshness,
+} from "./sql-query-freshness";
+import {
+  readSqlQuerySnapshotForSession,
+  removeSqlQuerySnapshotForSession,
+  writeSqlQuerySnapshotForSession,
+} from "./sql-query-snapshot-session";
 
 export { DASHBOARD_REPORT_ACTION_TIMEOUT_MS };
 
-export interface SqlQueryResult {
+export interface SqlQueryResult extends Omit<
+  SqlQueryExecutionMetadata,
+  "bytesProcessed"
+> {
   rows: Record<string, unknown>[];
   error?: string;
   schema?: { name: string; type: string }[];
@@ -139,54 +158,180 @@ type DashboardPanelQueryResponse = SqlQueryResult & {
   message?: string;
 };
 
+type SqlQueryTimingStatus = "success" | "error" | "cancelled" | "timeout";
+
+/** Sources whose queries scan BigQuery, so a lost request may still bill. */
+function scansBigQuery(source: DataSourceType): boolean {
+  return source === "bigquery" || source === "first-party";
+}
+
+/**
+ * One line per query with durations and outcome only. No SQL, rows, account
+ * or credentials, so it is safe to leave on in production.
+ */
+function logSqlQueryTiming(timing: {
+  status: SqlQueryTimingStatus;
+  source: DataSourceType;
+  cacheType: "none" | "app" | "provider" | "unknown";
+  forceRefresh: boolean;
+  queueMs: number;
+  requestMs: number;
+  totalMs: number;
+}): void {
+  console.info("[sql-query] timing", {
+    ...timing,
+    queueMs: Math.round(timing.queueMs),
+    requestMs: Math.round(timing.requestMs),
+    totalMs: Math.round(timing.totalMs),
+  });
+}
+
+function responseMetadata(data: DashboardPanelQueryResponse): {
+  cached?: boolean;
+  providerCacheHit?: boolean;
+  truncated?: boolean;
+  fetchedAt?: string;
+} {
+  const metadata: ReturnType<typeof responseMetadata> = {};
+  if (typeof data.cached === "boolean") metadata.cached = data.cached;
+  if (typeof data.providerCacheHit === "boolean") {
+    metadata.providerCacheHit = data.providerCacheHit;
+  }
+  if (typeof data.truncated === "boolean") metadata.truncated = data.truncated;
+  if (data.fetchedAt !== undefined) {
+    if (
+      typeof data.fetchedAt === "string" &&
+      Number.isFinite(Date.parse(data.fetchedAt))
+    ) {
+      metadata.fetchedAt = data.fetchedAt;
+    } else {
+      // Left absent so the panel says the time is unknown rather than guessing.
+      console.warn("[sql-query] ignored an unreadable fetchedAt");
+    }
+  }
+  return metadata;
+}
+
 export async function executeSqlQuery(
   sql: string,
   source: DataSourceType,
   signal?: AbortSignal,
   options?: { reportScreenshot?: boolean; forceRefresh?: boolean },
 ): Promise<SqlQueryResult> {
+  const startedAt = performance.now();
+  const forceRefresh = Boolean(
+    options?.forceRefresh && supportsSqlQueryCacheBypass(source),
+  );
   const deadline = createDeadlineSignal(
     signal,
     DASHBOARD_REPORT_ACTION_TIMEOUT_MS,
   );
   let release: (() => void) | undefined;
   let data: DashboardPanelQueryResponse;
+  let dispatchedAt: number | undefined;
+  let queueMs = 0;
+  let requestMs = 0;
+  let status: SqlQueryTimingStatus = "success";
+  let cacheType: "none" | "app" | "provider" | "unknown" = "unknown";
   try {
     release = await acquireSqlQuerySlot(source, deadline.signal);
+    dispatchedAt = performance.now();
+    queueMs = dispatchedAt - startedAt;
     data = await callAction<DashboardPanelQueryResponse>(
       "query-dashboard-panel",
       {
         query: sql,
         source,
-        ...(options?.forceRefresh && source === "bigquery"
-          ? { forceRefresh: true }
-          : {}),
+        ...(forceRefresh ? { forceRefresh: true } : {}),
       },
       {
         signal: deadline.signal,
         timeoutMs: DASHBOARD_REPORT_ACTION_TIMEOUT_MS,
       },
     );
+    requestMs = performance.now() - dispatchedAt;
+  } catch (error) {
+    const now = performance.now();
+    if (dispatchedAt === undefined) queueMs = now - startedAt;
+    else requestMs = now - dispatchedAt;
+    status = signal?.aborted
+      ? "cancelled"
+      : deadline.signal.aborted
+        ? "timeout"
+        : "error";
+    // A query still waiting for a slot never reached the warehouse. One that
+    // was sent may have scanned before it failed, so its cost is unknown.
+    if (
+      dispatchedAt !== undefined &&
+      scansBigQuery(source) &&
+      !isConfirmedPreQueryFailure(error)
+    ) {
+      recordQueryCost({
+        status: status === "cancelled" ? "cancelled" : "error",
+      });
+    }
+    logSqlQueryTiming({
+      status,
+      source,
+      cacheType,
+      forceRefresh,
+      queueMs,
+      requestMs,
+      totalMs: now - startedAt,
+    });
+    throw error;
   } finally {
     release?.();
     deadline.cleanup();
   }
 
   if (typeof data?.error === "string") {
-    throw new Error(
-      typeof data.message === "string" && data.message
-        ? data.message
-        : data.error,
-    );
+    // A refusal in the body (missing key, unsupported backend) ran no scan.
+    logSqlQueryTiming({
+      status: "error",
+      source,
+      cacheType,
+      forceRefresh,
+      queueMs,
+      requestMs,
+      totalMs: performance.now() - startedAt,
+    });
+    throw new SqlQueryRefusalError({
+      error: data.error,
+      message: data.message,
+    });
   }
 
-  if (data.bytesProcessed) {
-    addBytesProcessed(data.bytesProcessed);
-  }
+  const metadata = responseMetadata(data);
+  recordQueryCost({
+    status: "success",
+    cached: metadata.cached,
+    providerCacheHit: metadata.providerCacheHit,
+    bytesProcessed: data.bytesProcessed,
+  });
+  // "none" is a claim that both layers missed; a response that does not say
+  // so for each layer is unknown, never a miss.
+  cacheType = metadata.cached
+    ? "app"
+    : metadata.providerCacheHit
+      ? "provider"
+      : metadata.cached === false && metadata.providerCacheHit === false
+        ? "none"
+        : "unknown";
+  logSqlQueryTiming({
+    status,
+    source,
+    cacheType,
+    forceRefresh,
+    queueMs,
+    requestMs,
+    totalMs: performance.now() - startedAt,
+  });
 
   return {
     rows: data.rows ?? [],
     schema: data.schema,
+    ...metadata,
   };
 }
 
@@ -223,6 +368,13 @@ export function useSqlQuery(
      * explicit `refreshToken` refresh does. Ignored when `staleTime` is set.
      */
     reuseCompletedOnEnable?: boolean;
+    /**
+     * Saves each successful result in this tab's session storage and, after a
+     * reload, shows the saved copy for this exact account, SQL and source while
+     * the query's one normal fetch runs. The copy keeps its original fetch
+     * time and is marked `restored` in `freshness`; it is never fresh data.
+     */
+    snapshots?: boolean;
   },
 ) {
   // The signed-in user and org are part of the cache key, so one account's
@@ -244,30 +396,124 @@ export function useSqlQuery(
     accountScope: string;
     retainScope: string;
   } | null>(null);
-  const successfulRefreshToken = useRef(0);
   const refreshToken = options?.refreshToken ?? 0;
   const wantsQuery = options?.enabled ?? true;
   const enabled = wantsQuery && sessionReady;
   const latestRefreshToken = useRef(refreshToken);
   const latestStartedRefreshToken = useRef(refreshToken);
   latestRefreshToken.current = refreshToken;
+  // A manual refresh belongs to the query it was requested on. Sources that
+  // support cache bypass keep it pending until success. It is recorded while
+  // rendering because the fetch it triggers can start before any effect runs.
+  const pendingManualRefresh = useRef<{
+    token: number;
+    queryKeyHash: string;
+    failed?: boolean;
+  } | null>(null);
+  // The manual request whose own forced fetch last completed, for the caller
+  // that shows it. A fetch that started without that request (an automatic
+  // revalidation, a cancelled or failed attempt) never writes it, and it is
+  // dropped as soon as the account or query it belongs to changes.
+  const completedManualRefresh = useRef<{
+    token: number;
+    queryKeyHash: string;
+    completedAt: number;
+  } | null>(null);
+  if (
+    completedManualRefresh.current &&
+    completedManualRefresh.current.queryKeyHash !== queryKeyHash
+  ) {
+    completedManualRefresh.current = null;
+  }
+  const observedRefreshToken = useRef(refreshToken);
+  if (refreshToken > observedRefreshToken.current) {
+    observedRefreshToken.current = refreshToken;
+    pendingManualRefresh.current = { token: refreshToken, queryKeyHash };
+  } else if (
+    pendingManualRefresh.current &&
+    pendingManualRefresh.current.queryKeyHash !== queryKeyHash
+  ) {
+    // The request failed or was superseded, and the panel has moved to
+    // another query: that one is an ordinary automatic load.
+    pendingManualRefresh.current = null;
+  }
   const previousRefreshToken = useRef(refreshToken);
   const previousEnabled = useRef(enabled);
+  const snapshotKey = JSON.stringify([queryKey, sql, source]);
+  const restoredCopy = useRef<{
+    id: string;
+    result: SqlQueryResult | null;
+  } | null>(null);
   const queryClient = useQueryClient();
   const query = useQuery<SqlQueryResult>({
     queryKey: scopedQueryKey,
     queryFn: async ({ signal }) => {
-      const currentRefreshToken = latestRefreshToken.current;
-      latestStartedRefreshToken.current = currentRefreshToken;
-      const forceRefresh = currentRefreshToken > successfulRefreshToken.current;
-      const result = await executeSqlQuery(sql, source, signal, {
-        reportScreenshot: options?.reportScreenshot,
-        forceRefresh,
-      });
-      successfulRefreshToken.current = Math.max(
-        successfulRefreshToken.current,
-        currentRefreshToken,
-      );
+      latestStartedRefreshToken.current = latestRefreshToken.current;
+      const manual = pendingManualRefresh.current;
+      const manualRequested = manual?.queryKeyHash === queryKeyHash;
+      const forceRefresh =
+        manualRequested && supportsSqlQueryCacheBypass(source);
+      let result: SqlQueryResult;
+      try {
+        result = await executeSqlQuery(sql, source, signal, {
+          reportScreenshot: options?.reportScreenshot,
+          forceRefresh,
+        });
+      } catch (error) {
+        if (isSqlQueryAccessDenied(error)) {
+          if (
+            lastShown.current?.accountScope === accountScope &&
+            lastShown.current?.retainScope === retainScope
+          ) {
+            lastShown.current = null;
+          }
+          restoredCopy.current = null;
+          removeSqlQuerySnapshotForSession({
+            accountScope,
+            queryKey: snapshotKey,
+          });
+          // React Query retains data on failed revalidation by default. Remove
+          // just this denied result while letting it commit the real error.
+          queryClient
+            .getQueryCache()
+            .find({ queryKey: scopedQueryKey, exact: true })
+            ?.setState({
+              data: undefined,
+              dataUpdatedAt: 0,
+              error,
+              status: "error",
+            });
+        }
+        // The request stays pending for the cache bypass, but a later success
+        // is not the one the user asked for.
+        if (manual && forceRefresh && !signal.aborted) manual.failed = true;
+        if (
+          manualRequested &&
+          !forceRefresh &&
+          pendingManualRefresh.current === manual
+        ) {
+          pendingManualRefresh.current = null;
+        }
+        throw error;
+      }
+      if (manualRequested && pendingManualRefresh.current === manual) {
+        pendingManualRefresh.current = null;
+      }
+      if (manual && forceRefresh && !manual.failed && !signal.aborted) {
+        completedManualRefresh.current = {
+          token: manual.token,
+          queryKeyHash,
+          completedAt: Date.now(),
+        };
+      }
+      if (options?.snapshots) {
+        writeSqlQuerySnapshotForSession({
+          accountScope,
+          queryKey: snapshotKey,
+          result,
+          signal,
+        });
+      }
       return result;
     },
     enabled,
@@ -275,15 +521,22 @@ export function useSqlQuery(
     refetchOnMount: options?.refetchOnMount ?? false,
     refetchOnReconnect: options?.refetchOnReconnect ?? false,
     refetchOnWindowFocus: options?.refetchOnWindowFocus ?? false,
-    retry: options?.retry ?? false,
+    retry: (failureCount, error) => {
+      if (isSqlQueryAccessDenied(error)) return false;
+      const retry = options?.retry ?? false;
+      return typeof retry === "number" ? failureCount < retry : retry;
+    },
     staleTime:
       options?.staleTime ??
       (options?.reuseCompletedOnEnable ? Infinity : 5 * 60 * 1000),
   });
   const refetch = query.refetch;
+  const accessDenied = isSqlQueryAccessDenied(query.error);
 
   useEffect(() => {
-    if (query.data && sessionReady && retainScope !== undefined) {
+    if (accessDenied) {
+      lastShown.current = null;
+    } else if (query.data && sessionReady && retainScope !== undefined) {
       lastShown.current = {
         data: query.data,
         queryKeyHash,
@@ -296,7 +549,14 @@ export function useSqlQuery(
     ) {
       lastShown.current = null;
     }
-  }, [query.data, sessionReady, retainScope, queryKeyHash, accountScope]);
+  }, [
+    query.data,
+    sessionReady,
+    retainScope,
+    queryKeyHash,
+    accountScope,
+    accessDenied,
+  ]);
 
   useEffect(() => {
     const wasEnabled = previousEnabled.current;
@@ -304,15 +564,15 @@ export function useSqlQuery(
     const refreshTokenChanged = refreshToken > previousRefreshToken.current;
     previousRefreshToken.current = refreshToken;
     if (!enabled) return;
-    const enablingPendingRefresh =
-      !wasEnabled && refreshToken > successfulRefreshToken.current;
-    if (
-      (!refreshTokenChanged && !enablingPendingRefresh) ||
-      refreshToken <= successfulRefreshToken.current
-    ) {
+    const pending = pendingManualRefresh.current;
+    const enablingPendingRefresh = !wasEnabled && pending !== null;
+    if (!pending || (!refreshTokenChanged && !enablingPendingRefresh)) {
       return;
     }
-    if (query.isFetching && latestStartedRefreshToken.current >= refreshToken) {
+    if (
+      query.isFetching &&
+      latestStartedRefreshToken.current >= pending.token
+    ) {
       return;
     }
     void queryClient
@@ -327,12 +587,76 @@ export function useSqlQuery(
     refreshToken,
   ]);
 
+  // The saved copy is read once per account and query, and only for a query
+  // with nothing in memory. Once the query has data the copy is spent, so a
+  // later cache eviction cannot bring back rows older than ones already shown.
+  const restoreId = `${accountScope}
+${snapshotKey}`;
+  let restored: SqlQueryResult | null = null;
+  if (accessDenied) {
+    restoredCopy.current = { id: restoreId, result: null };
+  } else if (options?.snapshots && sessionReady && query.data === undefined) {
+    if (restoredCopy.current?.id !== restoreId) {
+      const read = readSqlQuerySnapshotForSession({
+        accountScope,
+        queryKey: snapshotKey,
+      });
+      restoredCopy.current = {
+        id: restoreId,
+        result: read.status === "hit" ? read.snapshot.result : null,
+      };
+    }
+    restored = restoredCopy.current.result;
+  } else if (query.data !== undefined && restoredCopy.current) {
+    restoredCopy.current = { id: restoreId, result: null };
+  }
+
+  const freshnessOf = (
+    data: SqlQueryResult | undefined,
+    isRestored: boolean,
+  ): SqlQueryFreshness | undefined =>
+    describeSqlQueryFreshness(data, { source, restored: isRestored });
+  // Offered only once the data it produced has been committed to the query.
+  const completion = completedManualRefresh.current;
+  const completedManualRefreshToken =
+    completion &&
+    completion.queryKeyHash === queryKeyHash &&
+    query.data !== undefined &&
+    query.dataUpdatedAt >= completion.completedAt
+      ? completion.token
+      : undefined;
   if (!sessionReady && wantsQuery) {
     return {
       ...query,
       data: undefined,
       isPlaceholderData: false,
       isLoading: true,
+      freshness: undefined,
+      completedManualRefreshToken: undefined,
+    };
+  }
+  if (accessDenied) {
+    return {
+      ...query,
+      data: undefined,
+      isPlaceholderData: false,
+      isLoading: false,
+      freshness: undefined,
+      completedManualRefreshToken: undefined,
+    };
+  }
+  if (
+    restored &&
+    query.data === undefined &&
+    (enabled || (options?.retainWhilePaused && sessionReady))
+  ) {
+    return {
+      ...query,
+      data: restored,
+      isPlaceholderData: false,
+      isLoading: false,
+      freshness: freshnessOf(restored, true),
+      completedManualRefreshToken: undefined,
     };
   }
   const held = lastShown.current;
@@ -348,7 +672,13 @@ export function useSqlQuery(
       data: held.data,
       isPlaceholderData: held.queryKeyHash !== queryKeyHash,
       isLoading: false,
+      freshness: freshnessOf(held.data, false),
+      completedManualRefreshToken: undefined,
     };
   }
-  return query;
+  return {
+    ...query,
+    freshness: freshnessOf(query.data, false),
+    completedManualRefreshToken,
+  };
 }

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/SqlChartCard.tsx

@@ -34,6 +34,8 @@ import {
   DataNoteLines,
   UnplacedDataNotesListener,
 } from "@/components/dashboard/data-note-bands";
+import type { PanelFreshness } from "@/components/dashboard/panel-freshness";
+import { PanelFreshnessClock } from "@/components/dashboard/PanelFreshnessClock";
 import { ChartFillHeight, SqlChart } from "@/components/dashboard/SqlChart";
 import {
   AlertDialog,
@@ -87,6 +89,29 @@ import { ViewSqlPopover } from "./ViewSqlPopover";
 
 const INHERIT_TIME_RANGE = "__inherit__";
 
+function PanelTitle({ title }: { title: string }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <CardTitle className="min-w-0 text-sm font-medium">
+      <Tooltip open={open} onOpenChange={setOpen}>
+        <TooltipTrigger asChild>
+          <button
+            type="button"
+            onClick={(event) => {
+              event.preventDefault();
+              setOpen(true);
+            }}
+            className="block max-w-full truncate rounded text-start focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {title}
+          </button>
+        </TooltipTrigger>
+        <TooltipContent>{title}</TooltipContent>
+      </Tooltip>
+    </CardTitle>
+  );
+}
+
 export function dashboardTileElementId(panelId: string): string {
   return `dashboard-tile-${panelId}`;
 }
@@ -275,6 +300,28 @@ export function SqlChartCard({
     setExportCsv(handler ? () => handler : null);
   }, []);
 
+  // Keyed by the panel it was reported for, so a card reused for another
+  // panel or dashboard never shows the previous one's clock.
+  const panelScope = JSON.stringify([
+    accountScope,
+    dashboardId ?? null,
+    panel.id,
+  ]);
+  const [reportedFreshness, setReportedFreshness] = useState<{
+    scope: string;
+    freshness: PanelFreshness | null;
+  } | null>(null);
+  const handleFreshnessChange = useCallback(
+    (freshness: PanelFreshness | null) => {
+      setReportedFreshness({ scope: panelScope, freshness });
+    },
+    [panelScope],
+  );
+  const panelFreshness =
+    reportedFreshness?.scope === panelScope
+      ? reportedFreshness.freshness
+      : null;
+
   const handleCopyTableChange = useCallback(
     (handler: (() => Promise<void>) | null) => {
       setCopyTable(handler ? () => handler : null);
@@ -716,26 +763,33 @@ export function SqlChartCard({
           highlighted && "ring-2 ring-primary",
         )}
       >
-        <CardHeader className="pb-2 flex flex-row items-center gap-2 shrink-0">
-          <div className="flex min-w-0 flex-1 items-center gap-1">
-            <CardTitle className="text-sm font-medium truncate">
-              {panel.title}
-            </CardTitle>
+        <CardHeader className="dashboard-panel-header grid space-y-0 shrink-0 pb-2">
+          <div className="dashboard-panel-title flex min-w-0 items-center gap-1">
+            <PanelTitle title={panel.title} />
             <DataNoteFlag notes={flaggedDataNotes} panelId={panel.id} />
+            {timeRangeOverrideLabel ? (
+              <Badge
+                variant="secondary"
+                className="max-w-20 min-w-0 shrink truncate px-1.5 py-0 text-[10px] font-normal"
+                title={timeRangeOverrideLabel}
+              >
+                <span className="sr-only">
+                  {t("sqlDashboard.chartTimeRangeOverride")}{" "}
+                </span>
+                {timeRangeOverrideLabel}
+              </Badge>
+            ) : null}
           </div>
-          {timeRangeOverrideLabel ? (
-            <Badge
-              variant="secondary"
-              className="max-w-32 shrink-0 truncate px-1.5 py-0 text-[10px] font-normal"
-              title={timeRangeOverrideLabel}
-            >
-              <span className="sr-only">
-                {t("sqlDashboard.chartTimeRangeOverride")}{" "}
-              </span>
-              {timeRangeOverrideLabel}
-            </Badge>
-          ) : null}
-          <div className="flex items-center gap-1 opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100">
+          <div className="dashboard-panel-freshness min-w-0 overflow-hidden">
+            {panelFreshness ? (
+              <PanelFreshnessClock
+                freshness={panelFreshness}
+                showAge
+                className="h-6 w-full px-1"
+              />
+            ) : null}
+          </div>
+          <div className="dashboard-panel-actions flex items-center justify-end gap-1 opacity-0 transition-opacity motion-reduce:transition-none group-hover:opacity-100 focus-within:opacity-100 [@media(hover:none)]:opacity-100">
             {!editable || onSaveSql ? (
               <ViewSqlPopover
                 panel={panel}
@@ -926,6 +980,7 @@ export function SqlChartCard({
               onRefreshRequested={handleRefresh}
               dashboardId={dashboardId}
               onExportCsvChange={handleExportCsvChange}
+              onFreshnessChange={handleFreshnessChange}
               onCopyTableChange={handleCopyTableChange}
               {...tableColumnProps}
               extensionContext={extensionContext}