@agent-native/core 0.141.6 → 0.144.0

package/corpus/templates/analytics/AGENTS.md

@@ -1,50 +1,41 @@
 # Analytics — Agent Guide
 
-Analytics is an agent-native BI workspace for data sources, queries, dashboards,
-charts, and warehouse integrations. Dashboards are the canonical user-facing
-artifact; legacy analyses remain readable only for compatibility.
+Analytics is an agent-native BI workspace for sources, queries, dashboards,
+charts, and warehouse integrations. Dashboards are canonical; legacy analyses
+remain readable for compatibility.
 
-Use all connected sources and MCP tools; reason over fetched data here, and do
-not suggest another AI tool.
+Use connected sources and MCP tools; reason over fetched data here, not via
+another AI tool.
 
 Prompt cap: 6,000; put detail in `.agents/skills/*`.
 
-Before building common workspace or agent UI, read `agent-native-toolkit`; use
-`customizing-agent-native` for the configure → compose → eject → propose
-ladder.
+Before building common workspace or agent UI, read `agent-native-toolkit` to
+discover existing primitives and patterns. Read `customizing-agent-native`
+before adapting shared UI: configure → compose → eject → propose.
 
 ## How To Answer A Data Question
 
-1. **Search existing work first.** Call `search-analytics-query-catalog` before
-   writing a query. Adapt the closest saved SQL to the requested filters and
-   window, run it once, and stop.
-2. **One bounded call.** List, filter, count, and cohort questions ("which X,
-   excluding Y") are a single SQL statement, or one `run-code` script that
-   filters server-side. Never page through a cohort or fan out per item to apply
-   a filter.
-3. **Escalate only on a miss.** If the catalog returns nothing usable, make at
-   most one discovery pass (`list-data-dictionary`, `search-bigquery-schema`,
-   `data-source-status`), then query. Don't cross-check or add breakdowns
-   nobody asked for.
-4. **Answer in chat.** Give the result directly with a short table or inline
-   chart — never deflect to "check the dashboard." Keep native data widgets to
-   already-summarized data (≤50 rows); above that, state the total and show the
-   top rows.
-5. **Deliver exports in chat.** See `analysis-workspace`; never return only a
-   path or tell the user to find a download elsewhere.
-6. **Chunk only for reading.** Group into 5-10 with per-item notes only when 30+
-   items each need qualitative reading no query can do (call transcripts, ticket
-   threads). Chunking a question a query could answer is the most expensive
-   mistake available here. See `adhoc-analysis`.
+1. **Search existing work first.** Call `search-analytics-query-catalog`, adapt
+   the closest saved SQL to the requested filters/window, run it once, and stop.
+2. **One bounded call.** List/filter/count/cohort questions are one SQL statement
+   or one server-side `run-code` script; never page or fan out per item.
+3. **Escalate on a miss.** If the catalog has no usable result, make one discovery
+   pass (`list-data-dictionary`, `search-bigquery-schema`, `data-source-status`),
+   then query; don't cross-check or add unasked breakdowns.
+4. **Answer in chat.** Return a short table or inline chart, not a dashboard
+   pointer. Native widgets show summarized data (≤50 rows); above that, state the
+   total and top rows.
+5. **Deliver exports in chat.** See `analysis-workspace`; don't return only a path.
+6. **Chunk only reading.** Group 5-10 only for 30+ qualitative items when a query
+   cannot answer; don't chunk queryable questions. See `adhoc-analysis`.
 
 ## Core Rules
 
-- A sibling app asking over A2A sends a question or shaped input, never SQL. It
-  lacks this app's schema, data dictionary, dashboards, and dialect knowledge,
-  so raw-query actions (`sql`, `code`, `script`, `expression`) are not
-  sibling-invocable. Prefer natural-language delegation so this app retains its
-  instructions, source selection, and tools. Shaped reads are stable contracts,
-  not workarounds for delegation; this app still owns the query.
+- A sibling app asking over A2A sends a question or shaped input, never SQL.
+  Raw-query actions (`sql`, `code`, `script`, `expression`) are not
+  sibling-invocable because this app owns schema, source selection, and tools.
+  Prefer natural-language delegation; shaped reads are stable contracts, not
+  delegation workarounds.
 - For open-ended delegated requests, choose a safe default and label partial.
 - Data integrity first. Never invent numbers, dimensions, filters, or source
   semantics; only present values you actually retrieved, and state uncertainty.
@@ -54,9 +45,15 @@ ladder.
   access checks with raw SQL for ownable resources.
 - Provider actions are bounded shortcuts, not limits. For broad or
   absence-sensitive Gong work, stage raw API data and use
-  `query-staged-dataset` or a Data Program; if raw transcript bodies are
-  required, use `provider-corpus-job`. See `provider-api`, `data-programs`, and
-  `gong`.
+  `query-staged-dataset` or a Data Program; use `provider-corpus-job` for raw
+  transcript bodies. See `provider-api`, `data-programs`, and `gong`.
+- Custom APIs use the `provider-api-register` action for public HTTPS provider
+  metadata and `test-custom-api-connection` for bounded GET previews. Store
+  credential values in Settings, pass only key names to provider actions, and
+  hand successful endpoint tests to `save-data-program` for refreshable panels.
+- Hosted Analytics cannot reach localhost or private network APIs. Use a
+  deployed HTTPS endpoint or an explicitly supported secure tunnel; never
+  weaken the provider runtime's SSRF boundary.
 - Create dashboards, panels, or saved artifacts only when explicitly asked;
   suggest and wait otherwise. Scope them to the question, avoid decorative
   metrics, and never modify existing dashboards without a directive.
@@ -81,7 +78,7 @@ ladder.
 ## Application State
 
 - `navigation` exposes the current dashboard, analysis, source, chart, and
-  selection. `navigate` moves the user, including `view="catalog"`,
+  selection. `navigate` moves the user between supported Analytics surfaces,
   `"sessions"`, `"monitoring"`, and `"agents"`. Use `view-screen` when the
   active context is unclear.
 - Clicking a panel stages it as a chat context chip and writes `selected-object`
@@ -97,7 +94,7 @@ Read the relevant skill before deeper work:
 - `cross-source-analysis` for questions spanning sources (identity stitching,
   de-duplication).
 - `dashboard-management` for dashboard/panel storage, layout, extensions,
-  mutation, sharing, and the template catalog.
+  mutation and sharing.
 - `adhoc-analysis` and `analysis-workspace` for one-off answers and large
   multi-source work.
 - `provider-api` and `data-programs` for the escape hatch and durable,

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

@@ -29,7 +29,7 @@ import {
 
 /**
  * Push the saved config through the collab layer so open dashboard editors get
- * the change in real time (mirrors update-dashboard / install-dashboard-template).
+ * the change in real time (mirrors update-dashboard).
  */
 async function syncToCollab(
   dashboardId: string,

package/corpus/templates/analytics/actions/ensure-native-v2-dashboards.ts

@@ -235,7 +235,7 @@ export async function ensureNativeV2Dashboards(
 
 export default defineAction({
   description:
-    "Provision the four reusable native Analytics v2 dashboard patterns for the active organization from explicit Data Program bindings. " +
+    "Provision the reusable native Analytics v2 dashboard patterns, including On Demand Billing, for the active organization from explicit Data Program bindings. " +
     "This is an admin-only post-deploy action: it validates every program exists and exposes the manifest's required output columns, shares the bound programs with the organization, creates deterministic native-* dashboard copies, and never changes the legacy extension dashboards. " +
     "Re-running preserves existing v2 dashboard edits unless overwrite=true.",
   schema: z.object({

package/corpus/templates/analytics/actions/list-dashboard-usage-stats.ts

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core/action";
+import { isPostgres } from "@agent-native/core/db";
 import { buildDeepLink } from "@agent-native/core/server";
 import { and, eq, isNull, like, or, sql } from "drizzle-orm";
 import { z } from "zod";
@@ -40,24 +41,8 @@ function toNumber(value: unknown): number {
   return 0;
 }
 
-function parseConfig(value: unknown): Record<string, unknown> {
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    return value as Record<string, unknown>;
-  }
-  if (typeof value !== "string") return {};
-  try {
-    const parsed = JSON.parse(value);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? parsed
-      : {};
-  } catch {
-    return {};
-  }
-}
-
-function dashboardName(row: { title: string; config: unknown }): string {
-  const config = parseConfig(row.config);
-  const configName = config.name;
+function dashboardName(row: { title: string; configName: unknown }): string {
+  const configName = row.configName;
   if (typeof configName === "string" && configName.trim()) {
     return configName.trim();
   }
@@ -66,11 +51,10 @@ function dashboardName(row: { title: string; config: unknown }): string {
 
 function dashboardPanelCount(row: {
   kind: string;
-  config: unknown;
+  panelCount: unknown;
 }): number | null {
   if (row.kind !== "sql") return null;
-  const panels = parseConfig(row.config).panels;
-  return Array.isArray(panels) ? panels.length : 0;
+  return toNumber(row.panelCount);
 }
 
 export function dashboardIdFromPath(path: string | null): string | null {
@@ -143,6 +127,16 @@ export default defineAction({
   run: async (_args, ctx) => {
     const admin = await requireDbAdminContextFromRequest(ctx);
     const db = getDb() as any;
+    const configName = isPostgres()
+      ? sql<string | null>`(${schema.dashboards.config}::jsonb ->> 'name')`
+      : sql<string | null>`json_extract(${schema.dashboards.config}, '$.name')`;
+    const panelCount = isPostgres()
+      ? sql<
+          number | null
+        >`CASE WHEN ${schema.dashboards.kind} = 'sql' AND jsonb_typeof(${schema.dashboards.config}::jsonb -> 'panels') = 'array' THEN jsonb_array_length(${schema.dashboards.config}::jsonb -> 'panels') ELSE 0 END`
+      : sql<
+          number | null
+        >`CASE WHEN ${schema.dashboards.kind} = 'sql' AND json_type(json_extract(${schema.dashboards.config}, '$.panels')) = 'array' THEN json_array_length(json_extract(${schema.dashboards.config}, '$.panels')) ELSE 0 END`;
 
     // guard:allow-unscoped — org owner/admin audit intentionally spans all
     // dashboard rows in the active org after requireDbAdminContextFromRequest.
@@ -151,7 +145,8 @@ export default defineAction({
         id: schema.dashboards.id,
         kind: schema.dashboards.kind,
         title: schema.dashboards.title,
-        config: schema.dashboards.config,
+        configName,
+        panelCount,
         ownerEmail: schema.dashboards.ownerEmail,
         visibility: schema.dashboards.visibility,
         createdAt: schema.dashboards.createdAt,

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

@@ -0,0 +1,135 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { requireAnalyticsAdminContext } from "../server/lib/db-admin-connections.js";
+import {
+  assertFirstPartyAnalyticsBigQueryReady,
+  backfillFirstPartyAnalyticsBatch,
+  getFirstPartyAnalyticsBackend,
+  saveFirstPartyAnalyticsBackend,
+} from "../server/lib/first-party-analytics-backend.js";
+
+async function resolveScope() {
+  const userEmail = getRequestUserEmail();
+  if (!userEmail) throw new Error("no authenticated user");
+  const orgId = getRequestOrgId();
+  if (!orgId) {
+    throw new Error(
+      "An active organization is required for the first-party Analytics migration.",
+    );
+  }
+  const admin = await requireAnalyticsAdminContext({ userEmail, orgId });
+  return { userEmail: admin.userEmail, orgId: admin.orgId };
+}
+
+const migrationSchema = z.object({
+  mode: z.enum(["status", "prepare", "backfill", "cutover"]),
+  table: z
+    .string()
+    .trim()
+    .optional()
+    .describe(
+      "Optional BigQuery table reference as dataset.table or project.dataset.table. The default is <BIGQUERY_PROJECT_ID>.analytics.first_party_analytics_events_raw.",
+    ),
+  cursor: z.string().trim().optional(),
+  limit: z.number().int().min(1).max(500).optional(),
+  confirm: z.boolean().optional(),
+});
+
+export default defineAction({
+  description:
+    "UI-only production migration for the current Analytics organization. Run prepare to validate the configured BigQuery table and enter dual-write mode, call backfill repeatedly with the returned cursor until complete, then call cutover with confirm=true. 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 analytics 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, cursor, limit, confirm }) => {
+    const scope = await resolveScope();
+    const current = await getFirstPartyAnalyticsBackend(scope);
+    const configuredTable = table ?? current.table;
+
+    if (mode === "status") {
+      const ready =
+        current.sink === "postgres"
+          ? null
+          : await assertFirstPartyAnalyticsBigQueryReady(current.table);
+      return {
+        ...current,
+        ready: Boolean(ready),
+        rowCount: ready?.rowCount ?? null,
+        table: ready?.table.fullyQualified ?? current.table,
+      };
+    }
+
+    if (mode === "prepare") {
+      const ready =
+        await assertFirstPartyAnalyticsBigQueryReady(configuredTable);
+      await saveFirstPartyAnalyticsBackend(scope, {
+        sink: "dual",
+        table: ready.table.fullyQualified,
+        backfillCursor: null,
+        backfillCompleted: false,
+      });
+      return {
+        sink: "dual" as const,
+        table: ready.table.fullyQualified,
+        existingBigQueryRows: ready.rowCount,
+        next: "backfill",
+      };
+    }
+
+    if (mode === "backfill") {
+      if (current.sink !== "dual") {
+        throw new Error(
+          "Prepare the organization for dual-write before starting the BigQuery backfill.",
+        );
+      }
+      const result = await backfillFirstPartyAnalyticsBatch(
+        scope,
+        cursor ?? current.backfillCursor ?? null,
+        limit ?? 500,
+        current.table,
+      );
+      await saveFirstPartyAnalyticsBackend(scope, {
+        sink: "dual",
+        table: current.table,
+        backfillCursor: result.nextCursor,
+        backfillCompleted: result.complete,
+      });
+      return {
+        ...result,
+        sink: "dual" as const,
+        table: current.table,
+        next: result.complete ? "cutover" : "backfill",
+      };
+    }
+
+    if (!confirm) {
+      throw new Error(
+        "Cutover requires confirm=true because it stops first-party event and rollup writes to Postgres for this organization.",
+      );
+    }
+    if (current.sink !== "dual" || current.backfillCompleted !== true) {
+      throw new Error(
+        "Complete the dual-write backfill before cutting over to BigQuery.",
+      );
+    }
+    const ready = await assertFirstPartyAnalyticsBigQueryReady(current.table);
+    await saveFirstPartyAnalyticsBackend(scope, {
+      sink: "bigquery",
+      table: ready.table.fullyQualified,
+      backfillCursor: current.backfillCursor,
+      backfillCompleted: true,
+    });
+    return {
+      sink: "bigquery" as const,
+      table: ready.table.fullyQualified,
+      existingBigQueryRows: ready.rowCount,
+      postgresEventWrites: "stopped",
+      next: "verify dashboards",
+    };
+  },
+});

package/corpus/templates/analytics/actions/navigate.ts

@@ -6,11 +6,10 @@ import {
 } from "@agent-native/core/server";
 import { z } from "zod";
 
-import { listDashboardSummaries } from "../server/lib/dashboards-store";
-
-function normalizeDashboardName(value: string): string {
-  return value.trim().replace(/\s+/g, " ").toLowerCase();
-}
+import {
+  listDashboardSummaries,
+  normalizeDashboardName,
+} from "../server/lib/dashboards-store";
 
 async function resolveDashboardIdByName(name: string): Promise<string> {
   const email = getRequestUserEmail();
@@ -50,7 +49,7 @@ export default defineAction({
       .string()
       .optional()
       .describe(
-        "View to navigate to (ask, adhoc, analyses, extensions, sessions, monitoring, agents, catalog, data-dictionary, data-sources, settings)",
+        "View to navigate to (ask, adhoc, analyses, extensions, sessions, monitoring, agents, data-dictionary, data-sources, settings)",
       ),
     dashboardId: z
       .string()

package/corpus/templates/analytics/actions/provider-api-register.ts

@@ -0,0 +1,50 @@
+import { getDbExec } from "@agent-native/core/db";
+import {
+  createCustomProviderRegistrationAction,
+  CustomProviderRegistrationSchema,
+} from "@agent-native/core/provider-api/actions/custom-provider-registration";
+import { getCredentialContext } from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+async function resolveCallerOrgRole(orgId: string, email: string) {
+  try {
+    const { rows } = await getDbExec().execute({
+      sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
+      args: [orgId, email.toLowerCase()],
+    });
+    const role = (rows[0] as { role?: unknown } | undefined)?.role;
+    return typeof role === "string" && role ? role : null;
+  } catch {
+    return null;
+  }
+}
+
+const schema = CustomProviderRegistrationSchema.superRefine((value, ctx) => {
+  if (value.operation === "upsert" && value.baseUrl) {
+    try {
+      const url = new URL(value.baseUrl);
+      if (url.protocol !== "https:") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["baseUrl"],
+          message: "baseUrl must use public HTTPS.",
+        });
+      }
+    } catch {
+      // The shared schema reports malformed URLs.
+    }
+  }
+});
+
+const action = createCustomProviderRegistrationAction({
+  schema,
+  getContext: getCredentialContext,
+  resolveOrgRole: resolveCallerOrgRole,
+  description:
+    "Register or update an Analytics custom API provider. Stores credential key names only, never secret values. Requires a public HTTPS base URL and owner/admin organization access.",
+});
+
+// The shared factory owns registration, validation, and mutation authorization;
+// this wrapper only adds Analytics' transport contract and base URL policy.
+// Static action registry marker: createCustomProviderRegistrationAction returns defineAction.
+export default { ...action, http: { method: "POST" as const } };

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

@@ -1,4 +1,9 @@
-import { defineAction } from "@agent-native/core";
+import {
+  ACTION_CHAT_UI_DATA_TABLE_RENDERER,
+  dataTableWidgetResultSchema,
+  defineAction,
+} from "@agent-native/core";
+import { createDataTableWidgetResult } from "@agent-native/core/data-widgets";
 import {
   getRequestOrgId,
   getRequestUserEmail,
@@ -13,25 +18,50 @@ function resolveScope() {
   return { userEmail, orgId: getRequestOrgId() || null };
 }
 
+function toDataTableResult(result: {
+  rows: Record<string, unknown>[];
+  schema: { name: string; type: string }[];
+}) {
+  const numericTypes = new Set([
+    "number",
+    "integer",
+    "float",
+    "double",
+    "decimal",
+    "numeric",
+  ]);
+
+  return createDataTableWidgetResult({
+    widgetId: "analytics.query.v1",
+    title: "Analytics query result",
+    table: {
+      title: "Analytics query result",
+      columns: result.schema.map(({ name, type }) => ({
+        key: name,
+        label: name,
+        ...(numericTypes.has(type.toLowerCase()) ? { align: "right" } : {}),
+      })),
+      rows: result.rows,
+    },
+  });
+}
+
 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, identifiable user-day rollups, and session replay summaries recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events, analytics_event_daily_rollups, analytics_user_days, and session_recordings; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. Prefer analytics_event_daily_rollups for event counts and analytics_user_days for active-user or retention questions. The rollups are updated transactionally with new ingest, and a durable scheduled job backfills existing analytics_events after deployment. Until that job completes, use analytics_events only for bounded recent drill-downs with an explicit event_date or timestamp range. Before a large or historical query, call get-first-party-analytics-health and use a configured external backend when it recommends one: BigQuery supports warehouse SQL and historical analysis, while Amplitude supports product analytics, funnels, and retention. Connecting a backend does not automatically reroute /track events or copy existing Neon events, so use that provider's explicit collection or export path before querying it. Aggregate, project only needed columns, and add a LIMIT for raw or high-cardinality reads; do not issue an unbounded raw-event scan or paginate a large cohort. An explicit all-time or lifetime request remains all-time, so do not invent a default lower time bound. Safe scoped results are cached for up to five minutes for this agent action. analytics_events columns include event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, and context. analytics_event_daily_rollups columns include tenant_key, owner_email, org_id, event_date, event_name, app, template, and event_count. analytics_user_days columns include tenant_key, owner_email, org_id, event_date, and user_key. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, tools, tools_truncated, delegated, delegation_protocol, caller_app, delegation_task_id, a2a_task_id, parent_run_id, parent_turn_id, and error_message/$ai_error. Agent Teams child runs use delegation_protocol = 'agent-team' and retain their own run_id while linking to the launching run through parent_run_id. The bounded tools array contains names, relative start times, durations, statuses, and coarse error classes only, never args or results; failed runs and interrupted tools remain queryable. session_recordings columns include 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, and metadata.",
+    "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 recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events, analytics_event_daily_rollups, analytics_user_days, and session_recordings; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. 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, event and rollup reads use partitioned BigQuery tables/views while session_recordings remains in the SQL store; cross-backend joins are not supported. Before a large or historical query, call get-first-party-analytics-health and use a configured external backend when it recommends one: BigQuery supports warehouse SQL and historical analysis, while Amplitude supports product analytics, funnels, and retention. Connecting a backend does not automatically reroute /track events or copy existing Neon events; the migration action performs that explicit prepare, backfill, and cutover sequence. Aggregate, project only needed columns, use bounded recent drill-downs, and add a LIMIT for raw or high-cardinality reads; do not issue an unbounded raw-event scan or paginate a large cohort. An explicit all-time or lifetime request remains all-time, so do not invent a default lower time bound. Safe scoped results are cached for up to five minutes for this agent action. analytics_events columns include event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, and context. analytics_event_daily_rollups columns include tenant_key, owner_email, org_id, event_date, event_name, app, template, and event_count. analytics_user_days columns include tenant_key, owner_email, org_id, event_date, and user_key. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, tools, tools_truncated, delegated, delegation_protocol, caller_app, delegation_task_id, a2a_task_id, parent_run_id, parent_turn_id, and error_message/$ai_error. Agent Teams child runs use delegation_protocol = 'agent-team' and retain their own run_id while linking to the launching run through parent_run_id. The bounded tools array contains names, relative start times, durations, statuses, and coarse error classes only, never args or results; failed runs and interrupted tools remain queryable. session_recordings columns include 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, and metadata.",
   schema: z.object({
     sql: z
       .string()
       .describe(
-        "Read-only SQL over analytics_events, analytics_event_daily_rollups, analytics_user_days, and session_recordings. Use literal values, not bind placeholders. Prefer the daily rollups for counts, active-user, and retention questions. A durable scheduled job repairs historical rollups after deployment; until it completes, use an explicit event_date or timestamp range for bounded analytics_events reads. Before a large or historical query, call get-first-party-analytics-health and use a configured external backend when recommended: BigQuery for warehouse SQL and complete history, or Amplitude for product analytics, funnels, and retention. Connecting one does not automatically reroute /track events or backfill existing Neon data. Aggregate or project only needed columns and add a LIMIT for raw or high-cardinality reads; do not issue an unbounded raw-event scan or paginate a large cohort. An explicit all-time or lifetime request remains all-time, so do not invent a default lower time bound. Example: SELECT event_date, event_name, SUM(event_count) AS events FROM analytics_event_daily_rollups WHERE event_date >= '2026-05-01' AND event_date < '2026-06-01' GROUP BY event_date, event_name ORDER BY event_date, events DESC",
+        "Read-only SQL over analytics_events, analytics_event_daily_rollups, analytics_user_days, and session_recordings. Use literal values, not bind placeholders. Prefer the daily rollups for counts, active-user, and retention questions. On the Builder.io production organization after the explicit BigQuery cutover, event and rollup reads use partitioned BigQuery tables/views while session_recordings remains in the SQL store; cross-backend joins are not supported. Before a large or historical query, call get-first-party-analytics-health and use a configured external backend when recommended: BigQuery for warehouse SQL and complete history, or Amplitude for product analytics, funnels, and retention. Connecting one does not automatically reroute /track events or backfill existing Neon data; the migration action performs that explicit prepare, backfill, and cutover sequence. Aggregate or project only needed columns and add a LIMIT for raw or high-cardinality reads; do not issue an unbounded raw-event scan or paginate a large cohort. An explicit all-time or lifetime request remains all-time, so do not invent a default lower time bound. Example: SELECT event_date, event_name, SUM(event_count) AS events FROM analytics_event_daily_rollups WHERE event_date >= '2026-05-01' AND event_date < '2026-06-01' GROUP BY event_date, event_name ORDER BY event_date, events DESC",
       ),
   }),
-  outputSchema: z.object({
-    rows: z.array(z.record(z.string(), z.unknown())),
-    schema: z.array(
-      z.object({
-        name: z.string(),
-        type: z.string(),
-      }),
-    ),
-  }),
+  outputSchema: dataTableWidgetResultSchema,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_DATA_TABLE_RENDERER,
+    title: "Analytics query result",
+    description: "Render query rows as a native table with CSV download.",
+  },
   readOnly: true,
   // No raw HTTP or connector-catalog route: SQL would land in query strings,
   // logs, or a caller that lacks this app's schema and data dictionary. This
@@ -40,6 +70,9 @@ export default defineAction({
   http: false,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   run: async (args) => {
-    return queryFirstPartyAnalytics(args.sql, resolveScope(), { cache: true });
+    const result = await queryFirstPartyAnalytics(args.sql, resolveScope(), {
+      cache: true,
+    });
+    return toDataTableResult(result);
   },
 });

package/corpus/templates/analytics/actions/test-custom-api-connection.ts

@@ -0,0 +1,106 @@
+import { defineAction } from "@agent-native/core";
+import { extractItemsArray } from "@agent-native/core/provider-api/staging";
+import { z } from "zod";
+
+import { getAnalyticsProviderApiRuntime } from "../server/lib/provider-api";
+
+const secretKey = /pass(word)?|secret|token|api[-_]?key|authorization/i;
+const Input = z.object({
+  provider: z.string().min(1),
+  path: z.string().min(1),
+  query: z.record(z.string(), z.unknown()).optional(),
+  itemsPath: z.string().min(1).optional(),
+});
+
+function redact(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redact);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      secretKey.test(key) ? "[redacted]" : redact(entry),
+    ]),
+  );
+}
+
+export default defineAction({
+  description:
+    "Test an Analytics custom API connection with a bounded authenticated GET and return a safe row preview.",
+  schema: Input,
+  agentTool: false,
+  http: { method: "POST" },
+  readOnly: true,
+  run: async ({ provider, path, query, itemsPath }) => {
+    try {
+      const result = (await getAnalyticsProviderApiRuntime().executeRequest({
+        provider,
+        method: "GET",
+        path,
+        ...(query ? { query } : {}),
+        auth: "default",
+        maxBytes: 1_000_000,
+        timeoutMs: 10_000,
+      })) as {
+        response?: {
+          ok?: boolean;
+          status?: number;
+          statusText?: string;
+          json?: unknown;
+          truncated?: boolean;
+        };
+      };
+      const response = result.response;
+      const status = response?.status ?? 0;
+      const statusText = response?.statusText ?? "";
+      if (!response?.ok) {
+        return {
+          ok: false,
+          status,
+          statusText,
+          rowCount: 0,
+          columns: [],
+          sampleRows: [],
+          itemsPath: itemsPath ?? null,
+          truncated: false,
+          error: `Custom API request failed with HTTP ${status}${statusText ? ` ${statusText}` : ""}.`,
+        };
+      }
+      const rows = extractItemsArray(response.json, itemsPath ?? "auto");
+      const sampleRows = rows.slice(0, 5).map((row) => redact(row));
+      const columns = Array.from(
+        new Set(
+          rows.flatMap((row) =>
+            row && typeof row === "object" && !Array.isArray(row)
+              ? Object.keys(row)
+              : [],
+          ),
+        ),
+      );
+      return {
+        ok: true,
+        status,
+        statusText,
+        rowCount: rows.length,
+        columns,
+        sampleRows,
+        itemsPath: itemsPath ?? "auto",
+        truncated: Boolean(response.truncated),
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        status: 0,
+        statusText: "",
+        rowCount: 0,
+        columns: [],
+        sampleRows: [],
+        itemsPath: itemsPath ?? null,
+        truncated: false,
+        error:
+          error instanceof Error
+            ? `Custom API connection failed: ${error.message}`
+            : "Custom API connection failed.",
+      };
+    }
+  },
+});

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

@@ -576,7 +576,6 @@ export default defineAction({
     "Do not use `ops` or `panelOrder` for ordinary agent edits like moving charts, adding panels to an existing dashboard, changing widths, or updating panel config; call `mutate-dashboard` once with the full edit script. " +
     "When this action is appropriate, provide only one of `ops`, `panelOrder`, or `config`; `config` replaces the whole dashboard config. " +
     "First-party event panels must bind to a declared dashboard time filter with `{{timeRange}}` or date-range variables. Intentional fixed-window, cohort-history, and all-time exceptions must be explicit in `panel.config.timeScope`; unbounded first-party SQL is rejected at save time. " +
-    "To add a shipped catalog template's panels to an existing dashboard, prefer `install-dashboard-template` with `mergePanels: true` — it appends the template's panels in one call without you having to author each panel. " +
     "The result is compact by default: `panelCount`, `appliedOps`, `panelOrder`, `firstPanelIds`, and `summary`. Set `returnConfig: true` only when you truly need the full config in the tool result. " +
     "The UI auto-refreshes after this action — do NOT call `refresh-screen`.",
   schema: z.object({