@agent-native/core 0.131.7 → 0.132.0

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -156,6 +156,43 @@ flattens into the baseline and reads as "no data."
 - Scheduled email reports render the same two scales, so a dual-axis panel is
   safe to put on a subscribed dashboard.
 
+## Reusable Native Dashboard Patterns
+
+The recent extension-backed dashboards in Builder Analytics cluster into a few
+repeatable compositions. Prefer these native panels, with a real SQL or Data
+Program result behind each one, when creating a replacement or a new dashboard:
+
+| Pattern | Native composition |
+| --- | --- |
+| Customer ROI / value realization | `metric` KPI cards, `line` or `area` trends, `table` detail, and `callout` or `section` panels for the business narrative |
+| Account engagement / outreach | `metric` coverage and adoption cards, a daily `line` trend, `heatmap` or `table` segmentation, and `callout` alerts |
+| GTM pipeline / cross-sell | `funnel` for ordered stages, `metric` totals, `bar` or `line` trends, and a `table` for account-level follow-up |
+| Win/loss analysis | `section` groups with `metric`, `table`, `bar`, `callout`, and trend panels; use a Data Program for provider joins and evidence rows |
+
+Funnel panels use `config.xKey` for the stage label and `config.yKey` for a
+non-negative count or value. The renderer preserves the SQL row order, shows
+each stage's share of the first stage, and shows the change from the previous
+stage. Keep the intended stage order in SQL with `ORDER BY`.
+
+When a dashboard is being migrated from an extension, create a new v2 copy,
+bind its panels to the real provider schema or Data Programs, and compare it
+with the original before retiring the extension-backed version. Do not invent
+customer-specific SQL, provider joins, cached rows, or extension ids in a
+catalog template. Existing dashboards remain readable while the native
+replacement is validated. Bespoke interaction flows, arbitrary layouts, and
+visualizations outside these contracts may remain Custom Blocks.
+
+The source tree ships four provider-free v2 manifests in
+`server/lib/native-v2-dashboards.ts`: Customer ROI, Account Engagement,
+Cross-sell, and Win / Loss. They intentionally contain no customer names,
+provider ids, SQL, cached rows, or guessed joins. After deployment, an
+organization owner or admin provisions them with `ensure-native-v2-dashboards`
+by supplying one real Data Program per binding key. The action validates the
+stored program output contract, shares the programs with the organization,
+creates deterministic `native-*-v2-*` dashboard copies, and preserves the
+extension-backed originals and any existing v2 edits. Do not add these to the
+root demo bootstrap or silently auto-bind them to guessed provider schemas.
+
 ## When To Use An Extension Instead
 
 Native Analytics dashboards are JSON configs rendered by the built-in dashboard
@@ -474,6 +511,7 @@ type PanelPatch = {
     | "table"
     | "pie"
     | "section"
+    | "funnel"
     | "heatmap"
     | "callout"
     | "extension";

package/corpus/templates/analytics/actions/dashboard-mutation-api.ts

@@ -49,7 +49,7 @@ type PanelPatch = {
   title?: string;
   sql?: string;
   source?: "bigquery" | "ga4" | "amplitude" | "first-party" | "demo" | "prometheus" | "program";
-  chartType?: "line" | "area" | "bar" | "metric" | "table" | "pie" | "section" | "heatmap" | "callout" | "extension";
+  chartType?: "line" | "area" | "bar" | "metric" | "table" | "pie" | "funnel" | "section" | "heatmap" | "callout" | "extension";
   width?: number;
   columns?: number;
   tab?: string;

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

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+
+import { defineAction, embedApp } from "@agent-native/core";
+import { getDataProgram } from "@agent-native/core/data-programs";
+import {
+  buildDeepLink,
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { resolveAccess } from "@agent-native/core/sharing";
+import setResourceVisibilityAction from "@agent-native/core/sharing/actions/set-resource-visibility";
+import { z } from "zod";
+
+import { getDashboard, upsertDashboard } from "../server/lib/dashboards-store";
+import { requireAnalyticsAdminContext } from "../server/lib/db-admin-connections";
+import {
+  compileNativeV2Dashboard,
+  getNativeV2DashboardManifest,
+  nativeV2DashboardManifests,
+  NATIVE_V2_DASHBOARD_IDS,
+  type NativeV2Binding,
+  type NativeV2BindingKey,
+  type NativeV2DashboardId,
+} from "../server/lib/native-v2-dashboards";
+
+const ANALYTICS_APP_ID = "analytics";
+
+const bindingSchema = z.object({
+  programId: z.string().min(1),
+  params: z.record(z.string(), z.unknown()).optional(),
+});
+
+function orgDashboardId(
+  orgId: string,
+  templateId: NativeV2DashboardId,
+): string {
+  const suffix = createHash("sha256").update(orgId).digest("hex").slice(0, 10);
+  return `native-${templateId}-${suffix}`;
+}
+
+function parseOutputColumns(value: string | null): Set<string> {
+  if (!value) return new Set();
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed)) return new Set();
+    return new Set(
+      parsed.flatMap((column) =>
+        column && typeof column === "object" && typeof column.name === "string"
+          ? [column.name]
+          : [],
+      ),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+function templateIdFromDashboard(
+  config: Record<string, unknown>,
+): string | null {
+  const catalog = config.catalog;
+  if (!catalog || typeof catalog !== "object" || Array.isArray(catalog)) {
+    return null;
+  }
+  const templateId = (catalog as Record<string, unknown>).templateId;
+  return typeof templateId === "string" ? templateId : null;
+}
+
+async function validateAndShareBindings(
+  bindings: Record<string, NativeV2Binding>,
+  requiredKeys: NativeV2BindingKey[],
+  requiredColumnsByBinding: Partial<Record<NativeV2BindingKey, string[]>>,
+  admin: { userEmail: string; orgId: string },
+): Promise<void> {
+  const missing = requiredKeys.filter((key) => !bindings[key]?.programId);
+  if (missing.length > 0) {
+    throw new Error(`Missing required v2 bindings: ${missing.join(", ")}`);
+  }
+
+  const uniqueProgramIds = new Set(
+    requiredKeys.map((key) => bindings[key]?.programId).filter(Boolean),
+  );
+  const programsToShare: string[] = [];
+  for (const programId of uniqueProgramIds) {
+    const program = await getDataProgram(programId, ANALYTICS_APP_ID);
+    if (!program) {
+      throw new Error(`Data program not found: ${programId}`);
+    }
+    if (program.orgId && program.orgId !== admin.orgId) {
+      throw new Error(
+        `Data program belongs to another organization: ${programId}`,
+      );
+    }
+    if (program.archivedAt) {
+      throw new Error(`Data program is archived: ${programId}`);
+    }
+    const access = await resolveAccess("data_program", programId, {
+      userEmail: admin.userEmail,
+      orgId: admin.orgId,
+    });
+    if (!access) {
+      throw new Error(`No access to data program: ${programId}`);
+    }
+    const outputColumns = parseOutputColumns(program.outputColumns);
+    const missingColumns = [
+      ...new Set(
+        requiredKeys.flatMap((key) =>
+          bindings[key]?.programId === programId
+            ? (requiredColumnsByBinding[key] ?? [])
+            : [],
+        ),
+      ),
+    ].filter((column) => !outputColumns.has(column));
+    if (missingColumns.length > 0) {
+      throw new Error(
+        `Data program ${programId} is missing required output columns: ${missingColumns.join(", ")}. Re-save it after a successful dry-run.`,
+      );
+    }
+
+    if (program.visibility !== "org" || program.orgId !== admin.orgId) {
+      programsToShare.push(programId);
+    }
+  }
+
+  for (const programId of programsToShare) {
+    await setResourceVisibilityAction.run({
+      resourceType: "data_program",
+      resourceId: programId,
+      visibility: "org",
+    });
+  }
+}
+
+export interface EnsureNativeV2DashboardsResult {
+  orgId: string;
+  dashboards: Array<{
+    templateId: NativeV2DashboardId;
+    dashboardId: string;
+    status: "created" | "updated" | "preserved";
+    requiredBindings: NativeV2BindingKey[];
+  }>;
+}
+
+export async function ensureNativeV2Dashboards(
+  args: {
+    templateIds?: NativeV2DashboardId[];
+    bindings: Record<string, NativeV2Binding>;
+    overwrite: boolean;
+  },
+  ctx?: { userEmail?: string; orgId?: string | null },
+): Promise<EnsureNativeV2DashboardsResult> {
+  const admin = await requireAnalyticsAdminContext(ctx);
+  const templateIds = args.templateIds?.length
+    ? args.templateIds
+    : [...NATIVE_V2_DASHBOARD_IDS];
+  const manifests = templateIds.map(getNativeV2DashboardManifest);
+  const allRequiredBindings = [
+    ...new Set(manifests.flatMap((manifest) => manifest.requiredBindings)),
+  ];
+  const requiredColumnsByBinding: Partial<
+    Record<NativeV2BindingKey, string[]>
+  > = Object.fromEntries(
+    manifests.flatMap((manifest) =>
+      manifest.panels
+        .filter(
+          (panel): panel is typeof panel & { bindingKey: NativeV2BindingKey } =>
+            Boolean(panel.bindingKey),
+        )
+        .map((panel) => [panel.bindingKey, panel.requiredColumns ?? []]),
+    ),
+  );
+
+  await validateAndShareBindings(
+    args.bindings,
+    allRequiredBindings,
+    requiredColumnsByBinding,
+    admin,
+  );
+
+  const installedAt = new Date().toISOString();
+  const dashboards: EnsureNativeV2DashboardsResult["dashboards"] = [];
+  for (const manifest of manifests) {
+    const dashboardId = orgDashboardId(admin.orgId, manifest.id);
+    const existing = await getDashboard(dashboardId, {
+      email: admin.userEmail,
+      orgId: admin.orgId,
+    });
+    if (existing && templateIdFromDashboard(existing.config) !== manifest.id) {
+      throw new Error(
+        `Refusing to overwrite unrelated dashboard at deterministic id ${dashboardId}.`,
+      );
+    }
+
+    if (existing && !args.overwrite) {
+      dashboards.push({
+        templateId: manifest.id,
+        dashboardId,
+        status: "preserved",
+        requiredBindings: manifest.requiredBindings,
+      });
+      continue;
+    }
+
+    const config = compileNativeV2Dashboard(
+      manifest,
+      args.bindings,
+      installedAt,
+    );
+    await upsertDashboard(
+      dashboardId,
+      "sql",
+      config as unknown as Record<string, unknown>,
+      {
+        email: admin.userEmail,
+        orgId: admin.orgId,
+      },
+    );
+    if (!existing) {
+      await setResourceVisibilityAction.run({
+        resourceType: "dashboard",
+        resourceId: dashboardId,
+        visibility: "org",
+      });
+    }
+    dashboards.push({
+      templateId: manifest.id,
+      dashboardId,
+      status: existing ? "updated" : "created",
+      requiredBindings: manifest.requiredBindings,
+    });
+  }
+
+  return { orgId: admin.orgId, dashboards };
+}
+
+export default defineAction({
+  description:
+    "Provision the four reusable native Analytics v2 dashboard patterns 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({
+    templateIds: z
+      .array(z.enum(NATIVE_V2_DASHBOARD_IDS))
+      .min(1)
+      .optional()
+      .describe("Optional subset of native v2 templates to provision."),
+    bindings: z
+      .record(z.string(), bindingSchema)
+      .describe(
+        'Binding key to stored Analytics Data Program, e.g. {"roi.kpi": {"programId": "dp_..."}}.',
+      ),
+    overwrite: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe("Replace an existing v2 copy only when explicitly true."),
+  }),
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Native Analytics v2 dashboards",
+      description: "Open the provisioned native v2 dashboard in Analytics.",
+      iframeTitle: "Agent-Native Analytics",
+      openLabel: "Open native v2 dashboard",
+      height: 680,
+    }),
+  },
+  run: async (args, ctx) => {
+    const userEmail = ctx?.userEmail ?? getRequestUserEmail();
+    const orgId = ctx?.orgId ?? getRequestOrgId() ?? null;
+    return ensureNativeV2Dashboards(
+      {
+        templateIds: args.templateIds,
+        bindings: args.bindings,
+        overwrite: args.overwrite,
+      },
+      { userEmail, orgId },
+    );
+  },
+  link: ({ result }) => {
+    const dashboardId =
+      result && typeof result === "object"
+        ? (result as EnsureNativeV2DashboardsResult).dashboards?.[0]
+            ?.dashboardId
+        : null;
+    if (!dashboardId) return null;
+    return {
+      url: buildDeepLink({
+        app: "analytics",
+        view: "adhoc",
+        params: { dashboardId },
+      }),
+      label: "Open native v2 dashboard",
+      view: "adhoc",
+    };
+  },
+});
+
+export { nativeV2DashboardManifests };

package/corpus/templates/analytics/actions/list-native-v2-dashboard-templates.ts

@@ -0,0 +1,34 @@
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+import {
+  nativeV2DashboardManifests,
+  NATIVE_V2_DASHBOARD_VERSION,
+} from "../server/lib/native-v2-dashboards";
+
+export default defineAction({
+  description:
+    "List the source-controlled native Analytics v2 dashboard manifests, including required Data Program binding keys and output columns. These provider-free manifests are compiled into org dashboards by ensure-native-v2-dashboards.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async () => ({
+    version: NATIVE_V2_DASHBOARD_VERSION,
+    templates: nativeV2DashboardManifests.map((manifest) => ({
+      id: manifest.id,
+      name: manifest.name,
+      description: manifest.description,
+      category: manifest.category,
+      tags: manifest.tags,
+      requiredBindings: manifest.requiredBindings,
+      panels: manifest.panels.map((panel) => ({
+        id: panel.id,
+        title: panel.title,
+        chartType: panel.chartType,
+        bindingKey: panel.bindingKey ?? null,
+        requiredColumns: panel.requiredColumns ?? [],
+      })),
+    })),
+  }),
+});

package/corpus/templates/analytics/app/components/dashboard/SqlChart.tsx

@@ -64,6 +64,8 @@ import {
 import { useChartTooltipPortalPosition } from "@/hooks/use-chart-tooltip-portal";
 
 const PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
+import { resolveDashboardFunnelRows } from "@shared/dashboard-funnel";
+
 import { createDemoChartTrendRows } from "@/lib/demo-chart-trend";
 import { useSqlQuery } from "@/lib/sql-query";
 import {
@@ -1454,6 +1456,12 @@ export function SqlChart({
     );
   }
 
+  if (chartType === "funnel") {
+    return withConfigWarning(
+      <FunnelRenderer rows={rows} panel={panel} colors={colors} />,
+    );
+  }
+
   if (chartType === "heatmap") {
     return withConfigWarning(<HeatmapRenderer rows={rows} panel={panel} />);
   }
@@ -2350,6 +2358,80 @@ function TimeSeriesRenderer({
   );
 }
 
+function FunnelRenderer({
+  rows,
+  panel,
+  colors,
+}: {
+  rows: Record<string, unknown>[];
+  panel: SqlPanel;
+  colors: string[];
+}) {
+  const t = useT();
+  const funnel = useMemo(
+    () =>
+      resolveDashboardFunnelRows(rows, panel.config?.xKey, panel.config?.yKey),
+    [rows, panel.config?.xKey, panel.config?.yKey],
+  );
+
+  if (funnel.items.length === 0) {
+    return (
+      <div
+        className={`flex items-center justify-center py-8 ${TABLE_PANEL_MIN_HEIGHT_CLASS}`}
+      >
+        <p className="text-sm text-muted-foreground text-center">
+          {t("common.noData")}
+        </p>
+      </div>
+    );
+  }
+
+  const maxValue = Math.max(...funnel.items.map((item) => item.value), 1);
+  const formatter = panel.config?.yFormatter;
+  const funnelColors = colors.length > 0 ? colors : DEFAULT_COLORS;
+
+  return (
+    <div
+      className="space-y-3 py-2"
+      role="img"
+      aria-label={panel.title}
+      data-dashboard-funnel="true"
+    >
+      {funnel.items.map((item, index) => {
+        const width =
+          item.value > 0 ? Math.max(2, (item.value / maxValue) * 100) : 0;
+        const dropOff =
+          item.dropOffPercent === null
+            ? null
+            : `${item.dropOffPercent < 0 ? "↑" : "↓"} ${Math.abs(item.dropOffPercent).toFixed(1)}%`;
+        return (
+          <div key={`${item.label}-${index}`} className="space-y-1">
+            <div className="flex items-baseline justify-between gap-3 text-xs">
+              <span className="min-w-0 truncate font-medium text-foreground">
+                {item.label}
+              </span>
+              <span className="shrink-0 tabular-nums text-muted-foreground">
+                {formatYValue(item.value, formatter)} ·{" "}
+                {item.percentOfFirst.toFixed(1)}%
+                {dropOff ? ` · ${dropOff}` : ""}
+              </span>
+            </div>
+            <div className="h-5 overflow-hidden rounded-sm bg-muted/60">
+              <div
+                className="h-full rounded-sm transition-[width]"
+                style={{
+                  width: `${width}%`,
+                  backgroundColor: funnelColors[index % funnelColors.length],
+                }}
+              />
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
 // Heatmap config: `xKey` = x-axis column, `yKey` = numeric value column,
 // `color` = optional row-label column. If `color` is omitted, the renderer
 // auto-detects the row-label as the first non-x non-value string column.

package/corpus/templates/analytics/app/components/layout/NewDashboardDialog.tsx

@@ -22,9 +22,9 @@ const DASHBOARD_CONTEXT =
   "NATIVE PANELS — Create a SQL-driven dashboard by calling the `update-dashboard` action with `dashboardId` and `config`; use a Data Program first when reusable fetching or transformation is the missing layer. " +
   "The config shape is: { name: string, panels: [{ id, title, sql, source, chartType, width, tab?, config? }] }. " +
   "Each panel needs: id (unique string), title, sql (the query), source ('bigquery' | 'ga4' | 'amplitude' | 'first-party' | 'demo' | 'prometheus'), " +
-  "chartType ('line' | 'area' | 'bar' | 'metric' | 'table' | 'pie'), width (1 or 2). " +
+  "chartType ('line' | 'area' | 'bar' | 'metric' | 'table' | 'pie' | 'funnel' | 'heatmap' | 'callout' | 'section'), width (1 or 2). " +
   "Optional tab labels can use 'Group / Tab' for primary and secondary dashboard tabs. " +
-  "Optional config: { xKey, yKey, yKeys, color, colors, yFormatter ('number'|'currency'|'percent'), description, valueLabels }. " +
+  "Optional config: { xKey, yKey, yKeys, color, colors, yFormatter ('number'|'currency'|'percent'), description, valueLabels }. For funnel panels, xKey is the stage label, yKey is the non-negative value, and SQL ORDER BY defines stage order. " +
   "For first-party analytics, source is 'first-party' and sql may read analytics_events only; do not use db-query for datasource panels. " +
   "For the built-in demo dashboard, source is 'demo' and sql uses the same Prometheus JSON descriptor shape as source 'prometheus': { promql, mode, range, step }. " +
   "Call `data-source-status` if you need to see which data sources are connected. " +

package/corpus/templates/analytics/app/hooks/use-dashboard-chat-context.ts

@@ -18,6 +18,7 @@ const DASHBOARD_CONTEXT_KEY = "analytics-selected-dashboard";
 const DASHBOARD_PANEL_CONTEXT_KEY = "analytics-selected-dashboard-panel";
 const SELECTED_OBJECT_STATE_KEY = "selected-object";
 const SELECTED_OBJECT_SOURCE_FIELD = "__agentNativeSelectedObjectSource";
+const CONTEXT_PUBLISH_DELAY_MS = 250;
 
 export interface DashboardChatContextArgs {
   id: string | null | undefined;
@@ -233,56 +234,61 @@ export function useDashboardChatContext(
       );
   }, []);
 
+  // Dashboard metadata lands in pieces — title first, then panel count, then
+  // the access role. Publishing each piece costs a round-trip and a sync event
+  // that invalidates every mounted query, so only the settled value is sent.
   useEffect(() => {
     if (!id) return;
     const displayTitle = title?.trim() || id;
-
-    setAgentChatContextItem({
-      key: DASHBOARD_CONTEXT_KEY,
-      title: `Dashboard: ${displayTitle}`,
-      context: dashboardContext({
-        id,
-        kind,
-        title: displayTitle,
-        panelCount,
-        canEdit,
-      }),
-      openSidebar: false,
-      focus: false,
-    });
-
-    return () => {
-      removeAgentChatContextItem({
+    const timer = setTimeout(() => {
+      setAgentChatContextItem({
         key: DASHBOARD_CONTEXT_KEY,
+        title: `Dashboard: ${displayTitle}`,
+        context: dashboardContext({
+          id,
+          kind,
+          title: displayTitle,
+          panelCount,
+          canEdit,
+        }),
         openSidebar: false,
+        focus: false,
       });
-    };
+    }, CONTEXT_PUBLISH_DELAY_MS);
+    return () => clearTimeout(timer);
   }, [canEdit, id, kind, panelCount, title]);
 
   useEffect(() => {
     if (!id || hasSelectedPanel) return;
     const displayTitle = title?.trim() || id;
-    setClientAppState(
-      SELECTED_OBJECT_STATE_KEY,
-      {
-        type: "dashboard",
-        id,
-        kind,
-        title: displayTitle,
-        panelCount,
-        canEdit,
-        [SELECTED_OBJECT_SOURCE_FIELD]: TAB_ID,
-      },
-      {
-        keepalive: true,
-        requestSource: TAB_ID,
-      },
-    ).catch(() => {});
+    const timer = setTimeout(() => {
+      setClientAppState(
+        SELECTED_OBJECT_STATE_KEY,
+        {
+          type: "dashboard",
+          id,
+          kind,
+          title: displayTitle,
+          panelCount,
+          canEdit,
+          [SELECTED_OBJECT_SOURCE_FIELD]: TAB_ID,
+        },
+        {
+          keepalive: true,
+          requestSource: TAB_ID,
+        },
+      ).catch(() => {});
+    }, CONTEXT_PUBLISH_DELAY_MS);
+    return () => clearTimeout(timer);
   }, [canEdit, hasSelectedPanel, id, kind, panelCount, title]);
 
   useEffect(() => {
     if (!id) return;
     return () => {
+      removeAgentChatContextItem({
+        key: DASHBOARD_CONTEXT_KEY,
+        openSidebar: false,
+      });
       removeAgentChatContextItem({
         key: DASHBOARD_PANEL_CONTEXT_KEY,
         openSidebar: false,

package/corpus/templates/analytics/app/hooks/use-user-pref.ts

@@ -32,13 +32,13 @@ export function useUserPref<T extends Record<string, unknown>>(key: string) {
       queryClient.setQueryData(queryKey, value);
       return { previousValue };
     },
+    // No invalidate on success: the optimistic value above is exactly what the
+    // server stored, so refetching it only buys a round-trip. `onError` is the
+    // path that restores truth.
     onError: (_err, _value, context) => {
       queryClient.setQueryData(queryKey, context?.previousValue);
       toast.error("Failed to save preference");
     },
-    onSettled: () => {
-      queryClient.invalidateQueries({ queryKey });
-    },
   });
 
   const { mutate: remove } = useMutation({