@agent-native/core-corpus 0.210.0-nightly-20261019153056 → 0.210.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Builder.io, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 12906
+- template files: 12899

package/corpus/templates/analytics/.agents/skills/actions/SKILL.md

@@ -170,10 +170,10 @@ Everything else — CRUD, settings, search, list/detail reads, auth state, anyth
 - **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
 - **Do** use `fail(message, { errorCode, statusCode })` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
 - **Do** signal failure by throwing, using `fail()` for expected caller-readable failures. Never return `{ error: ... }` as a failure result: a normal return is treated as a successful action. Reserve bare errors for unexpected internal faults.
-- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser; unexpected errors become a generic 500. Reserve bare throws for internal faults.
+- **Do** use `fail()` rather than a bare `Error` for caller-readable failures. It carries the action's message, `errorCode`, and `details` to the browser and to agents; unexpected errors become a generic 500. Reserve bare throws for internal faults.
 - **Do** give `fail()` the status that matches the cause: it defaults to `400`, and `useActionQuery` retries only `429`, `502`, `503`, and `504`. Mutations do not retry; use transient statuses only for retryable failures.
 - **Do** render `actionErrorMessage(error) ?? yourCopy` in UI, never bare `error.message`. The message keeps an `Action <name> failed:` prefix that belongs in a console, so a toast built from it reads "Action update-brand-kit failed: That name is taken." The helper returns only what the action wrote, and `undefined` when nothing did (network drop, proxy HTML page), which is why the fallback is not optional.
-- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP; `details` and the status never reach either.
+- **Do** pass a real `errorCode` when the agent should branch on the failure rather than re-read it. Codes other than the default `action_failed` are appended to the tool result as `(errorCode: not_found)`, on both the in-app agent and MCP. `details` follow as an `Error details: {...}` JSON line, and as `structuredContent.error` over MCP, capped at 2,000 characters, so keep them to what the agent acts on next: ids, limits, field names. The status never reaches either.
 - **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
 - **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
 

package/corpus/templates/analytics/.agents/skills/data-querying/SKILL.md

@@ -79,7 +79,14 @@ exception is the legacy `@app_events` table, which keeps a test identity's
 `$exception` rows marked `JSON_VALUE(data, '$.test_identity') = 'true'`;
 exclude those from any metric over it.
 
-Before a large or historical first-party query, call
+When the user rules out BigQuery, skip the health check below, which queries
+BigQuery on a BigQuery-backed scope. Call `get-first-party-analytics-backend`
+to see which tables Postgres serves, then pass `backend: "postgres"` to
+`query-agent-native-analytics`. If it fails with
+`first_party_backend_not_postgres`, this scope reads those tables only from
+BigQuery: say so and let the user decide.
+
+Otherwise, before a large or historical first-party query, call
 `get-first-party-analytics-health`. Keep Neon as the default while its status is
 `healthy` or `monitor`; a `recommend_bigquery` result means the app has observed
 1M+ events, repeated slow queries, or a timeout/30-second query. Treat that
@@ -103,6 +110,22 @@ BigQuery `insertId` values for retry-safe writes. After cutover, `/track`
 writes and event queries use BigQuery; public-key metadata, derived exception
 issues, and session-replay data remain in SQL.
 
+After cutover, an org admin can point charts at a scheduled warehouse events
+model with `configure-first-party-events-model`; run `check` first, which
+dry-runs as the app and saves nothing. With a model set, a first-party query
+reads `analytics_events` from the model only when its WHERE filters
+`event_name` to named events (`= 'x'` or `IN (...)`, ANDed, no OR or NOT),
+because the model has no `http.response` rows; its result carries
+`eventsSource` and `sourceGeneration` (the model build it read). Unfiltered
+queries, `SELECT *`, and queries that name `public_key_id` or `context`, read
+`http.response`, or read `properties` other than through `JSON_VALUE`,
+`JSON_EXTRACT_SCALAR`, `JSON_VALUE_ARRAY`, or `JSON_EXTRACT_STRING_ARRAY` stay
+on the raw table, as do alerts and onboarding journeys;
+`eventsSource.modelSkipped` says why. A model result trails the newest events
+by up to one rebuild, so for the last few minutes give the model's age from
+`get-analytics-source-generation` (a metadata read, no query) rather than
+calling the count complete.
+
 Example pageviews query for a local calendar day:
 
 ```sql

package/corpus/templates/analytics/CHANGELOG.md

@@ -3,10 +3,51 @@
 All notable user-facing changes to Agent-Native Analytics are documented here. Open it any
 time from the command menu (Cmd+K → "What's new") or from Settings.
 
+## 2026-10-19
+
+### Fixed
+
+- Dashboard upgrades preserve saved history, custom data sources, and legacy edits.
+- The agent sees the row breakdown open in your current browser tab.
+
+### Changed
+
+- Apps no longer keep server functions and databases warm by default; set `AGENT_NATIVE_ENABLE_KEEP_WARM=1` to opt in.
+
+## 2026-10-17
+
+### Added
+
+- Dashboard descriptions and custom blocks now open safe Markdown links in a new tab
+
+### Improved
+
+- Analytics distinguishes email-domain filters from creator self-view exclusions
+- Analytics validates explicit day-first date ranges before querying dbt metrics
+- Keyboard chart point lists show every visible metric with localized dates and values
+
+### Fixed
+
+- Failed chart drilldowns no longer allow exporting stale cached rows
+- Keep chart-point pagination stable and preserve aggregate result columns
+- Keyboard chart controls now describe the chart points they open
+
 ## 2026-10-16
 
+### Added
+
+- Click a table row to see its numbers broken down by app, or another column, in a side panel.
+- Connect a personal Sigma account to import its dashboards
+- First-party charts can read a scheduled warehouse events model instead of the raw event table, so repeat loads reuse BigQuery's cache between model rebuilds.
+
 ### Improved
 
+- Analytics preserves requested organization grain and guides supported ratio query retries
+- Charts that compute their window from today's date can now reuse BigQuery's cached results within the day instead of rerunning the full query on every load.
+- Dashboard callouts and descriptions support Markdown links
+- Dashboard filters show your selection immediately while charts update.
+- Dashboard panels can be resized by dragging their edges.
+- Keyboard chart point lists now paginate and show each value
 - Dashboard freshness stays in the title row, with compact update times on wide cards and a clock on narrow cards.
 - Analytics preserves metric breakdowns across continued queries and keeps partial totals clearly labeled.
 - Analytics query errors now explain safe next steps without exposing raw SQL or backend details
@@ -14,6 +55,29 @@ time from the command menu (Cmd+K → "What's new") or from Settings.
 
 ### Fixed
 
+- Alert polls enforce a query byte limit and report evaluations that exceed it as errors.
+- All-time dashboard panels keep their historical label when you edit a title or description
+- Analytics answers owner-defined dbt metrics through the Semantic Layer and say when dbt is not ready, instead of reading warehouse tables as the approved definition.
+- Analytics can now count its own first-party events strictly from Postgres when you rule out BigQuery, and refuses instead of quietly querying BigQuery when the data only lives there
+- Analytics recognizes more natural date range formats, including day-first and same-month shorthand.
+- Chart drilldowns are accessible from the keyboard
+- Clarified dbt setup errors when organization context is unavailable
+- Month and quarter comparisons now stay aligned with their named periods, including requests that use “with”.
+- Dashboard event colors render consistently in email reports
+- Dashboard filters show when navigation temporarily prevents changes and close open menus safely
+- Dashboard panel sizes stay put when multiple edits save together
+- Date-based metric comparisons now honor both requested periods.
+- First-party Analytics health checks bound BigQuery reads and identify recent activity counts.
+- First-party dashboards apply the selected time range earlier to avoid unnecessary BigQuery event scans.
+- Fixed a dashboard crash caused by an invalid panel description.
+- Fixed dashboard panels reverting to stale SQL, repeating query validation while resizing, and lacking a reset to content-based height.
+- Formatted negative numbers stay numeric in CSV exports, and funnel drilldowns remain accessible to screen readers
+- Funnel outcome stages now open drilldown details, and CSV exports preserve negative numeric values.
+- Markdown links in chart descriptions and custom blocks open external pages in a new tab.
+- Organization breakdowns now distinguish a root organization from its individual organizations
+- Ratio recovery preserves fractional results for integer data
+- Resized dashboard panels keep their size through concurrent edits
+- Resizing a dashboard panel keeps its size when other edits are saved.
 - Explorer flags incomplete query results
 - Chart drilldowns preserve the selected series and report lookup or export failures safely.
 - CSV downloads show when results are limited to the first 500 records
@@ -21,6 +85,10 @@ time from the command menu (Cmd+K → "What's new") or from Settings.
 - Normalize typed date literals in first-party BigQuery queries
 - Treat incomplete schema and truncated BigQuery results as partial evidence
 
+### Changed
+
+- Built-in dashboards stay read-only and update with each release; Duplicate to customize makes your own editable copy
+
 ## 2026-10-15
 
 ### Added
@@ -33,6 +101,7 @@ time from the command menu (Cmd+K → "What's new") or from Settings.
 
 ### Improved
 
+- Collapsed Analytics navigation icons stay centered when the list is short
 - Active-user answers distinguish Builder product activity from Agent-Native app opens, and dbt metric follow-ups keep their original filters.
 - Analytics keeps ambiguous active-user questions open across product activity and membership sources, and validates dbt metric date ranges before reporting results
 - Analytics keeps ambiguous active-user searches open across Builder activity, organization membership, and app opens until you choose the population.
@@ -47,6 +116,7 @@ time from the command menu (Cmd+K → "What's new") or from Settings.
 
 ### Fixed
 
+- Collapsed navigation icons stay centered in the Analytics sidebar
 - Dashboard query costs and refresh confirmations reflect actual execution, and disconnected sources clear saved rows
 - Dashboard results disappear when access is withdrawn, and Explorer query costs exclude cached scans
 - Analytics now distinguishes empty and partial dbt metric results from complete answers.
@@ -264,6 +334,7 @@ time from the command menu (Cmd+K → "What's new") or from Settings.
 
 ### Improved
 
+- AI tools connected over MCP now get a checked result format for the analytics health check and the connected database tables list
 - Session replays now show the date and time the session started, and the Sessions list shows start times in a shorter, easier-to-scan format.
 - Agent dashboard edits are now checked against the live chart before they save, so the agent no longer reports a chart change that did not happen.
 

package/corpus/templates/analytics/actions/configure-first-party-events-model.ts

@@ -0,0 +1,161 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { dryRunQuerySchema } from "../server/lib/bigquery.js";
+import { requireAnalyticsAdminContext } from "../server/lib/db-admin-connections.js";
+import {
+  firstPartyEventsModelProjection,
+  getFirstPartyAnalyticsBackend,
+  saveFirstPartyEventsModelTable,
+} from "../server/lib/first-party-analytics-backend.js";
+import { resolveSourceGeneration } from "../server/lib/source-generation.js";
+
+const TABLE_ID = /^[a-z][a-z0-9-]{4,61}[a-z0-9]\.[A-Za-z_]\w*\.[A-Za-z_]\w*$/;
+
+type ModelCheck =
+  | {
+      status: "ok";
+      table: string;
+      modifiedAt: string;
+      ageMs: number;
+      stale: boolean;
+      recentDayBytes: number | null;
+      fullScanBytes: number | null;
+    }
+  | { status: "unavailable"; table: string; reason: string; message?: string };
+
+function utcDateDaysAgo(days: number): string {
+  return new Date(Date.now() - days * 86_400_000).toISOString().slice(0, 10);
+}
+
+// Dry runs only: BigQuery plans the query and reports the bytes it would
+// scan, but runs and bills nothing.
+async function checkModel(
+  table: string,
+  signal?: AbortSignal,
+): Promise<ModelCheck> {
+  const generation = await resolveSourceGeneration([table], {
+    force: true,
+    signal,
+  });
+  if (generation.status === "unavailable") {
+    return { status: "unavailable", table, reason: generation.reason };
+  }
+  const projection = `(${firstPartyEventsModelProjection(table)}) AS analytics_events`;
+  const recent = await dryRunQuerySchema(
+    `SELECT COUNT(*) AS events FROM ${projection} WHERE event_date >= DATE '${utcDateDaysAgo(1)}'`,
+    { signal },
+  );
+  if (recent.error) {
+    return {
+      status: "unavailable",
+      table,
+      reason: "query_denied",
+      message: recent.error,
+    };
+  }
+  // Eligible chart SQL need not bound event_date, so a model that refuses an
+  // unbounded read (a required partition filter, say) would fail those charts.
+  const full = await dryRunQuerySchema(
+    `SELECT COUNT(*) AS events FROM ${projection}`,
+    { signal },
+  );
+  if (full.error) {
+    return {
+      status: "unavailable",
+      table,
+      reason: "full_read_denied",
+      message: full.error,
+    };
+  }
+  return {
+    status: "ok",
+    table,
+    modifiedAt: generation.oldestModifiedAt,
+    ageMs: generation.ageMs,
+    stale: generation.stale,
+    recentDayBytes: recent.totalBytesProcessed ?? null,
+    fullScanBytes: full.totalBytesProcessed ?? null,
+  };
+}
+
+export default defineAction({
+  // set and clear replace the org-wide model every first-party chart reads.
+  mcpAnnotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  description:
+    "Check or set the warehouse events model that first-party Analytics charts read instead of the raw event table. `check` (any org member) reads the model's table metadata and dry-runs the chart projection against it as the app, reporting whether the app can query it and the bytes a one-day and a full read would scan; it runs and bills no query. `set` (org admin, needs approval) runs the same check and saves the model only if it passes. `clear` (org admin, needs approval) sends charts back to the raw table. Charts that read columns or events the model lacks, alerts, and onboarding journeys keep reading the raw table either way.",
+  schema: z.object({
+    mode: z.enum(["check", "set", "clear"]),
+    table: z
+      .string()
+      .trim()
+      .optional()
+      .describe(
+        "Model table as project.dataset.table. Required for set; check defaults to the configured model.",
+      ),
+  }),
+  needsApproval: ({ mode }) => mode !== "check",
+  run: async ({ mode, table }, context) => {
+    const userEmail = getRequestUserEmail();
+    if (!userEmail) {
+      fail("Sign in to configure the Analytics model", {
+        errorCode: "unauthenticated",
+        statusCode: 401,
+      });
+    }
+    const orgId = getRequestOrgId();
+    if (!orgId) {
+      fail("An active organization is required to configure the model", {
+        errorCode: "organization_required",
+        statusCode: 403,
+      });
+    }
+    const signal = context?.signal;
+    const scope =
+      mode === "check"
+        ? { userEmail, orgId }
+        : await requireAnalyticsAdminContext({ userEmail, orgId });
+
+    if (mode === "clear") {
+      await saveFirstPartyEventsModelTable(scope, null);
+      return { status: "cleared" as const };
+    }
+
+    const target =
+      table ||
+      (mode === "check"
+        ? (await getFirstPartyAnalyticsBackend(scope, signal)).modelTable
+        : null);
+    if (!target) {
+      fail("Name the model table as project.dataset.table", {
+        errorCode: "model_table_required",
+        statusCode: 400,
+      });
+    }
+    if (!TABLE_ID.test(target)) {
+      fail("The model table must be project.dataset.table", {
+        errorCode: "invalid_model_table",
+        statusCode: 400,
+      });
+    }
+
+    const check = await checkModel(target, signal);
+    if (mode === "check") return check;
+    if (check.status !== "ok") {
+      fail(
+        `The app cannot read ${target} (${check.reason}); the model was not saved`,
+        { errorCode: "model_unreadable", statusCode: 424 },
+      );
+    }
+    await saveFirstPartyEventsModelTable(scope, target);
+    return { ...check, status: "saved" as const };
+  },
+});

package/corpus/templates/analytics/actions/get-first-party-analytics-backend.ts

@@ -0,0 +1,59 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getFirstPartyAnalyticsBackend } from "../server/lib/first-party-analytics-backend.js";
+import { firstPartyAnalyticsTableBackends } from "../server/lib/first-party-analytics.js";
+
+const queryBackendSchema = z.enum(["postgres", "bigquery"]);
+
+export default defineAction({
+  description:
+    "Report where first-party Analytics queries run for the current user/org, read from its stored backend setting; it never queries BigQuery or any warehouse. Returns `sink` (`postgres`; `dual`, which also writes to BigQuery but reads Postgres; or `bigquery`) and `tables`, the backend each query-agent-native-analytics table is read from. `setting` is `absent` (the Postgres default), `recognized`, or `unrecognized`: a stored value that is not a known backend, which also routes to Postgres; report that the setting needs fixing. Fails with errorCode first_party_backend_unreadable when the setting cannot be read; that is unknown, not Postgres.",
+  schema: z.object({}),
+  outputSchema: z.object({
+    sink: z.enum(["postgres", "dual", "bigquery"]),
+    setting: z.enum(["absent", "recognized", "unrecognized"]),
+    tables: z.object({
+      analytics_events: queryBackendSchema,
+      analytics_event_daily_rollups: queryBackendSchema,
+      analytics_user_days: queryBackendSchema,
+      session_recordings: queryBackendSchema,
+    }),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async () => {
+    const userEmail = getRequestUserEmail();
+    if (!userEmail) {
+      fail("no authenticated user", {
+        errorCode: "unauthenticated",
+        statusCode: 401,
+      });
+    }
+    let backend: Awaited<ReturnType<typeof getFirstPartyAnalyticsBackend>>;
+    try {
+      backend = await getFirstPartyAnalyticsBackend({
+        userEmail,
+        orgId: getRequestOrgId() || null,
+      });
+    } catch (error) {
+      console.warn("[first-party-analytics] Backend setting unreadable:", {
+        errorType: error instanceof Error ? error.name : "non_error",
+      });
+      fail(
+        "Could not read this scope's first-party analytics backend setting, so it is unknown whether queries would run on Postgres or BigQuery. Do not assume Postgres; retry later.",
+        { errorCode: "first_party_backend_unreadable", statusCode: 503 },
+      );
+    }
+    return {
+      sink: backend.sink,
+      setting: backend.sinkSetting,
+      tables: firstPartyAnalyticsTableBackends(backend.sink),
+    };
+  },
+});

package/corpus/templates/analytics/actions/get-first-party-analytics-health.ts

@@ -92,7 +92,7 @@ const healthSchema = z.object({
 
 export default defineAction({
   description:
-    "Check first-party Analytics source health before a large or historical query. Returns query pressure, delivery health, and external backend recommendations. Neon/Postgres reads compact all-time daily rollups; BigQuery reads at most the last 30 UTC calendar days (including today) with a small billed-byte cap. BigQuery eventCount, dailyRollupRows, and lastEventDate cover only the dates in metrics.coverage (kind recent_window), while all-time firstEventDate and spanDays are null with an explicit reason. A cap failure returns unavailable coverage, null event metrics, and reason maximum_bytes_billed. Both sinks read the small query-pressure ledger. For Neon/Postgres, event volume or query pressure can recommend BigQuery; for an existing BigQuery sink, only query pressure or delivery lag can produce monitor. A pending delivery-queue migration is reported as degraded delivery health. External options include BigQuery for warehouse SQL and history and Amplitude for product analytics, with safe setup links. Connecting a backend does not reroute /track or backfill existing events.",
+    "Check first-party Analytics source health before a large or historical query. Returns query pressure, delivery health, and external backend recommendations. Neon/Postgres reads compact all-time daily rollups; BigQuery reads at most the last 30 UTC calendar days (including today) with a small billed-byte cap. BigQuery eventCount, dailyRollupRows, and lastEventDate cover only the dates in metrics.coverage (kind recent_window), while all-time firstEventDate and spanDays are null with an explicit reason. A cap failure returns unavailable coverage, null event metrics, and reason maximum_bytes_billed. Both sinks read the small query-pressure ledger. To learn only where queries run, without querying BigQuery, call get-first-party-analytics-backend. For Neon/Postgres, event volume or query pressure can recommend BigQuery; for an existing BigQuery sink, only query pressure or delivery lag can produce monitor. A pending delivery-queue migration is reported as degraded delivery health. External options include BigQuery for warehouse SQL and history and Amplitude for product analytics, with safe setup links. Connecting a backend does not reroute /track or backfill existing events.",
   schema: z.object({}),
   outputSchema: healthSchema,
   outputErrorStrategy: "strict",

package/corpus/templates/analytics/actions/list-event-catalog.ts

@@ -49,7 +49,7 @@ async function dataDictionaryDescriptions(
 
 export default defineAction({
   description:
-    "List the events Analytics has received, with each event's app, volume in the range, last-seen time, sample property keys, and Data Dictionary description. Flags apps that send only automatic events and events that stopped firing. Keeps the 1,000 most recently seen events, sorted by volume, and sets truncated when more exist; app flags still count every event in the range. Reads Analytics' own index. Requires the Sessions triage Lab.",
+    "List the events Analytics has received, with each event's app, volume in the range, last-seen time, sample property keys, and Data Dictionary description. Flags apps that send only automatic events and events that stopped firing. Keeps the 1,000 most recently seen events, sorted by volume, and sets truncated when more exist; app flags still count every event in the range. Reads Analytics' own index; Postgres-only, never queries BigQuery. Requires the Sessions triage Lab.",
   schema: z.object({
     from: sessionEventBoundSchema
       .optional()

package/corpus/templates/analytics/actions/list-session-event-names.ts

@@ -11,7 +11,7 @@ import { sessionEventBoundSchema } from "../shared/session-events.js";
 
 export default defineAction({
   description:
-    "List event names tracked in Analytics sessions with the number of sessions that tracked each, for building did/didn't event filters on list-session-recordings. Reads Analytics' own session event index. Requires the Sessions triage Lab.",
+    "List event names tracked in Analytics sessions with the number of sessions that tracked each, for building did/didn't event filters on list-session-recordings. Reads Analytics' own session event index; Postgres-only, never queries BigQuery. Requires the Sessions triage Lab.",
   schema: z.object({
     from: sessionEventBoundSchema
       .optional()

package/corpus/templates/analytics/actions/list-session-recordings.ts

@@ -42,7 +42,7 @@ async function withFriction(
 
 export default defineAction({
   description:
-    "List first-party Analytics session replay recordings accessible to the current user/org. `visitorType: anonymous` explicitly includes playable recordings with no signed-in user id and a non-empty client-supplied anonymous id; it does not verify the page origin or a person's identity. Returns summaries only, not raw replay chunks.",
+    "List first-party Analytics session replay recordings accessible to the current user/org. `visitorType: anonymous` explicitly includes playable recordings with no signed-in user id and a non-empty client-supplied anonymous id; it does not verify the page origin or a person's identity. Returns summaries only, not raw replay chunks. Postgres-only; never queries BigQuery.",
   schema: z.object({
     query: z
       .string()

package/corpus/templates/analytics/actions/query-agent-native-analytics.ts

@@ -1,5 +1,5 @@
 import { dataTableWidgetResultSchema, defineAction } from "@agent-native/core";
-import type { ActionRunContext } from "@agent-native/core/action";
+import { fail, type ActionRunContext } from "@agent-native/core/action";
 import { createDataTableWidgetResult } from "@agent-native/core/data-widgets";
 import {
   getRequestOrgId,
@@ -9,7 +9,11 @@ import { track } from "@agent-native/core/tracking";
 import { z } from "zod";
 
 import { FirstPartyAnalyticsValidationError } from "../server/lib/first-party-analytics-errors.js";
-import { queryFirstPartyAnalytics } from "../server/lib/first-party-analytics.js";
+import {
+  FirstPartyAnalyticsBackendNotPostgresError,
+  queryFirstPartyAnalyticsWithBackend,
+  type FirstPartyAnalyticsQueryResultWithBackend,
+} from "../server/lib/first-party-analytics.js";
 import {
   ANALYTICS_ANALYSIS_RESULT_RENDERER,
   getSingleNumericAnalysisResult,
@@ -21,11 +25,7 @@ function resolveScope() {
   return { userEmail, orgId: getRequestOrgId() || null };
 }
 
-function toDataTableResult(result: {
-  rows: Record<string, unknown>[];
-  schema: { name: string; type: string }[];
-  truncated?: boolean;
-}) {
+function toDataTableResult(result: FirstPartyAnalyticsQueryResultWithBackend) {
   const numericTypes = new Set([
     "number",
     "integer",
@@ -48,6 +48,7 @@ function toDataTableResult(result: {
       rows: result.rows,
       ...(result.truncated ? { truncated: true } : {}),
     },
+    backend: result.backend,
   });
 }
 
@@ -72,6 +73,7 @@ type QueryFailureClass =
   | "quota_exceeded"
   | "rate_limited"
   | "backend_error"
+  | "backend_not_postgres"
   | "timeout"
   | "query_error"
   | "unknown";
@@ -99,7 +101,7 @@ type QueryFailure = {
 };
 
 const QUERY_FAILURES: Record<
-  Exclude<QueryFailureClass, "unknown">,
+  Exclude<QueryFailureClass, "unknown" | "backend_not_postgres">,
   QueryFailure
 > = {
   unsupported_sql: {
@@ -314,9 +316,9 @@ function safeCancellationError(): Error {
 
 export default defineAction({
   description:
-    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track), compact daily rollups updated transactionally with new ingest, identifiable user-day rollups, and session replay summaries. It needs no external provider connection. Use it for app/site traffic, product events, template/app usage, conversions, session recordings, and LLM/agent observability (event_name = '$ai_generation': model cost, tokens, latency); use the BigQuery, GA4, Mixpanel, PostHog, or Amplitude actions when the user asks for those or the data lives there. " +
-    "SQL may read analytics_events, analytics_event_daily_rollups, analytics_user_days, and session_recordings; session_replay_chunks is unavailable. Reads are scoped to the current user/org and exclude test identities (QA/E2E) unless includeTestIdentities is true. Prefer analytics_event_daily_rollups for event counts and analytics_user_days for active-user or retention questions. On the Builder.io production organization after the explicit BigQuery cutover, events and rollups read from BigQuery while session_recordings stays in the SQL store; cross-backend joins are not supported. The BigQuery path translates a restricted PostgreSQL-compatible SQL subset: extract event properties with `properties::jsonb ->> 'key'`; bare JSON operators, LATERAL/unnest/generate_series, FILTER (WHERE ...), DISTINCT ON, and ILIKE are unsupported. Use `||` explicitly between strings. Do not call DIV(); the first-party SQL function policy rejects it. For ratios, use `CAST(numerator AS NUMERIC) / NULLIF(denominator, 0)` to avoid integer truncation. " +
-    "On query errors, follow the typed recovery instruction: rewrite unsupported or invalid SQL once, check schema for a missing source, narrow a billed-byte-limit query, retry only timeouts/rate limits/temporary backend errors once, and stop on permission or unclassified errors. Never repeat unchanged SQL after a non-retryable failure. Before a large or historical query, call get-first-party-analytics-health. Aggregate, project only needed columns, use bounded recent drill-downs, and add a LIMIT for raw or high-cardinality reads; an explicit all-time or lifetime request remains all-time. Safe scoped results are cached for up to five minutes. " +
+    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track), daily rollups updated transactionally with new ingest, identifiable user-day rollups, and session replay summaries. Use it for app/site traffic, product events, template/app usage, conversions, session recordings, and LLM/agent observability (event_name = '$ai_generation': model cost, tokens, latency); use the BigQuery, GA4, Mixpanel, PostHog, or Amplitude actions when the user asks for those or the data lives there. " +
+    "SQL may read analytics_events, analytics_event_daily_rollups, analytics_user_days, and session_recordings; session_replay_chunks is unavailable. Reads are scoped to the current user/org. Prefer analytics_event_daily_rollups for event counts and analytics_user_days for active-user or retention questions. After the explicit BigQuery cutover, events and rollups read from BigQuery while session_recordings stays in Postgres; cross-backend joins are not supported. " +
+    "Do not call DIV(); for ratios use CAST(numerator AS NUMERIC) / NULLIF(denominator, 0). Extract properties with properties::jsonb ->> 'key'; LATERAL/unnest/generate_series are unsupported. Use `||` explicitly between strings. On errors, follow typed recovery instructions and never repeat non-retryable SQL unchanged. If the user rules out BigQuery, skip get-first-party-analytics-health; otherwise call it before large or historical queries. Aggregate, project only needed columns, use bounded recent drill-downs, and add a LIMIT for raw or high-cardinality reads; an explicit all-time or lifetime request remains all-time. " +
     "Columns. analytics_events: event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, context. analytics_event_daily_rollups: tenant_key, owner_email, org_id, event_date, event_name, app, template, event_count. analytics_user_days: tenant_key, owner_email, org_id, event_date, user_key. session_recordings: id, session_id, user_id, anonymous_id, user_key, started_at, ended_at, duration_ms, chunk_count, event_count, page_count, error_count, rage_click_count, app, template, status, first_url, last_url, path, hostname, referrer, metadata. " +
     "The data-querying skill lists the `$ai_generation` properties and backend routing.",
   schema: z.object({
@@ -337,6 +339,12 @@ export default defineAction({
       .describe(
         "Set true only when the user explicitly asks to see the query rows as a table.",
       ),
+    backend: z
+      .enum(["postgres"])
+      .optional()
+      .describe(
+        'Set "postgres" when the user rules out BigQuery; skip get-first-party-analytics-health then. BigQuery-only queries fail with first_party_backend_not_postgres.',
+      ),
   }),
   outputSchema: z.union([
     dataTableWidgetResultSchema,
@@ -344,6 +352,7 @@ export default defineAction({
       rows: z.array(z.record(z.string(), z.unknown())),
       schema: z.array(z.object({ name: z.string(), type: z.string() })),
       truncated: z.boolean().optional(),
+      backend: z.enum(["postgres", "bigquery"]),
     }),
   ]),
   chatUI: {
@@ -370,11 +379,12 @@ export default defineAction({
       },
       actionContext,
     );
-    let result: Awaited<ReturnType<typeof queryFirstPartyAnalytics>>;
+    let result: FirstPartyAnalyticsQueryResultWithBackend;
     try {
-      result = await queryFirstPartyAnalytics(args.sql, scope, {
+      result = await queryFirstPartyAnalyticsWithBackend(args.sql, scope, {
         cache: true,
         includeTestIdentities: args.includeTestIdentities === true,
+        ...(args.backend ? { requireBackend: args.backend } : {}),
         ...(actionContext?.signal ? { signal: actionContext.signal } : {}),
       });
     } catch (error) {
@@ -398,8 +408,14 @@ export default defineAction({
         }
         throw safeCancellationError();
       }
-
-      const failure = queryFailure(error);
+      const failure: QueryFailure =
+        error instanceof FirstPartyAnalyticsBackendNotPostgresError
+          ? {
+              failureClass: "backend_not_postgres",
+              recovery: "stop",
+              message: error.message,
+            }
+          : queryFailure(error);
       try {
         track(
           "query_failed",
@@ -418,6 +434,12 @@ export default defineAction({
       } catch {
         // Telemetry is best-effort and must not replace the safe query error.
       }
+      if (error instanceof FirstPartyAnalyticsBackendNotPostgresError) {
+        fail(error.message, {
+          errorCode: error.code,
+          details: { bigQueryTables: error.bigQueryTables },
+        });
+      }
       throw new FirstPartyAnalyticsActionQueryError(failure);
     }
     track(

package/corpus/templates/analytics/app/i18n/en-US.ts

@@ -2114,10 +2114,6 @@ export default {
     noMatches: "No definitions match your search.",
     searchPlaceholder: "Search definitions",
     sourceIndex: "Source index",
-    statusApproved: "Approved",
-    statusSuggested: "Suggested",
-    statusUnreviewed: "Unreviewed",
-    unsourced: "No source",
   },
   indexPanel: {
     presetDaily: "Daily at 06:00",