@agent-native/core 0.189.0 → 0.190.0-nightly-20260925215540

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 9963
+- template files: 9989

package/corpus/templates/analytics/.agents/skills/analysis-workspace/SKILL.md

@@ -92,6 +92,16 @@ Inside `run-code`, use the workspace helper functions:
   download must appear in chat; do not answer with only a path or navigation
   instructions.
 
+## CSV and XLSX Exports
+
+- For a compact result, use `query-agent-native-analytics` and its Download
+  CSV control. For a durable CSV, use `run-code` with `workspaceWrite` in a
+  normal Resources folder, then call `show-workspace-file` with that path. If
+  `run-code` is not available, discover it once with tool search.
+- For an explicit `.xlsx` request, call `docs-search` once for `xlsx export`
+  and follow the returned workflow. The QuickJS `run-code` sandbox has no Node
+  imports; do not try to load `xlsx` or `exceljs` there.
+
 ## Chunked Batch Analysis (30+ items)
 
 For large fan-outs (account deep dives, Gong call reviews, deal cohorts):

package/corpus/templates/analytics/.agents/skills/data-querying/SKILL.md

@@ -11,7 +11,7 @@ The analytics app connects to multiple data sources. This skill covers general p
 
 ## Approach
 
-0. **Orient catalog-first** — before querying, consult what already exists: the injected `<data-dictionary>` and data-source status tell you which sources are configured and which table/columns/join paths to use. Use them to pick the one source that owns the fact instead of fanning out blind queries.
+0. **Use retrieved references first** — data questions may start with a small set of relevant data-dictionary entries and saved dashboard panels in `<resource scope="analytics-catalog">`. Treat them as definitions and query examples, never live results. If they do not fit, call `search-analytics-query-catalog` before querying; use data-source status when provider availability matters.
 1. **Route named account health deliberately** — for a customer/org health, QBR, renewal, contract-utilization, risk, or adoption request, read `account-health` before writing SQL. It adds identity-lock and metric-definition checks that an ordinary lookup does not need.
 2. **Read the relevant provider skill first** — check `.agents/skills/<provider>/SKILL.md` for table names, column mappings, auth, and gotchas. For BigQuery, read `.agents/skills/bigquery/SKILL.md` and use `search-bigquery-schema` before guessing table or column names.
 3. **Clarify if ambiguous** — if the metric definition, date range, or grain is unclear and a wrong guess would change the numbers, use the `ask-question` clarifying tool (multiple-choice) before querying. Ask at most once per turn; skip it when the dictionary or the user already answered.

package/corpus/templates/analytics/AGENTS.md

@@ -17,8 +17,8 @@ Read the relevant skill before deeper work:
   de-duplication).
 - `dashboard-management` for dashboard/panel storage, layout, extensions,
   mutation and sharing.
-- `adhoc-analysis` and `analysis-workspace` for one-off answers and large
-  multi-source work.
+- `adhoc-analysis` for one-off answers; `analysis-workspace` for large work and
+  CSV/XLSX exports.
 - `provider-api` and `data-programs` for the escape hatch and durable,
   refreshable data sources.
 - `creative-context` for governed contexts and immutable dashboard revisions.
@@ -26,13 +26,13 @@ Read the relevant skill before deeper work:
 
 ## How To Answer A Data Question
 
-1. **Search existing work first.** For a metric question, call
-   `search-analytics-query-catalog`; for dashboard replication or adaptation,
-   call `search-dashboard-references` first. Inspect each returned reference
-   with `get-sql-dashboard` or `get-explorer-dashboard` by its `kind`; a match
-   is context, not authoritative source data. Then adapt the closest saved SQL
-   to the requested filters/window, run it once, and stop. Prefer a current
-   `certified` dashboard result; a dashboard starred by you is a weaker
+1. **Use the closest query example.** For a metric question, adapt a relevant
+   preloaded reference; if none fits, call `search-analytics-query-catalog`.
+   For dashboard replication or adaptation, call `search-dashboard-references`
+   first and inspect each result with `get-sql-dashboard` or
+   `get-explorer-dashboard` by its `kind`. A match is context, not live data.
+   Adapt the closest saved SQL to the requested filters/window, run it once,
+   and stop. Prefer a current `certified` dashboard; a favorite is a weaker
    relevance signal. Certification becomes stale after a dashboard edit.
 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.
@@ -66,9 +66,8 @@ certified ones); label figures "Unverified" when no live query ran.
   absence-sensitive Gong work, stage raw API data and use `query-staged-dataset`
   or a Data Program; see `provider-api`, `data-programs`, and `gong` for secure
   provider and hosted-endpoint boundaries.
-- 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.
+- Create dashboards or saved artifacts only when asked; keep them focused and
+  never modify existing dashboards without direction.
 - For named account/deal deep dives, call `account-deep-dive` first.
 - For named account health, read `account-health` before querying.
 - When the user challenges coverage or asks why records are missing, rerun from
@@ -85,16 +84,6 @@ certified ones); label figures "Unverified" when no live query ran.
   multi-step work, unavailable actions, or unsupported writes.
 - Reports/alerts use SQL actions; cap at five recipients.
 
-## Actions
-
-| Action | Use |
-| --- | --- |
-| `search-analytics-query-catalog` | Search saved metric examples first. |
-| `search-dashboard-references` | Find dashboards to replicate. |
-| `get-sql-dashboard` | Read the dashboard and exact panel SQL. |
-| `certify-dashboard` | Admin-only approval of its current version. |
-| DB | `list-db-admin-connections`, `list-connected-database-tables`, `db-admin-federated-read`: registry, schema, bounded joins. |
-
 ## Application State
 
 - `navigation` exposes the current dashboard, analysis, source, chart, and

package/corpus/templates/analytics/actions/list-data-dictionary.ts

@@ -3,7 +3,10 @@ import {
   getRequestUserEmail,
   getRequestOrgId,
 } from "@agent-native/core/server";
-import { getAllSettings, listOrgSettings } from "@agent-native/core/settings";
+import {
+  listOrgSettings,
+  listSettingsByPrefix,
+} from "@agent-native/core/settings";
 import { z } from "zod";
 
 const KEY_PREFIX = "data-dict-";
@@ -46,15 +49,10 @@ export default defineAction({
       for (const value of Object.values(orgEntries)) collect(value);
     }
 
-    // User-scoped entries — iterate once, filter by exact user prefix.
-    // See list-analyses.ts for the rationale (substring matches leak across
-    // users).
+    // Scope the read in SQL so other users' settings never enter this action.
     const userPrefix = `u:${email}:${KEY_PREFIX}`;
-    const all = await getAllSettings();
-    for (const [fullKey, value] of Object.entries(all)) {
-      if (!fullKey.startsWith(userPrefix)) continue;
-      collect(value);
-    }
+    const userEntries = await listSettingsByPrefix(userPrefix);
+    for (const { value } of userEntries) collect(value);
 
     const q = (args.search ?? "").trim().toLowerCase();
     const dept = (args.department ?? "").trim().toLowerCase();

package/corpus/templates/analytics/actions/search-analytics-query-catalog.ts

@@ -10,7 +10,7 @@ import { searchAnalyticsQueryCatalog } from "../server/lib/analytics-query-catal
 export default defineAction({
   description:
     "Prefer a current certified dashboard panel before other matches; a dashboard starred by the requesting user is a weaker relevance signal. " +
-    "Search Analytics' existing query knowledge before writing a new query. This is the analytics equivalent of grepping for similar code: one bounded call searches accessible saved dashboard names, chart titles/descriptions/queries, shipped dashboard patterns, and data-dictionary definitions. Use it first for an ordinary metric lookup unless the user supplied an exact source and query. Prefer the highest-trust close match, adapt its saved query only for the requested filters/time window, run one authoritative source query, and stop on success. Do not separately list every dashboard or scan provider catalogs after a strong match.",
+    "Search Analytics' existing query knowledge before writing a new query. This is the analytics equivalent of grepping for similar code: one bounded call searches accessible saved dashboard names, chart titles/descriptions/queries, shipped dashboard patterns, and data-dictionary definitions. The result reports `searchedDashboardCount`, `dashboardSearchTruncated`, `dashboardSearchStatus`, `searchedDictionaryEntryCount`, `dictionarySearchTruncated`, and `dictionarySearchStatus`. If dashboard search is truncated or unavailable and no close saved-dashboard match appears, use `search-dashboard-references` with focused terms; if dictionary search is truncated, partial, or unavailable and no close definition appears, use `list-data-dictionary` with focused terms before concluding there is no saved example. Use it first for an ordinary metric lookup unless the user supplied an exact source and query. Prefer the highest-trust close match, adapt its saved query only for the requested filters/time window, run one authoritative source query, and stop on success. Do not separately list every dashboard or scan provider catalogs after a strong match.",
   schema: z.object({
     search: z
       .string()

package/corpus/templates/analytics/app/components/AnalyticsReviewArtifactPreview.tsx

@@ -0,0 +1,201 @@
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+
+import { SqlChart } from "@/components/dashboard/SqlChart";
+import { resolveFilterVars } from "@/pages/adhoc/sql-dashboard/DashboardFilterBar";
+import { interpolate } from "@/pages/adhoc/sql-dashboard/interpolate";
+import { serializePanelSql } from "@/pages/adhoc/sql-dashboard/panel-sql";
+import { timeRangeDays } from "@/pages/adhoc/sql-dashboard/pivot";
+import type {
+  DashboardFilter,
+  DataSourceType,
+  ChartType,
+  SqlPanel,
+} from "@/pages/adhoc/sql-dashboard/types";
+
+const DATA_SOURCES: DataSourceType[] = [
+  "bigquery",
+  "ga4",
+  "amplitude",
+  "first-party",
+  "demo",
+  "prometheus",
+  "program",
+];
+const CHART_TYPES: ChartType[] = [
+  "line",
+  "area",
+  "bar",
+  "metric",
+  "table",
+  "pie",
+  "section",
+  "funnel",
+  "heatmap",
+  "callout",
+  "extension",
+];
+const FILTER_TYPES: DashboardFilter["type"][] = [
+  "date",
+  "date-range",
+  "select",
+  "toggle",
+  "text",
+  "toggle-date",
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSqlPanel(value: unknown): value is SqlPanel {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.id === "string" &&
+    typeof value.title === "string" &&
+    typeof value.sql === "string" &&
+    typeof value.width === "number" &&
+    DATA_SOURCES.includes(value.source as DataSourceType) &&
+    CHART_TYPES.includes(value.chartType as ChartType) &&
+    (value.config === undefined || isRecord(value.config))
+  );
+}
+
+function isDashboardFilter(value: unknown): value is DashboardFilter {
+  if (
+    !isRecord(value) ||
+    typeof value.id !== "string" ||
+    !value.id ||
+    typeof value.label !== "string" ||
+    !FILTER_TYPES.includes(value.type as DashboardFilter["type"]) ||
+    (value.default !== undefined && typeof value.default !== "string")
+  ) {
+    return false;
+  }
+  return (
+    value.options === undefined ||
+    (Array.isArray(value.options) &&
+      value.options.length <= 100 &&
+      value.options.every(
+        (option) =>
+          isRecord(option) &&
+          typeof option.value === "string" &&
+          typeof option.label === "string",
+      ))
+  );
+}
+
+export function reviewDashboardFilters(
+  value: unknown,
+): DashboardFilter[] | undefined {
+  if (!isRecord(value) || value.filters === undefined) return [];
+  return Array.isArray(value.filters) &&
+    value.filters.length <= 100 &&
+    value.filters.every(isDashboardFilter)
+    ? value.filters
+    : undefined;
+}
+
+export function reviewDashboardVariables(
+  value: unknown,
+): Record<string, string> | undefined {
+  if (!isRecord(value) || value.variables === undefined) return {};
+  if (!isRecord(value.variables)) return undefined;
+  const entries = Object.entries(value.variables);
+  if (
+    entries.length > 100 ||
+    entries.some(([, variable]) => typeof variable !== "string")
+  ) {
+    return undefined;
+  }
+  return Object.fromEntries(entries) as Record<string, string>;
+}
+
+export function firstReviewDashboardPanel(
+  value: unknown,
+): SqlPanel | undefined {
+  if (!isRecord(value) || !Array.isArray(value.panels)) return undefined;
+  const panels = value.panels.filter(isSqlPanel);
+  const byId = new Map(panels.map((panel) => [panel.id, panel]));
+  const preferredIds =
+    isRecord(value.layout) && Array.isArray(value.layout.firstPanelIds)
+      ? value.layout.firstPanelIds.filter(
+          (id): id is string => typeof id === "string",
+        )
+      : [];
+  const preferred = preferredIds.flatMap((id) => {
+    const panel = byId.get(id);
+    return panel ? [panel] : [];
+  });
+  const ordered = [
+    ...preferred,
+    ...panels.filter((panel) => !preferredIds.includes(panel.id)),
+  ];
+  return ordered.find(
+    (panel) => panel.chartType !== "section" && panel.chartType !== "extension",
+  );
+}
+
+export function AnalyticsReviewArtifactPreview({
+  artifactId,
+  compact,
+}: {
+  artifactId: string;
+  compact: boolean;
+}) {
+  const t = useT();
+  const { data, isLoading, isError } = useActionQuery<Record<string, unknown>>(
+    "get-sql-dashboard",
+    { id: artifactId, includeConfig: true },
+    { staleTime: 5 * 60_000 },
+  );
+  const panel = firstReviewDashboardPanel(data);
+  const filters = reviewDashboardFilters(data);
+  const variables = reviewDashboardVariables(data);
+  if (isLoading) {
+    return (
+      <div
+        aria-hidden="true"
+        className={
+          compact
+            ? "size-full animate-pulse bg-muted"
+            : "h-full min-h-64 w-full animate-pulse bg-muted"
+        }
+      />
+    );
+  }
+  if (isError || !panel || !filters || !variables) {
+    return (
+      <div
+        className="flex size-full items-center justify-center bg-muted px-2 text-center text-xs text-muted-foreground"
+        data-preview-state="unavailable"
+        role="status"
+      >
+        {t("settings.reviewPreviewUnavailable")}
+      </div>
+    );
+  }
+
+  const vars = { ...variables, ...resolveFilterVars(filters, () => "") };
+  const resolvedSql = interpolate(serializePanelSql(panel.sql), vars, {
+    failClosedTimeVariables: true,
+  });
+
+  return (
+    <div
+      className={
+        compact
+          ? "pointer-events-none h-[600%] w-[600%] origin-top-left scale-[0.166667] overflow-hidden"
+          : "h-full min-h-64 w-full overflow-hidden"
+      }
+      data-preview-kind="analytics-sql-chart"
+    >
+      <SqlChart
+        panel={panel}
+        resolvedSql={resolvedSql}
+        timeRange={timeRangeDays(vars.timeRange)}
+        dashboardId={artifactId}
+      />
+    </div>
+  );
+}

package/corpus/templates/analytics/app/i18n/en-US.ts

@@ -337,6 +337,8 @@ export default {
     untitledDashboard: "Untitled dashboard",
   },
   settings: {
+    agentObservability: "Agent Observability",
+    reviewPreviewUnavailable: "Preview unavailable",
     agentTitle: "Manage agent",
     agentDescription:
       "Manage the agent's model, API keys, automations, voice, and other controls.",

package/corpus/templates/analytics/app/pages/Settings.tsx

@@ -4,7 +4,9 @@ import {
   useActionQuery,
 } from "@agent-native/core/client/hooks";
 import { LanguagePicker, useT } from "@agent-native/core/client/i18n";
-import { TeamPage } from "@agent-native/core/client/org";
+import { buildSettingsRoute } from "@agent-native/core/client/navigation";
+import { ObservabilityDashboard } from "@agent-native/core/client/observability";
+import { TeamPage, useOrg } from "@agent-native/core/client/org";
 import {
   AccountSettingsCard,
   SettingsGroup,
@@ -18,7 +20,7 @@ import {
   createCreativeContextAgentTab,
   useCreativeContextLab,
 } from "@agent-native/creative-context/client";
-import { IconBell } from "@tabler/icons-react";
+import { IconActivity, IconBell } from "@tabler/icons-react";
 import { useEffect, useMemo, useState } from "react";
 import { Link } from "react-router";
 import { toast } from "sonner";
@@ -31,6 +33,7 @@ import {
   ANALYTICS_USER_PREFS_KEY,
   type AnalyticsUserPrefs,
 } from "../../shared/analytics-user-prefs";
+import { AnalyticsReviewArtifactPreview } from "../components/AnalyticsReviewArtifactPreview";
 import { useReplayStorageStatus } from "../hooks/use-replay-storage-status";
 import { ReplayStorageHint } from "./sessions/SessionsPage";
 import { AlertRulesSettingsCard } from "./settings/AlertRulesSettingsCard";
@@ -40,6 +43,11 @@ export default function Settings() {
   const t = useT();
   const creativeContextEnabled = useCreativeContextLab();
   const replayStorageStatus = useReplayStorageStatus();
+  const {
+    data: activeOrg,
+    isLoading: orgLoading,
+    isError: orgError,
+  } = useOrg();
   const { data: analyticsPrefs, isLoading: analyticsPrefsLoading } =
     useActionQuery<AnalyticsUserPrefs>("get-user-pref", {
       key: ANALYTICS_USER_PREFS_KEY,
@@ -142,6 +150,44 @@ export default function Settings() {
     agentAdditionalContent,
     agentAdditionalTabFactories,
   });
+  const observabilityBasePath = buildSettingsRoute("observability");
+  const observabilityTabs = useMemo<SettingsTabItem[]>(
+    () =>
+      !orgLoading &&
+      !orgError &&
+      activeOrg?.orgId &&
+      (activeOrg.role === "owner" || activeOrg.role === "admin")
+        ? [
+            {
+              id: "observability",
+              label: t("settings.agentObservability"),
+              icon: IconActivity,
+              group: "agent",
+              href: `${observabilityBasePath}/overview`,
+              content: (
+                <ObservabilityDashboard
+                  routeBasePath={observabilityBasePath}
+                  showHumanReview
+                  renderArtifactPreview={(artifact, compact) => (
+                    <AnalyticsReviewArtifactPreview
+                      artifactId={artifact.artifactId}
+                      compact={compact}
+                    />
+                  )}
+                />
+              ),
+            },
+          ]
+        : [],
+    [
+      activeOrg?.orgId,
+      activeOrg?.role,
+      observabilityBasePath,
+      orgError,
+      orgLoading,
+      t,
+    ],
+  );
   const labs = useMemo(
     () => [
       {
@@ -167,8 +213,9 @@ export default function Settings() {
         ),
       },
       ...agentSettingsTabs,
+      ...observabilityTabs,
     ],
-    [agentSettingsTabs, t],
+    [agentSettingsTabs, observabilityTabs, t],
   );
 
   const generalSearchEntries = useMemo(

package/corpus/templates/analytics/changelog/2026-09-25-first-run-onboarding-records-setup-choices-and-builder-conne.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-09-25
+---
+
+First-run onboarding records setup choices and Builder connection outcomes

package/corpus/templates/analytics/changelog/2026-09-25-human-review-previews-analytics-dashboards-as-real-charts.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-09-25
+---
+
+Human review previews Analytics dashboards as real charts

package/corpus/templates/analytics/changelog/2026-09-25-org-admins-can-review-agent-runs-from-settings.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-09-25
+---
+
+Org admins can review agent runs from Settings

package/corpus/templates/analytics/changelog/2026-09-25-proactive-query-context.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-09-25
+---
+
+Relevant metric definitions and saved dashboard examples are available with the first response so Analytics queries can reuse proven definitions and query shapes.