@agent-native/core 0.70.3 → 0.72.0

package/corpus/core/src/templates/workspace-core/.agents/skills/audit-log/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: audit-log
+description: >-
+  Durable, access-scoped, append-only record of who changed what app data,
+  when, and whether it was the agent or a human. Use when adding an activity
+  feed or change history, declaring what a mutating action targets, auditing
+  sensitive reads, or answering "what did the agent change / who edited this".
+scope: dev
+metadata:
+  internal: true
+---
+
+# Audit Log
+
+## Rule
+
+Every mutating action automatically records an audit event — **no wiring
+needed**. The framework captures who/what/when/from-where at the `defineAction`
+seam, redacts credentials, and attributes the change to a human or the agent
+(with the agent thread/turn that caused it). You only touch `audit` config to
+make events *more useful* (declare the target) or to opt a read in / a noisy
+write out.
+
+This is distinct from:
+
+- **observability** — sampled agent-run telemetry (traces, evals), developer-facing.
+- **tracking** — fire-and-forget product analytics to external SaaS.
+
+Audit is complete, durable, locally queryable, and scoped to the data it
+describes.
+
+## Declare the target so it lands in the owner's trail
+
+By default an event is scoped to the **actor** (you see your own changes and the
+agent's changes on your behalf). To make a change to a *shared* resource show up
+in the **owner's** audit trail, declare the target:
+
+```ts
+defineAction({
+  description: "Delete a recording",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    // type + id label the event; ownerEmail/orgId/visibility scope who can read it.
+    target: (args, result, meta) => ({
+      type: "recording",
+      id: args.id,
+      // Optional — defaults to the actor. Set when editing someone else's resource.
+      ownerEmail: result?.ownerEmail,
+      visibility: "org",
+    }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => { /* ... */ },
+});
+```
+
+`target`, `ownerEmail`, `visibility`, and `summary` are all optional. The
+minimum useful addition is `target: () => ({ type, id })`.
+
+## Defaults and how to override them
+
+- **Mutations** (anything not GET / `readOnly`) are audited automatically.
+- **Read-only** actions are skipped. Audit a sensitive read (secret access, bulk
+  export) with `audit: { onRead: true }`.
+- **High-frequency framework actions** (app-state sync, context-xray, navigate,
+  appearance) are skipped by default. Force one on with `audit: { enabled: true }`.
+- **Opt a noisy write out** with `audit: { enabled: false }`.
+- **Skip capturing arguments** (large/sensitive payloads) with
+  `audit: { recordInputs: false }`. Inputs are credential-redacted regardless.
+
+## Reading the log
+
+Two actions are available to the agent and the frontend in every app, scoped in
+SQL to the caller — they never leak another tenant's rows:
+
+- `list-audit-events` — filter by `targetType`/`targetId`, `actorKind`
+  (`agent` | `human` | `system`), `status`, `threadId`/`turnId`, `action`,
+  `sinceMs`, `limit`.
+- `get-audit-event` — one event by id, with its redacted input payload.
+
+Call them from the UI with `useActionQuery` to build an activity feed or a
+"who changed this" line — never hand-write a fetch to the audit table.
+
+## Never
+
+- Don't write a parallel "history" table for a resource — declare an `audit.target`
+  and read it back instead.
+- Don't put secrets in `summary` or rely on inputs being safe — redaction covers
+  credential-shaped values, but keep summaries free of sensitive data.
+- Don't expose an update/delete path for audit rows. The log is append-only; the
+  only deletion is the retention purge (`AGENT_NATIVE_AUDIT_RETENTION_DAYS`,
+  default 365 days; `0` = keep forever). Global kill switch:
+  `AGENT_NATIVE_AUDIT_ENABLED=false`.

package/corpus/core/src/usage/store.ts

@@ -8,6 +8,7 @@
  * Cost is stored as "centicents" (1/100th of a cent) for integer precision.
  */
 import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 
 /**
  * Per-million-token pricing in cents. Cache read is typically ~10% of
@@ -233,6 +234,11 @@ async function ensureUsageTable(): Promise<void> {
         }
       }
 
+      // Older deployments created `created_at` as 32-bit `INTEGER`; on Postgres
+      // the `Date.now()` written per run by recordUsage() overflows int4. Widen
+      // it in place (no-op once done / on fresh BIGINT databases).
+      await widenIntColumnsToBigInt("token_usage", ["created_at"]);
+
       try {
         await client.execute(
           `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,

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

@@ -174,12 +174,31 @@ pnpm action update-dashboard --dashboardId weekly-metrics --config '<full json>'
 
 After a mutation, navigate to the dashboard if the user is elsewhere. The app syncs through the framework's polling/query invalidation path.
 
+## Building Large First-Party Dashboards (compose-dashboard)
+
+For a **first-party analytics** dashboard, prefer `compose-dashboard` over hand-authoring a big `update-dashboard` config. You name the metrics; the SERVER expands each into a full, validated panel (SQL + chart config) from the shipped metric catalog and saves them in ONE atomic call. This avoids the failure mode where the agent must stream a giant multi-panel `update-dashboard` argument inside the ~40s budget — that big tool-call can't be resumed mid-stream and is all-or-nothing on validation, so the agent thrashes (repeated update-dashboard + tool-search, never landing).
+
+- **Never hand-author large first-party configs panel-by-panel.** Call `compose-dashboard` with the metric keys instead.
+- Unknown metric keys are skipped and reported in `unknownMetrics` (not fatal). Each panel's SQL is validated independently — valid panels save, invalid ones are reported in `invalidMetrics`.
+- By default (no `overwrite`), composing into an existing dashboard APPENDS the new panels and skips ids already present. `overwrite: true` replaces the whole config.
+- Each metric accepts an optional per-metric `window` of `'30d' | '90d' | 'all'` (only affects windowed virality/time metrics) and `title` / `chartType` / `width` overrides.
+- Returns `{ dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, skippedExistingIds }` — report `panelCount` as proof-of-done.
+
+Available metric keys: `total-signups`, `signups-over-time`, `signups-by-template`, `sessions-by-app`, `sessions-over-time`, `signed-in-vs-anon`, `total-template-clicks`, `total-demo-clicks`, `total-cli-copies`, `template-interest-over-time`, `clicks-by-template`, `demo-clicks-by-template`, `cli-copies-by-template`, `cli-copies-over-time`, `pageviews-over-time`, `referred-signups-30d`, `viral-signup-share-30d`, `clip-share-signups-30d`, `signups-by-referral-source`, `referred-signups-over-time`, `top-referrers`, `share-funnel-30d`, `viral-participation-rate-90d`, `viral-coefficient-90d`, `activated-referrers-90d`.
+
+```bash
+# Build a large first-party dashboard in ONE call (server generates the panels)
+pnpm action compose-dashboard --dashboardId first-party-overview --title "First-Party Overview" \
+  --metrics '["total-signups","signups-over-time","signups-by-template","sessions-by-app","viral-coefficient-90d","top-referrers","share-funnel-30d"]'
+```
+
 ## Reliable Bulk Edits
 
 This is the dashboard-specific application of the framework-wide `reliable-mutations` skill — read that for the general rule (one atomic write, verify end state, report proof-of-done).
 
 Hosted agent runs have a **~40s budget**. Many sequential `update-dashboard` calls (one per panel, plus schema-discovery calls) will blow that budget and leave the dashboard in a partial state — earlier inserts looked like they succeeded (✓), but nothing actually persisted. Avoid this:
 
+- **For a large first-party dashboard, use `compose-dashboard`** (see the section above): name the metrics, the server generates the panels in one call. Do not hand-author the big config.
 - **Batch ALL changes into ONE `update-dashboard` call.** A single `update-dashboard` is atomic: it applies every op to an in-memory config, validates all panel SQL, then upserts once. Never loop the action.
   - To add N panels, pass N ops in one call: `ops: [{op:"insert", path:"/panels/-", value:<panel>}, … ]` (`/panels/-` appends to the end).
   - The `ops` format needs no discovery: each op is `{ op, path, from?, value? }`, `op ∈ set | replace | remove | insert | move | move-before`, and `path` is a JSON Pointer (e.g. `/panels/3`, `/panels/3/title`, `/name`).

package/corpus/templates/analytics/AGENTS.md

@@ -83,6 +83,14 @@ details live in `.agents/skills/`.
 
 ## Dashboard Template Catalog
 
+- To build or extend a LARGE first-party dashboard, prefer `compose-dashboard`:
+  name the metrics and the server generates the validated SQL/config for every
+  panel in ONE fast call. Do NOT hand-author big `update-dashboard` configs
+  panel-by-panel or loop `update-dashboard` — streaming a giant multi-panel
+  argument inside the ~40s budget fails and thrashes. Unknown metric keys are
+  skipped and reported; per-panel SQL validates independently; existing
+  dashboards append by default (`overwrite: true` replaces). Report the returned
+  `panelCount` as proof-of-done.
 - `list-dashboard-templates` lists source-controlled dashboard templates with
   `id`, category, data sources, panel count, and installed dashboard IDs.
 - `install-dashboard-template` installs a catalog template into normal

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

@@ -0,0 +1,317 @@
+import { defineAction, embedApp } from "@agent-native/core";
+import {
+  getRequestUserEmail,
+  getRequestOrgId,
+  buildDeepLink,
+} from "@agent-native/core/server";
+import { z } from "zod";
+import { getDashboard, upsertDashboard } from "../server/lib/dashboards-store";
+import {
+  buildPanel,
+  listMetricKeys,
+  type ComposedPanel,
+  type MetricWindow,
+} from "../server/lib/first-party-metric-catalog";
+import { validateFirstPartyAnalyticsSql } from "../server/lib/first-party-analytics.js";
+import {
+  hasCollabState,
+  applyText,
+  seedFromText,
+} from "@agent-native/core/collab";
+
+/**
+ * Push the saved config through the collab layer so open dashboard editors get
+ * the change in real time (mirrors update-dashboard / install-dashboard-template).
+ */
+async function syncToCollab(
+  dashboardId: string,
+  config: Record<string, unknown>,
+): Promise<void> {
+  const docId = `dash-${dashboardId}`;
+  const configStr = JSON.stringify(config);
+  try {
+    if (await hasCollabState(docId)) {
+      await applyText(docId, configStr, "content", "agent");
+    } else {
+      await seedFromText(docId, configStr);
+    }
+  } catch {
+    // Collab sync is best-effort — the SQL write is the source of truth.
+  }
+}
+
+const WINDOWS = new Set<MetricWindow>(["30d", "90d", "all"]);
+
+function normalizeWindow(raw: unknown): MetricWindow | undefined {
+  if (typeof raw !== "string") return undefined;
+  const v = raw.trim() as MetricWindow;
+  return WINDOWS.has(v) ? v : undefined;
+}
+
+/** One requested metric, normalized to a key plus optional overrides. */
+interface NormalizedRequest {
+  metric: string;
+  id?: string;
+  title?: string;
+  chartType?: string;
+  width?: number;
+  window?: MetricWindow;
+}
+
+function normalizeRequest(raw: unknown): NormalizedRequest | null {
+  if (typeof raw === "string") {
+    const metric = raw.trim();
+    return metric ? { metric } : null;
+  }
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw as Record<string, unknown>;
+    const metric = typeof obj.metric === "string" ? obj.metric.trim() : "";
+    if (!metric) return null;
+    const width =
+      typeof obj.width === "number" && Number.isFinite(obj.width)
+        ? obj.width
+        : undefined;
+    return {
+      metric,
+      id: typeof obj.id === "string" ? obj.id : undefined,
+      title: typeof obj.title === "string" ? obj.title : undefined,
+      chartType: typeof obj.chartType === "string" ? obj.chartType : undefined,
+      width,
+      window: normalizeWindow(obj.window),
+    };
+  }
+  return null;
+}
+
+const metricSchema = z.union([
+  z.string(),
+  z.object({
+    metric: z.string(),
+    id: z.string().optional(),
+    title: z.string().optional(),
+    chartType: z.string().optional(),
+    width: z.number().optional(),
+    window: z.string().optional(),
+  }),
+]);
+
+const METRIC_KEYS = listMetricKeys();
+
+export default defineAction({
+  description:
+    "Build a large first-party analytics dashboard in ONE fast call: name the metrics you want and the SERVER generates the validated SQL + chart config for every panel. " +
+    "Do NOT hand-author large `update-dashboard` configs panel-by-panel — producing/streaming a big multi-panel config inside the ~40s run budget fails and thrashes. " +
+    "Each metric expands into a complete first-party panel from the shipped, already-validated metric catalog. Unknown metric keys are skipped and reported (not fatal); each panel's SQL is validated independently (valid panels are saved, invalid ones reported), and the dashboard is assembled and saved in a single atomic store write. " +
+    "If the dashboard already exists and `overwrite` is false (default), the new panels are APPENDED (panels whose id is already present are skipped); with `overwrite: true` the config is replaced. " +
+    "Returns { dashboardId, panelCount, createdMetrics, unknownMetrics, invalidMetrics, urlPath, deepLink, message } — use panelCount as proof-of-done. " +
+    `Available metric keys: ${METRIC_KEYS.join(", ")}. ` +
+    "Each metric accepts an optional per-metric `window` of '30d' | '90d' | 'all' (only affects windowed virality/time metrics).",
+  schema: z.object({
+    dashboardId: z
+      .string()
+      .describe(
+        "Dashboard id (without the `sql-dashboard-` prefix), e.g. 'first-party-overview'.",
+      ),
+    title: z
+      .string()
+      .optional()
+      .describe(
+        "Dashboard name. Used on create; on append it is applied only if the existing dashboard has no name.",
+      ),
+    metrics: z
+      .preprocess(
+        (v) => (typeof v === "string" ? JSON.parse(v) : v),
+        z.array(metricSchema),
+      )
+      .describe(
+        "Metric keys to include, in order. Each item is either a key string or { metric, title?, chartType?, width?, window? }. " +
+          `Valid keys: ${METRIC_KEYS.join(", ")}.`,
+      ),
+    overwrite: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true, replace the whole dashboard config. If false (default) and the dashboard exists, APPEND the new panels (skipping ids already present).",
+      ),
+  }),
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Dashboard preview",
+      description: "Open the composed dashboard in the real Analytics UI.",
+      iframeTitle: "Agent-Native Analytics",
+      openLabel: "Open dashboard",
+      height: 680,
+    }),
+  },
+  run: async (args) => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    const ctx = { email, orgId: getRequestOrgId() || null };
+
+    // The CLI/gateway may hand `metrics` over as a JSON string; the schema
+    // preprocess handles that, but normalize defensively here too.
+    const rawMetrics: unknown[] = Array.isArray(args.metrics)
+      ? (args.metrics as unknown[])
+      : typeof args.metrics === "string"
+        ? (JSON.parse(args.metrics) as unknown[])
+        : [];
+
+    const requests: NormalizedRequest[] = [];
+    for (const raw of rawMetrics) {
+      const normalized = normalizeRequest(raw);
+      if (normalized) requests.push(normalized);
+    }
+
+    const createdMetrics: string[] = [];
+    const unknownMetrics: string[] = [];
+    const invalidMetrics: Array<{ metric: string; reason: string }> = [];
+    const composedPanels: ComposedPanel[] = [];
+
+    for (const req of requests) {
+      const panel = buildPanel(req.metric, {
+        id: req.id,
+        title: req.title,
+        chartType: req.chartType,
+        width: req.width,
+        window: req.window,
+      });
+      if (!panel) {
+        // Unknown key — report, never throw.
+        if (!unknownMetrics.includes(req.metric)) {
+          unknownMetrics.push(req.metric);
+        }
+        continue;
+      }
+      // Per-panel graceful validation: a bad panel is dropped + reported, the
+      // rest of the dashboard still builds. (Catalog SQL is known-good, so this
+      // is a defensive net, e.g. if a future window/override produces bad SQL.)
+      try {
+        validateFirstPartyAnalyticsSql(panel.sql);
+      } catch (e: any) {
+        invalidMetrics.push({
+          metric: req.metric,
+          reason: e?.message ?? String(e),
+        });
+        continue;
+      }
+      composedPanels.push(panel);
+      createdMetrics.push(req.metric);
+    }
+
+    const existing = await getDashboard(args.dashboardId, ctx);
+    const dashboardName =
+      args.title?.trim() ||
+      (existing && typeof existing.config?.name === "string"
+        ? (existing.config.name as string)
+        : args.dashboardId);
+
+    let finalConfig: Record<string, unknown>;
+    let appendedCount = composedPanels.length;
+    let skippedExistingIds: string[] = [];
+
+    if (existing && !args.overwrite) {
+      // Append: preserve existing panels + order, add only new panel ids.
+      const existingConfig = existing.config as Record<string, unknown>;
+      const existingPanels = Array.isArray(existingConfig.panels)
+        ? (existingConfig.panels as Array<Record<string, unknown>>)
+        : [];
+      const existingIds = new Set(
+        existingPanels
+          .map((p) => (typeof p?.id === "string" ? p.id : null))
+          .filter((id): id is string => !!id),
+      );
+      const toAppend: ComposedPanel[] = [];
+      for (const panel of composedPanels) {
+        if (existingIds.has(panel.id)) {
+          skippedExistingIds.push(panel.id);
+          continue;
+        }
+        toAppend.push(panel);
+        existingIds.add(panel.id);
+      }
+      appendedCount = toAppend.length;
+      finalConfig = {
+        ...existingConfig,
+        name:
+          typeof existingConfig.name === "string" && existingConfig.name.trim()
+            ? existingConfig.name
+            : dashboardName,
+        panels: [...existingPanels, ...toAppend],
+      };
+    } else {
+      // Create or overwrite: a fresh config with exactly the composed panels.
+      finalConfig = {
+        name: dashboardName,
+        description:
+          "First-party analytics dashboard composed from the metric catalog.",
+        panels: composedPanels,
+      };
+    }
+
+    const panelCount = Array.isArray(finalConfig.panels)
+      ? (finalConfig.panels as unknown[]).length
+      : 0;
+
+    // Single atomic save through the same store path update-dashboard uses.
+    await upsertDashboard(args.dashboardId, "sql", finalConfig, ctx);
+    await syncToCollab(args.dashboardId, finalConfig);
+
+    const parts: string[] = [];
+    if (existing && !args.overwrite) {
+      parts.push(`Appended ${appendedCount} panel(s) to "${args.dashboardId}"`);
+      if (skippedExistingIds.length > 0) {
+        parts.push(`${skippedExistingIds.length} already present`);
+      }
+    } else {
+      parts.push(
+        `${existing ? "Replaced" : "Created"} "${args.dashboardId}" with ${createdMetrics.length} panel(s)`,
+      );
+    }
+    if (unknownMetrics.length > 0) {
+      parts.push(
+        `skipped ${unknownMetrics.length} unknown metric(s): ${unknownMetrics.join(", ")}`,
+      );
+    }
+    if (invalidMetrics.length > 0) {
+      parts.push(
+        `skipped ${invalidMetrics.length} invalid metric(s): ${invalidMetrics.map((m) => m.metric).join(", ")}`,
+      );
+    }
+    parts.push(`Dashboard now has ${panelCount} panel(s).`);
+
+    return {
+      id: args.dashboardId,
+      dashboardId: args.dashboardId,
+      name: dashboardName,
+      panelCount,
+      createdMetrics,
+      unknownMetrics,
+      invalidMetrics,
+      skippedExistingIds,
+      urlPath: `/dashboards/${args.dashboardId}`,
+      deepLink: buildDeepLink({
+        app: "analytics",
+        view: "adhoc",
+        params: { dashboardId: args.dashboardId },
+      }),
+      message: parts.join("; ") + ".",
+    };
+  },
+  link: ({ result }) => {
+    const dashboardId =
+      result && typeof result === "object"
+        ? (result as { dashboardId?: string }).dashboardId
+        : undefined;
+    if (!dashboardId) return null;
+    return {
+      url: buildDeepLink({
+        app: "analytics",
+        view: "adhoc",
+        params: { dashboardId },
+      }),
+      label: "Open composed dashboard in Analytics",
+      view: "adhoc",
+    };
+  },
+});

package/corpus/templates/analytics/changelog/2026-06-23-build-large-first-party-analytics-dashboards-in-one-fast-cal.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-06-23
+---
+
+Build large first-party analytics dashboards in one fast call by naming metrics