@agent-native/core 0.161.1 → 0.161.2

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

@@ -13,7 +13,7 @@ import {
   upsertDashboard,
   upsertDashboardWithRetry,
 } from "../server/lib/dashboards-store";
-import { validateFirstPartyAnalyticsSql } from "../server/lib/first-party-analytics.js";
+import { validateFirstPartyAnalyticsSqlForScope } from "../server/lib/first-party-analytics.js";
 import {
   buildFirstPartyDashboardFilters,
   buildPanel,
@@ -212,7 +212,10 @@ export default defineAction({
           invalidMetrics.push({ metric: req.metric, reason: timeScopeError });
           continue;
         }
-        validateFirstPartyAnalyticsSql(panel.sql);
+        await validateFirstPartyAnalyticsSqlForScope(panel.sql, {
+          userEmail: ctx.email,
+          orgId: ctx.orgId,
+        });
       } catch (e: any) {
         invalidMetrics.push({
           metric: req.metric,

package/corpus/templates/analytics/actions/export-dashboard-panel-to-google-sheet.ts

@@ -31,14 +31,20 @@ function asPanels(config: Record<string, unknown>): DashboardPanel[] {
     : [];
 }
 
-function missingKeyMessage(result: unknown): string | null {
+/**
+ * Any structured panel failure (`missing_api_key`, `unsupported_by_backend`)
+ * carries its own explanation. Surface that rather than the generic
+ * invalid-result message below, which reads as a bug in the export.
+ */
+function panelFailureMessage(result: unknown): string | null {
   if (!result || typeof result !== "object" || Array.isArray(result)) {
     return null;
   }
   const value = result as { error?: unknown; message?: unknown };
-  return value.error === "missing_api_key" && typeof value.message === "string"
+  if (typeof value.error !== "string" || !value.error) return null;
+  return typeof value.message === "string" && value.message
     ? value.message
-    : null;
+    : value.error;
 }
 
 export default defineAction({
@@ -97,8 +103,8 @@ export default defineAction({
       { source: panel.source, query },
       context,
     );
-    const missing = missingKeyMessage(result);
-    if (missing) throw new Error(missing);
+    const failure = panelFailureMessage(result);
+    if (failure) throw new Error(failure);
     if (
       !result ||
       typeof result !== "object" ||

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

@@ -9,13 +9,79 @@ import {
   getFirstPartyAnalyticsBigQueryBackfillJob,
   queueFirstPartyAnalyticsBigQueryBackfill,
 } from "../server/jobs/analytics-bigquery-backfill.js";
+import { listDashboards } from "../server/lib/dashboards-store.js";
 import { requireAnalyticsAdminContext } from "../server/lib/db-admin-connections.js";
 import {
   assertFirstPartyAnalyticsBigQueryReady,
+  assertFirstPartyAnalyticsBigQuerySql,
+  FirstPartyAnalyticsUnsupportedSqlError,
+  type FirstPartyAnalyticsScope,
   getFirstPartyAnalyticsBackend,
   saveFirstPartyAnalyticsBackend,
 } from "../server/lib/first-party-analytics-backend.js";
 
+interface UnrunnablePanel {
+  dashboardId: string;
+  dashboardName: string;
+  panelId: string;
+  panelTitle: string;
+  reason: string;
+}
+
+/**
+ * Stored first-party panels the BigQuery sink cannot run. Cutover only flips a
+ * setting — it never rewrites saved SQL — so every panel listed here starts
+ * failing the moment the flip lands. Surfacing the list is the whole point: the
+ * alternative is the org discovering it as broken panels afterwards.
+ */
+async function findPanelsUnrunnableOnBigQuery(
+  scope: FirstPartyAnalyticsScope,
+): Promise<UnrunnablePanel[]> {
+  const dashboards = await listDashboards(
+    { email: scope.userEmail, orgId: scope.orgId },
+    { kind: "sql", archived: "all" },
+  );
+  const unrunnable: UnrunnablePanel[] = [];
+  for (const dashboard of dashboards) {
+    const panels = Array.isArray(dashboard.config?.panels)
+      ? dashboard.config.panels
+      : [];
+    for (const raw of panels) {
+      const panel = raw as Record<string, unknown>;
+      if (panel?.source !== "first-party") continue;
+      if (typeof panel.sql !== "string" || !panel.sql.trim()) continue;
+      try {
+        // Stored `{{var}}` tokens are left uninterpolated on purpose: the
+        // translator rejects syntax, not values, and filter values are never
+        // syntax. Interpolating here would drag the dashboard-save module — and
+        // its whole import chain — into this action.
+        assertFirstPartyAnalyticsBigQuerySql(panel.sql);
+      } catch (error) {
+        unrunnable.push({
+          dashboardId: dashboard.id,
+          dashboardName: dashboard.title,
+          panelId: typeof panel.id === "string" ? panel.id : "(unnamed)",
+          panelTitle: typeof panel.title === "string" ? panel.title : "",
+          reason:
+            error instanceof FirstPartyAnalyticsUnsupportedSqlError
+              ? `uses ${error.construct}`
+              : `${(error as Error)?.message ?? String(error)}`,
+        });
+      }
+    }
+  }
+  return unrunnable;
+}
+
+function describeUnrunnablePanels(panels: UnrunnablePanel[]): string {
+  return panels
+    .map(
+      (panel) =>
+        `${panel.dashboardId}/${panel.panelId} "${panel.panelTitle}" ${panel.reason}`,
+    )
+    .join("; ");
+}
+
 async function resolveScope() {
   const userEmail = getRequestUserEmail();
   if (!userEmail) throw new Error("no authenticated user");
@@ -48,15 +114,21 @@ const migrationSchema = z.object({
       "Optional per-page limit used when mode is prepare; for an existing job, it can only increase the bounded batch size. The durable worker then processes non-overlapping UTC time shards in parallel.",
     ),
   confirm: z.boolean().optional(),
+  acknowledgeUnrunnablePanels: z
+    .boolean()
+    .optional()
+    .describe(
+      "Cut over even though status reported saved first-party panels the BigQuery backend cannot run. Those panels render an unsupported-backend state until their SQL is rewritten; nothing migrates or rewrites them.",
+    ),
 });
 
 export default defineAction({
   description:
-    "Production migration for the current Analytics organization. Run prepare to validate the configured BigQuery table, enter dual-write mode, and enqueue a durable worker. The worker creates non-overlapping UTC time shards, processes the newest shards first with bounded parallel leases, persists per-shard cursors, and pauses on database pressure. Call status or backfill to inspect progress, then call cutover with confirm=true only after the worker reports completed. New /track events stay in Postgres during dual-write, so a BigQuery outage does not silently lose live data. Cutover is the only step that stops first-party event and rollup writes to Postgres; public-key metadata, derived exception issues, and session-replay data remain in the SQL store.",
+    "Production migration for the current Analytics organization. Run prepare to validate the configured BigQuery table, enter dual-write mode, and enqueue a durable worker. The worker creates non-overlapping UTC time shards, processes the newest shards first with bounded parallel leases, persists per-shard cursors, and pauses on database pressure. Call status or backfill to inspect progress, then call cutover with confirm=true only after the worker reports completed. status and cutover both list saved first-party dashboard panels whose SQL the BigQuery backend cannot run; cutover refuses to flip while any exist unless acknowledgeUnrunnablePanels=true, because the flip never rewrites stored SQL. New /track events stay in Postgres during dual-write, so a BigQuery outage does not silently lose live data. Cutover is the only step that stops first-party event and rollup writes to Postgres; public-key metadata, derived exception issues, and session-replay data remain in the SQL store.",
   schema: migrationSchema,
   agentTool: false,
   needsApproval: ({ mode }) => mode === "cutover",
-  run: async ({ mode, table, limit, confirm }) => {
+  run: async ({ mode, table, limit, confirm, acknowledgeUnrunnablePanels }) => {
     const scope = await resolveScope();
     const current = await getFirstPartyAnalyticsBackend(scope);
     const configuredTable = table ?? current.table;
@@ -70,8 +142,13 @@ export default defineAction({
         current.sink === "postgres"
           ? null
           : await getFirstPartyAnalyticsBigQueryBackfillJob(scope);
+      const unrunnablePanels =
+        current.sink === "bigquery"
+          ? []
+          : await findPanelsUnrunnableOnBigQuery(scope);
       return {
         ...current,
+        unrunnablePanels,
         backfillCursor:
           current.sink === "dual"
             ? (job?.cursor ?? null)
@@ -171,6 +248,15 @@ export default defineAction({
       );
     }
     const ready = await assertFirstPartyAnalyticsBigQueryReady(current.table);
+    const unrunnablePanels = await findPanelsUnrunnableOnBigQuery(scope);
+    if (unrunnablePanels.length && !acknowledgeUnrunnablePanels) {
+      throw Object.assign(
+        new Error(
+          `${unrunnablePanels.length} saved first-party panel(s) cannot run on BigQuery and would start failing at cutover: ${describeUnrunnablePanels(unrunnablePanels)}. Rewrite them in BigQuery-compatible SQL, or pass acknowledgeUnrunnablePanels=true to cut over and leave them showing an unsupported-backend state.`,
+        ),
+        { unrunnablePanels },
+      );
+    }
     await saveFirstPartyAnalyticsBackend(scope, {
       sink: "bigquery",
       table: ready.table.fullyQualified,
@@ -182,6 +268,7 @@ export default defineAction({
       table: ready.table.fullyQualified,
       existingBigQueryRows: ready.rowCount,
       postgresEventWrites: "stopped",
+      unrunnablePanels,
       next: "verify dashboards",
     };
   },

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

@@ -15,7 +15,8 @@ import {
   upsertDashboardWithRetry,
 } from "../server/lib/dashboards-store";
 import { parseDemoDescriptor } from "../server/lib/demo-source";
-import { validateFirstPartyAnalyticsSql } from "../server/lib/first-party-analytics.js";
+import { FirstPartyAnalyticsUnsupportedSqlError } from "../server/lib/first-party-analytics-backend.js";
+import { validateFirstPartyAnalyticsSqlForScope } from "../server/lib/first-party-analytics.js";
 import { DASHBOARD_SQL_VALIDATION_TIMEOUT_MS } from "../shared/dashboard-report-timeouts.js";
 import {
   applyPanelOrder,
@@ -391,6 +392,11 @@ export function validateDashboardConfig(
 
 const MAX_CONCURRENT_SQL_VALIDATIONS = 8;
 
+function firstPartyScope() {
+  const { email, orgId } = resolveScope();
+  return { userEmail: email, orgId };
+}
+
 export interface ValidatePanelSqlOptions {
   signal?: AbortSignal;
 }
@@ -445,7 +451,10 @@ export async function validatePanelSql(
             i,
           );
           if (timeScopeError) return timeScopeError;
-          validateFirstPartyAnalyticsSql(interpolate(raw, vars));
+          await validateFirstPartyAnalyticsSqlForScope(
+            interpolate(raw, vars),
+            firstPartyScope(),
+          );
         } catch (e: any) {
           if (
             typeof e?.message === "string" &&
@@ -453,6 +462,9 @@ export async function validatePanelSql(
           ) {
             return e.message;
           }
+          if (e instanceof FirstPartyAnalyticsUnsupportedSqlError) {
+            return `panel[${i}] "${p.title || p.id}" cannot run on this scope's active data backend (BigQuery) because its SQL uses ${e.construct}. Rewrite it with BigQuery-compatible SQL, or move the scope back to the PostgreSQL backend.`;
+          }
           return `panel[${i}] "${p.title || p.id}" first-party analytics SQL is invalid: ${e?.message ?? e}`;
         }
       }

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

@@ -104,6 +104,12 @@ function parseProgramDescriptor(sql: string): {
   paramsText: string;
 } {
   if (!sql.trim()) return { programId: "", paramsText: "" };
+  // A panel may be stored as the bare program id — the server accepts that as a
+  // complete descriptor, so the editor has to show it rather than blanking the
+  // picker on a JSON.parse it was never going to satisfy.
+  if (/^dp_[A-Za-z0-9]+$/.test(sql.trim())) {
+    return { programId: sql.trim(), paramsText: "" };
+  }
   try {
     const parsed = JSON.parse(sql) as { programId?: unknown; params?: unknown };
     const programId =

package/corpus/templates/analytics/server/lib/dashboard-panel-query.ts

@@ -10,6 +10,7 @@ import { getUserSegmentation, queryEvents } from "./amplitude";
 import { runQuery } from "./bigquery";
 import { runDemoPanel, serializeDemoDescriptorInput } from "./demo-source";
 import { queryFirstPartyAnalytics } from "./first-party-analytics";
+import { FirstPartyAnalyticsUnsupportedSqlError } from "./first-party-analytics-backend";
 import { runReport } from "./google-analytics";
 import {
   runPrometheusPanel,
@@ -36,6 +37,19 @@ export interface DashboardPanelQueryResult {
   bytesProcessed?: number;
 }
 
+/**
+ * A stored panel the active data backend cannot run at all. It carries no
+ * `rows` on purpose: an empty result set would be indistinguishable from a
+ * query that legitimately matched nothing, and this panel matched nothing
+ * because it never ran.
+ */
+export interface UnsupportedBackendResponse {
+  error: "unsupported_by_backend";
+  backend: "bigquery";
+  construct: string;
+  message: string;
+}
+
 export function isDashboardPanelSource(
   value: unknown,
 ): value is DashboardPanelSource {
@@ -45,43 +59,48 @@ export function isDashboardPanelSource(
   );
 }
 
+export interface ProgramDescriptor {
+  programId: string;
+  params?: Record<string, unknown>;
+}
+
+/** Stored data program id: `dp_` + a random hex id. */
+const PROGRAM_ID_PATTERN = /^dp_[A-Za-z0-9]+$/;
+
 /**
  * program panels carry a JSON blob in `sql` describing which stored data
  * program to run and with what params. Shape:
  * { programId: string; params?: Record<string, unknown> }.
+ *
+ * A bare program id is part of that grammar, not a fallback: with no params the
+ * id IS the whole descriptor, and it is what every caller reaches for first.
+ * Writer and reader both resolve through here so they cannot disagree — the
+ * writer used to pass any string straight through while the reader required
+ * JSON, so a panel saved as `dp_01c5e3d...` threw `is not valid JSON` on every
+ * render instead of rendering. Anything that is neither a descriptor nor an id
+ * still throws; an unreadable panel must never resolve to an empty one.
  */
-export function serializeProgramDescriptorInput(raw: unknown): string {
-  if (typeof raw === "string") return raw;
-  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
-    const obj = raw as Record<string, unknown>;
-    if (typeof obj.programId !== "string" || !obj.programId.trim()) {
+export function coerceProgramDescriptor(raw: unknown): ProgramDescriptor {
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed) {
       throw new Error("program panel descriptor requires a 'programId' field");
     }
-    return JSON.stringify(raw);
-  }
-  throw new Error(
-    "program panel sql must be a JSON string or object with 'programId'",
-  );
-}
-
-export interface ProgramDescriptor {
-  programId: string;
-  params?: Record<string, unknown>;
-}
-
-function parseProgramDescriptor(raw: string): ProgramDescriptor {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err: any) {
-    throw new Error(
-      `program panel sql must be a JSON object: ${err?.message ?? err}`,
-    );
+    if (PROGRAM_ID_PATTERN.test(trimmed)) return { programId: trimmed };
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (err: any) {
+      throw new Error(
+        `program panel sql must be a program id or a JSON object: ${err?.message ?? err}`,
+      );
+    }
+    return coerceProgramDescriptor(parsed);
   }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("program panel sql must be a JSON object");
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("program panel sql must be a program id or a JSON object");
   }
-  const obj = parsed as Record<string, unknown>;
+  const obj = raw as Record<string, unknown>;
   if (typeof obj.programId !== "string" || !obj.programId.trim()) {
     throw new Error("program panel descriptor requires a 'programId' field");
   }
@@ -89,7 +108,15 @@ function parseProgramDescriptor(raw: string): ProgramDescriptor {
     obj.params && typeof obj.params === "object" && !Array.isArray(obj.params)
       ? (obj.params as Record<string, unknown>)
       : undefined;
-  return { programId: obj.programId, params };
+  return { programId: obj.programId.trim(), ...(params ? { params } : {}) };
+}
+
+export function serializeProgramDescriptorInput(raw: unknown): string {
+  return JSON.stringify(coerceProgramDescriptor(raw));
+}
+
+function parseProgramDescriptor(raw: string): ProgramDescriptor {
+  return coerceProgramDescriptor(raw);
 }
 
 export function normalizeDashboardPanelQuery(
@@ -406,7 +433,9 @@ export async function runDashboardPanelQuery(args: {
   query: string;
   ctx: CredentialContext;
   timeoutMs?: number;
-}): Promise<DashboardPanelQueryResult | MissingKeyResponse> {
+}): Promise<
+  DashboardPanelQueryResult | MissingKeyResponse | UnsupportedBackendResponse
+> {
   const { source, query, ctx, timeoutMs } = args;
 
   if (source === "bigquery") {
@@ -452,17 +481,36 @@ export async function runDashboardPanelQuery(args: {
   }
 
   if (source === "first-party") {
-    return await queryFirstPartyAnalytics(
-      query,
-      {
-        userEmail: ctx.userEmail,
-        orgId: ctx.orgId ?? null,
-      },
-      {
-        cache: true,
-        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-      },
-    );
+    try {
+      return await queryFirstPartyAnalytics(
+        query,
+        {
+          userEmail: ctx.userEmail,
+          orgId: ctx.orgId ?? null,
+        },
+        {
+          cache: true,
+          ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        },
+      );
+    } catch (error) {
+      // Only the "no BigQuery equivalent exists" failure becomes a rendered
+      // state. Every other failure — timeout, permission, provider outage —
+      // still throws, because those are retryable and must not read to the
+      // user as a permanent property of the panel.
+      if (!(error instanceof FirstPartyAnalyticsUnsupportedSqlError))
+        throw error;
+      console.error(
+        "[first-party-analytics] Panel SQL has no BigQuery translation:",
+        error,
+      );
+      return {
+        error: "unsupported_by_backend",
+        backend: "bigquery",
+        construct: error.construct,
+        message: `This panel can't run on your current data backend (BigQuery) because its SQL uses ${error.construct}. Edit the panel's SQL, or switch the backend back to PostgreSQL.`,
+      };
+    }
   }
 
   if (source === "demo") {

package/corpus/templates/analytics/server/lib/dashboard-panel-source-resolver.ts

@@ -12,8 +12,13 @@ import {
   type DashboardPanelQueryResult,
   type DashboardPanelSource,
   runDashboardPanelQuery,
+  type UnsupportedBackendResponse,
 } from "./dashboard-panel-query";
 
+type AnalyticsPanelSourceFailure =
+  | MissingKeyResponse
+  | UnsupportedBackendResponse;
+
 type AnalyticsPanelSourceResolver = PanelSourceResolver<
   DashboardPanelSource,
   CredentialContext
@@ -35,7 +40,7 @@ function createResolver(
         query: request.query,
         ctx: context,
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-      })) as DashboardPanelQueryResult | MissingKeyResponse;
+      })) as DashboardPanelQueryResult | AnalyticsPanelSourceFailure;
     },
   };
 }
@@ -51,8 +56,8 @@ const registry = createPanelSourceResolverRegistry<
 export async function resolveAnalyticsPanelSource(
   request: AnalyticsPanelSourceRequest,
   context: CredentialContext,
-): Promise<PanelSourceResult | MissingKeyResponse> {
+): Promise<PanelSourceResult | AnalyticsPanelSourceFailure> {
   return registry.resolve(request, context) as Promise<
-    PanelSourceResult | MissingKeyResponse
+    PanelSourceResult | AnalyticsPanelSourceFailure
   >;
 }

package/corpus/templates/analytics/server/lib/error-capture.ts

@@ -396,6 +396,12 @@ function normalizeMessageForFingerprint(message: string): string {
       .replace(/(['"`])[^\s'"`]*\1/g, "<str>")
       .replace(/(?:\/[\w.@%+-]+){2,}\/?/g, "<path>")
       .replace(/0x[0-9a-f]+/gi, "<hex>")
+      // Bare hex ids (request ids, trace ids, the gateway's "ERROR ID: ...")
+      // carry no dashes and no 0x, so they used to fall through to the digit
+      // rule below — which keeps the a-f nibbles and gives every occurrence its
+      // own key. An outage then renders as N unrelated issues of count 1.
+      // Requiring a letter AND a digit keeps prose and identifiers out.
+      .replace(/\b(?=[0-9a-f]*[a-f])(?=[0-9a-f]*\d)[0-9a-f]{8,}\b/gi, "<hex>")
       // Not \b\d+\b: a unit suffix ("8000ms") keeps the digits word-adjacent, so
       // a bounded rule leaves every timeout value in its own group.
       .replace(/\d+/g, "<n>")