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

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 12945
+- 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

@@ -110,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/changelog/2026-10-16-first-party-charts-can-read-a-scheduled-warehouse-events-mod.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-10-16
+---
+
+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.

package/corpus/templates/analytics/server/lib/analytics-alerts.ts

@@ -153,6 +153,13 @@ const DEFAULT_AGENT_CHAT_STUCK_ALERT_WINDOW_MINUTES = 10;
 const DEFAULT_AGENT_CHAT_STUCK_ALERT_COOLDOWN_MINUTES = 60;
 const DEFAULT_ALERT_SCOPE_PAGE_SIZE = 500;
 const BIGQUERY_ALERT_PAGE_SIZE = 5_000;
+
+// Alerts watch the last few minutes, which an hourly events model has not
+// built yet.
+const ALERT_QUERY_OPTIONS = {
+  eventsSource: "raw",
+  maxBytesBilled: ANALYTICS_ALERT_MAX_BYTES_BILLED,
+} as const;
 const ALERT_RULE_DEFAULTS_KEY = "analytics-alert-rule-defaults";
 
 function safeJsonParse<T>(raw: unknown, fallback: T): T {
@@ -1178,7 +1185,7 @@ export async function evaluateBigQueryAnalyticsAlertBatch(
       queryFirstPartyAnalytics(
         query,
         { userEmail: first.ownerEmail, orgId: first.orgId },
-        { maxBytesBilled: ANALYTICS_ALERT_MAX_BYTES_BILLED },
+        ALERT_QUERY_OPTIONS,
       ),
   );
   if (result.truncated || result.rows.length !== 1) {
@@ -1543,7 +1550,7 @@ async function loadCandidateEvents(
           const result = await queryFirstPartyAnalytics(
             buildBigQueryAlertQuery(rule, windowStart, windowEnd, cursor),
             { userEmail: rule.ownerEmail, orgId: rule.orgId },
-            { maxBytesBilled: ANALYTICS_ALERT_MAX_BYTES_BILLED },
+            ALERT_QUERY_OPTIONS,
           );
           if (result.truncated) {
             throw new Error(