@agent-native/core 0.120.0 → 0.120.2

package/corpus/templates/analytics/AGENTS.md

@@ -1,8 +1,9 @@
 # Analytics — Agent Guide
 
 Analytics is an agent-native BI workspace. The agent manages data sources,
-queries, dashboards, charts, analyses, and connected warehouse integrations
-through actions and SQL-backed state.
+queries, dashboards, charts, and connected warehouse integrations through
+actions and SQL-backed state. Dashboards are the canonical user-facing
+analytics artifact; legacy analyses remain readable only for compatibility.
 
 Keep this file essential. Querying, dashboard, warehouse, and implementation
 details live in `.agents/skills/`.
@@ -175,13 +176,22 @@ membership id when its native update status reports `update-available`.
   `/agents?view=dashboards` shows the
   admin-only dashboard usage audit; call `list-dashboard-usage-stats` when
   admins ask about dashboard created/modified dates, owners, last tracked
-  modifier, views, engagements, saved views, or cleanup candidates. The
+  modifier, views, edits, engagements, saved views, or cleanup candidates. The
+  dashboard overflow menu shows created/updated timestamps and their tracked
+  actors for both SQL and Explorer dashboards. The
   Advanced menu opens `/agents?view=database`, where organization owners/admins
   can connect other agent-native app databases and use the shared database admin
   tool for table browsing, row editing, and SQL inspection. This database
   surface is for connected target app databases, not broad access to all
   Analytics data. Keep future admin additions inside this route instead of
   adding many top-level sidebar tabs.
+- The `migrate-analytics-artifacts` action is the organization-scoped
+  consolidation path. Run it first with `dryRun: true`, then use the exact
+  `confirm: "MIGRATE_ANALYTICS_ARTIFACTS"` token for an owner/admin-approved
+  write. It materializes legacy settings, turns saved analyses and standalone
+  extensions into dashboard blocks, archives exact duplicates, copies shares,
+  and keeps source rows recoverable. It intentionally covers organization-
+  scoped rows, not private member-only rows.
 - For dashboard edits, default to `mutate-dashboard` with its typed
   `dashboard.*` script API. It supports id-based panel moves, title/SQL/config
   edits, inserts, duplication, removal, and dashboard field patches in one
@@ -212,11 +222,13 @@ membership id when its native update status reports `update-available`.
 - `get-sql-dashboard` is compact by default for agents. Use its `panels`
   summaries and `layout.panelOrder` / `layout.firstPanelIds` for orientation and
   proof. Pass `includeConfig: true` only when full panel SQL/config is needed.
-- Native dashboards and saved analyses are constrained artifacts. If a requested
-  dashboard, analysis surface, visualization, interaction model, custom layout,
-  or bespoke workflow cannot be done faithfully with the built-in dashboard JSON
-  config/components or saved-analysis markdown/chart format, automatically build
-  it as an extension instead and tell the user why.
+- Native dashboards are constrained artifacts. If a requested dashboard,
+  analysis/report surface, visualization, interaction model, custom layout, or
+  bespoke workflow cannot be done faithfully with the built-in dashboard JSON
+  config/components, automatically create an extension and embed it as one or
+  more `chartType: "extension"` panels using `config.extensionId`. Never leave
+  the extension standalone or direct the user to an Extensions page from
+  Analytics.
 - For an existing extension-backed dashboard or migrated surface such as Risk
   Meeting, separate data repair from visual redesign. Inspect the dashboard and
   extension first, then call `update-extension` with exactly `id`,

package/corpus/templates/analytics/actions/get-explorer-dashboard.ts

@@ -33,6 +33,9 @@ export default defineAction({
       ownerEmail: dash.ownerEmail,
       orgId: dash.orgId,
       visibility: dash.visibility,
+      createdAt: dash.createdAt,
+      updatedAt: dash.updatedAt,
+      updatedBy: dash.updatedBy,
       role: dash.role,
       canEdit: dash.canEdit,
       canManage: dash.canManage,

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

@@ -1,6 +1,6 @@
 import { defineAction } from "@agent-native/core/action";
 import { buildDeepLink } from "@agent-native/core/server";
-import { and, eq, like, or, sql } from "drizzle-orm";
+import { and, eq, isNull, like, or, sql } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
@@ -21,6 +21,7 @@ type DashboardUsageStats = {
   viewCount: number;
   engagementCount: number;
   eventEngagementCount: number;
+  editCount: number;
   savedViewCount: number;
   uniqueUserCount: number;
   lastViewedAt: string | null;
@@ -96,6 +97,8 @@ export function dashboardIdFromEventLocation(
   if (!raw) return null;
   try {
     const parsed = new URL(raw, "https://analytics.local");
+    const parsedDashboardId = dashboardIdFromPath(parsed.pathname);
+    if (parsedDashboardId) return parsedDashboardId;
     if (
       /(?:^|\/)(?:dashboards|adhoc)\/explorer-dashboard$/.test(parsed.pathname)
     ) {
@@ -124,7 +127,7 @@ function dashboardUrl(row: { id: string; kind: string }): string {
 
 export default defineAction({
   description:
-    "List admin-only dashboard usage and cleanup stats for every dashboard in the active organization. Includes lifecycle metadata, owner, last tracked modifier, pageviews, engagement events, unique viewers, saved view counts, archive/hidden state, and dashboard links. Requires active organization owner/admin role.",
+    "List admin-only dashboard usage and cleanup stats for every dashboard in the active organization. Includes lifecycle metadata, owner, last tracked modifier, pageviews, edit counts, engagement events, unique viewers, saved view counts, archive/hidden state, and dashboard links. Requires active organization owner/admin role.",
   schema: z.object({}),
   http: { method: "GET" },
   readOnly: true,
@@ -144,24 +147,120 @@ export default defineAction({
     // guard:allow-unscoped — org owner/admin audit intentionally spans all
     // dashboard rows in the active org after requireDbAdminContextFromRequest.
     const dashboardRows = await db
-      .select()
+      .select({
+        id: schema.dashboards.id,
+        kind: schema.dashboards.kind,
+        title: schema.dashboards.title,
+        config: schema.dashboards.config,
+        ownerEmail: schema.dashboards.ownerEmail,
+        visibility: schema.dashboards.visibility,
+        createdAt: schema.dashboards.createdAt,
+        updatedAt: schema.dashboards.updatedAt,
+        updatedBy: schema.dashboards.updatedBy,
+        archivedAt: schema.dashboards.archivedAt,
+        hiddenAt: schema.dashboards.hiddenAt,
+        hiddenBy: schema.dashboards.hiddenBy,
+      })
       .from(schema.dashboards)
       .where(eq(schema.dashboards.orgId, admin.orgId));
 
+    if (dashboardRows.length === 0) return [];
+
     const dashboardIds = new Set<string>(
       dashboardRows.map((row: { id: string }) => row.id),
     );
 
-    const savedViewRows = await db
-      .select({
-        dashboardId: schema.dashboardViews.dashboardId,
-        count: sql<number>`count(*)`,
-        lastSavedViewAt: sql<
-          string | null
-        >`max(${schema.dashboardViews.createdAt})`,
-      })
-      .from(schema.dashboardViews)
-      .groupBy(schema.dashboardViews.dashboardId);
+    const analyticsUserIdentity = sql<
+      string | null
+    >`coalesce(nullif(${schema.analyticsEvents.userKey}, ''), nullif(${schema.analyticsEvents.userId}, ''), nullif(${schema.analyticsEvents.anonymousId}, ''), nullif(${schema.analyticsEvents.sessionId}, ''))`;
+    const indexedDashboardEventLocation = or(
+      like(schema.analyticsEvents.path, "/dashboards/%"),
+      like(schema.analyticsEvents.path, "/adhoc/%"),
+    );
+    const legacyAbsoluteUrlDashboardEventLocation = and(
+      or(
+        isNull(schema.analyticsEvents.path),
+        eq(schema.analyticsEvents.path, ""),
+      ),
+      or(
+        like(schema.analyticsEvents.url, "%/dashboards/%"),
+        like(schema.analyticsEvents.url, "%/adhoc/%"),
+      ),
+    );
+    const dashboardEventLocation = or(
+      indexedDashboardEventLocation,
+      legacyAbsoluteUrlDashboardEventLocation,
+    );
+
+    const [savedViewRows, revisionRows, eventRows, eventUserRows] =
+      await Promise.all([
+        db
+          .select({
+            dashboardId: schema.dashboardViews.dashboardId,
+            count: sql<number>`count(*)`,
+            lastSavedViewAt: sql<
+              string | null
+            >`max(${schema.dashboardViews.createdAt})`,
+          })
+          .from(schema.dashboardViews)
+          .innerJoin(
+            schema.dashboards,
+            and(
+              eq(schema.dashboardViews.dashboardId, schema.dashboards.id),
+              eq(schema.dashboards.orgId, admin.orgId),
+            ),
+          )
+          .groupBy(schema.dashboardViews.dashboardId),
+        db
+          .select({
+            dashboardId: schema.dashboardRevisions.dashboardId,
+            count: sql<number>`count(*)`,
+          })
+          .from(schema.dashboardRevisions)
+          .where(eq(schema.dashboardRevisions.orgId, admin.orgId))
+          .groupBy(schema.dashboardRevisions.dashboardId),
+        db
+          .select({
+            path: schema.analyticsEvents.path,
+            url: schema.analyticsEvents.url,
+            eventName: schema.analyticsEvents.eventName,
+            count: sql<number>`count(*)`,
+            lastSeenAt: sql<
+              string | null
+            >`max(${schema.analyticsEvents.receivedAt})`,
+          })
+          .from(schema.analyticsEvents)
+          .where(
+            and(
+              eq(schema.analyticsEvents.orgId, admin.orgId),
+              dashboardEventLocation,
+            ),
+          )
+          .groupBy(
+            schema.analyticsEvents.path,
+            schema.analyticsEvents.url,
+            schema.analyticsEvents.eventName,
+          ),
+        db
+          .select({
+            path: schema.analyticsEvents.path,
+            url: schema.analyticsEvents.url,
+            userIdentity: analyticsUserIdentity,
+          })
+          .from(schema.analyticsEvents)
+          .where(
+            and(
+              eq(schema.analyticsEvents.orgId, admin.orgId),
+              dashboardEventLocation,
+              sql`${analyticsUserIdentity} IS NOT NULL`,
+            ),
+          )
+          .groupBy(
+            schema.analyticsEvents.path,
+            schema.analyticsEvents.url,
+            analyticsUserIdentity,
+          ),
+      ]);
 
     const savedViewsByDashboard = new Map<
       string,
@@ -179,38 +278,15 @@ export default defineAction({
       });
     }
 
-    const analyticsUserIdentity = sql<
-      string | null
-    >`coalesce(nullif(${schema.analyticsEvents.userKey}, ''), nullif(${schema.analyticsEvents.userId}, ''), nullif(${schema.analyticsEvents.anonymousId}, ''), nullif(${schema.analyticsEvents.sessionId}, ''))`;
-    const eventRows = await db
-      .select({
-        path: schema.analyticsEvents.path,
-        url: schema.analyticsEvents.url,
-        eventName: schema.analyticsEvents.eventName,
-        count: sql<number>`count(*)`,
-        userIdentity: analyticsUserIdentity,
-        lastSeenAt: sql<
-          string | null
-        >`max(${schema.analyticsEvents.receivedAt})`,
-      })
-      .from(schema.analyticsEvents)
-      .where(
-        and(
-          eq(schema.analyticsEvents.orgId, admin.orgId),
-          or(
-            like(schema.analyticsEvents.path, "%/dashboards/%"),
-            like(schema.analyticsEvents.path, "%/adhoc/%"),
-            like(schema.analyticsEvents.url, "%/dashboards/%"),
-            like(schema.analyticsEvents.url, "%/adhoc/%"),
-          ),
-        ),
-      )
-      .groupBy(
-        schema.analyticsEvents.path,
-        schema.analyticsEvents.url,
-        schema.analyticsEvents.eventName,
-        analyticsUserIdentity,
-      );
+    const editsByDashboard = new Map<string, number>();
+    for (const row of revisionRows as Array<{
+      dashboardId: string;
+      count: unknown;
+    }>) {
+      if (dashboardIds.has(row.dashboardId)) {
+        editsByDashboard.set(row.dashboardId, toNumber(row.count));
+      }
+    }
 
     const eventsByDashboard = new Map<
       string,
@@ -226,7 +302,6 @@ export default defineAction({
       url: string | null;
       eventName: string;
       count: unknown;
-      userIdentity: string | null;
       lastSeenAt: string | null;
     }>) {
       const dashboardId = dashboardIdFromEventLocation(row.path, row.url);
@@ -248,6 +323,22 @@ export default defineAction({
       } else {
         current.eventEngagementCount += count;
       }
+      eventsByDashboard.set(dashboardId, current);
+    }
+
+    for (const row of eventUserRows as Array<{
+      path: string | null;
+      url: string | null;
+      userIdentity: string | null;
+    }>) {
+      const dashboardId = dashboardIdFromEventLocation(row.path, row.url);
+      if (!dashboardId || !dashboardIds.has(dashboardId)) continue;
+      const current = eventsByDashboard.get(dashboardId) ?? {
+        viewCount: 0,
+        eventEngagementCount: 0,
+        uniqueUsers: new Set<string>(),
+        lastViewedAt: null,
+      };
       if (row.userIdentity) current.uniqueUsers.add(row.userIdentity);
       eventsByDashboard.set(dashboardId, current);
     }
@@ -281,6 +372,7 @@ export default defineAction({
           hiddenBy: row.hiddenBy ?? null,
           viewCount: events.viewCount,
           eventEngagementCount: events.eventEngagementCount,
+          editCount: editsByDashboard.get(row.id) ?? 0,
           savedViewCount: savedViews.count,
           engagementCount: events.eventEngagementCount + savedViews.count,
           uniqueUserCount: events.uniqueUsers.size,
@@ -293,6 +385,8 @@ export default defineAction({
       .sort((a, b) => {
         const views = b.viewCount - a.viewCount;
         if (views !== 0) return views;
+        const edits = b.editCount - a.editCount;
+        if (edits !== 0) return edits;
         return b.updatedAt.localeCompare(a.updatedAt);
       });
   },

package/corpus/templates/analytics/actions/migrate-analytics-artifacts.ts

@@ -0,0 +1,48 @@
+import { defineAction } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { requireAnalyticsAdminContext } from "../server/lib/db-admin-connections";
+import {
+  migrateAnalyticsArtifacts,
+  type AnalyticsArtifactMigrationContext,
+} from "../server/lib/migrate-analytics-artifacts.js";
+
+const confirmation = "MIGRATE_ANALYTICS_ARTIFACTS" as const;
+
+export default defineAction({
+  description:
+    "Inventory or consolidate all organization-scoped Analytics dashboards, saved analyses, and extensions into the canonical Dashboards list. The default is a read-only dry run. A write requires an organization owner/admin and confirm=MIGRATE_ANALYTICS_ARTIFACTS; exact duplicates are archived/hidden, source rows remain recoverable, shares are copied, and legacy settings keys are removed only after SQL materialization.",
+  schema: z.object({
+    dryRun: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Inspect the migration without writing when true (default)."),
+    confirm: z
+      .literal(confirmation)
+      .optional()
+      .describe(
+        "Required for writes: MIGRATE_ANALYTICS_ARTIFACTS. Do not send this for a dry run.",
+      ),
+  }),
+  needsApproval: ({ dryRun }) => !dryRun,
+  run: async ({ dryRun, confirm }, ctx) => {
+    const userEmail = getRequestUserEmail() || ctx?.userEmail;
+    const orgId = getRequestOrgId() || ctx?.orgId || null;
+    const admin = await requireAnalyticsAdminContext({ userEmail, orgId });
+    if (!dryRun && confirm !== confirmation) {
+      throw new Error(
+        `Refusing the Analytics organization migration without confirm=${confirmation}. Run a dry run first, then repeat with the exact confirmation token.`,
+      );
+    }
+    const migrationContext: AnalyticsArtifactMigrationContext = {
+      userEmail: admin.userEmail,
+      orgId: admin.orgId,
+    };
+    return migrateAnalyticsArtifacts(migrationContext, { dryRun });
+  },
+});

package/corpus/templates/analytics/actions/save-analysis.ts

@@ -113,9 +113,8 @@ function assertCompactAnalysisPayload(args: {
 
 export default defineAction({
   description:
-    "Save an ad-hoc analysis as a reusable artifact. Do not call this for ordinary in-chat analysis or deep-dive answers unless the user explicitly asks to save/create a reusable analysis, or this turn is re-running an existing saved analysis. Stores the analysis question, instructions for re-running, data sources used, and compact results. " +
-    "This creates a reusable analysis that anyone can re-run later to get updated results. " +
-    "Saved analyses appear in the Analyses sidebar, so do not use this as scratch storage, as a transient summary, or as a duplicate companion artifact when creating a dashboard or extension unless the user explicitly asked for a saved analysis too. " +
+    "Legacy compatibility only: use this to re-run or update an existing saved analysis when the user explicitly names its legacy analysis id or asks to preserve that legacy record. Do not call this to create a new saved analysis, report, visualization, or bespoke workflow; new requests become dashboards, using update-dashboard and embedding any bespoke extension as one or more dashboard panels. Stores the legacy analysis question, instructions for re-running, data sources used, and compact results. " +
+    "Do not use this as scratch storage, a transient summary, or a duplicate companion artifact for a dashboard. " +
     "Call this only after you've gathered real evidence and include non-empty, compact resultData with structured evidence from those data-source action results. For qualitative analyses, resultData may include call/message IDs, short transcript excerpts, coded themes, mention counts, and sentiment labels derived from actual source records. Never include full Gong transcripts, full tool outputs, or bulk raw provider payloads.",
   schema: z.object({
     id: z

package/corpus/templates/analytics/actions/view-screen.ts

@@ -438,7 +438,7 @@ export default defineAction({
           includes: [
             "dashboard created and modified dates",
             "last tracked modifier",
-            "view and engagement counts",
+            "view, edit, and engagement counts",
             "saved view counts",
             "hidden and archived state",
           ],

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

@@ -0,0 +1,77 @@
+import { useFormatters, useT } from "@agent-native/core/client/i18n";
+import { IconCalendar, IconClock, IconUser } from "@tabler/icons-react";
+
+interface DashboardMetadataProps {
+  createdAt: string | null;
+  createdBy: string | null;
+  updatedAt: string | null;
+  updatedBy: string | null;
+}
+
+function MetadataRow({
+  icon: Icon,
+  label,
+  value,
+}: {
+  icon: typeof IconCalendar;
+  label: string;
+  value: string;
+}) {
+  return (
+    <div className="flex items-start gap-1.5">
+      <Icon className="mt-0.5 h-3 w-3 shrink-0" />
+      <span className="shrink-0">{label}</span>
+      <span className="min-w-0 truncate text-foreground/80">{value}</span>
+    </div>
+  );
+}
+
+export function DashboardMetadata({
+  createdAt,
+  createdBy,
+  updatedAt,
+  updatedBy,
+}: DashboardMetadataProps) {
+  const t = useT();
+  const { formatDate } = useFormatters();
+
+  function formatMetadataDate(value: string | null): string {
+    if (!value) return t("agents.notTracked");
+    try {
+      return formatDate(value, {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+      });
+    } catch {
+      return value;
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-1.5 text-xs text-muted-foreground">
+      <MetadataRow
+        icon={IconCalendar}
+        label={t("agents.dashboardMetadataCreated")}
+        value={formatMetadataDate(createdAt)}
+      />
+      <MetadataRow
+        icon={IconUser}
+        label={t("agents.dashboardMetadataCreatedBy")}
+        value={createdBy || t("agents.notTracked")}
+      />
+      <MetadataRow
+        icon={IconClock}
+        label={t("agents.dashboardMetadataUpdated")}
+        value={formatMetadataDate(updatedAt)}
+      />
+      <MetadataRow
+        icon={IconUser}
+        label={t("agents.dashboardMetadataUpdatedBy")}
+        value={updatedBy || t("agents.notTracked")}
+      />
+    </div>
+  );
+}

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

@@ -8,6 +8,12 @@ export function DashboardPanelSkeleton({
   ...props
 }: ComponentProps<typeof Skeleton>) {
   return (
-    <Skeleton {...props} className={cn("bg-muted-foreground/20", className)} />
+    <Skeleton
+      {...props}
+      className={cn(
+        "dashboard-panel-skeleton bg-muted-foreground/25",
+        className,
+      )}
+    />
   );
 }

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

@@ -12,6 +12,7 @@ import {
 
 const DASHBOARD_CONTEXT =
   "The user wants to create a new analytics dashboard. " +
+  'DASHBOARD ARTIFACT RULE — Dashboards are the only user-facing Analytics artifact. For deep dives, saved reports, custom visualizations, or bespoke workflows, always create or update a dashboard. If bespoke UI is needed, create the extension and immediately add it as one or more `chartType: "extension"` panels in that dashboard; never leave the extension standalone or direct the user to an Extensions page. ' +
   "TEMPLATE FIRST — If the user names an existing dashboard as a template to clone/base this on, resolve its id first (use `list-sql-dashboards` if you only have a title), then call `get-sql-dashboard` with `includeConfig: true` immediately and inspect `panels[].chartType`. " +
   'If any panel is `chartType: "extension"`, this is an extension-backed dashboard: call `get-extension` for that panel\'s `config.extensionId`, clone/adapt it with `create-extension` (apply the requested customer/org filters), then save a new dashboard via `update-dashboard` that embeds the new extension panel (`chartType: "extension"`, `config.extensionId`). Do not rebuild an extension template as guessed SQL/BigQuery panels. ' +
   "LARGE EXTENSION CLONE — Extension bodies can be very large (tens of thousands of characters). Call `get-extension` with `forceContent: true` exactly ONCE and reuse that body; a second same-run read intentionally omits `content` (you'll see `contentOmitted`), so don't treat that as the content being gone. Call `create-extension` / `update-extension` as NATIVE tools — they are mutating actions and cannot be invoked from `run-code`/`appAction`. For customer-specific clones, change only the small static config block (e.g. `ACCOUNT_USAGE_STATIC`) and prefer a focused `update-extension` edit over regenerating the whole HTML. Never shovel the full body through `run-code` or chat; if you stage it in a workspace scratch file, read it back with `workspaceRead` (which returns the whole file). " +