@agent-native/core 0.131.9 → 0.132.0

package/corpus/core/src/server/poll.ts

@@ -442,6 +442,12 @@ export class AppSyncState {
   private lastExtensionsUpdatedAt: string | number | undefined;
   private lastExtensionMarkerTs = 0;
   private lastActionMarkerTs = 0;
+  /**
+   * Set by the seed when a durable action marker predates this process, so the
+   * first `doCheckExternalDbChanges` reads the marker rows even though the
+   * MAX(updated_at) probe cannot distinguish that row from the seeded max.
+   */
+  private replayActionMarkerOnce = false;
 
   /**
    * Tracks the latest updated_at seen on the `__screen_refresh__` key.
@@ -1355,6 +1361,7 @@ export class AppSyncState {
       // performed by a separate action process. Do not baseline past an existing
       // marker on cold start, or the first poll after the action will miss it.
       this.lastActionMarkerTs = 0;
+      this.replayActionMarkerOnce = actionMarkerTs > 0;
       this.lastScreenRefreshTs = refreshTs;
       this.lastScreenRefreshTsBySession.clear();
       for (const row of refreshResult.rows) {
@@ -1416,28 +1423,54 @@ export class AppSyncState {
       // concurrently to shave stacked latency; results are still processed in
       // the original sequential order, and conditional follow-up queries stay
       // sequential within their branch.
+      //
+      // `lastAppStateTs` is maintained as MAX(updated_at) over the whole
+      // `application_state` table (seeded in `seedVersionFromDb`, advanced by
+      // the scan below over every key, not just the ones that emit events).
+      // The application-state row scan and screen/extension marker reads only
+      // report rows strictly newer than a watermark that is itself <=
+      // `lastAppStateTs`, so an unadvanced MAX proves those reads are no-ops.
+      // The action marker keeps its own max probe because its watermark must
+      // remain independent under cross-process clock skew.
       const [
-        appResult,
+        appStateMaxTs,
         actionMarkerTs,
-        refreshResult,
-        extensionMarkerTs,
         settingsTs,
         extensionsMaxUpdatedAt,
       ] = await Promise.all([
-        db.execute({
-          sql: "SELECT session_id, key, updated_at FROM application_state WHERE updated_at > ? ORDER BY updated_at ASC",
-          args: [this.lastAppStateTs],
-        }),
+        readMaxUpdatedAt(db, "application_state"),
         readActionMarkerMaxUpdatedAt(db),
-        db.execute({
-          sql: "SELECT session_id, updated_at, value FROM application_state WHERE key = ?",
-          args: [SCREEN_REFRESH_KEY],
-        }),
-        readExtensionMarkerMaxUpdatedAt(db),
         readMaxUpdatedAt(db, "settings"),
         readMaxUpdatedAtRaw(db, "tools"),
       ]);
 
+      // The seed deliberately rewinds `lastActionMarkerTs` to 0 so a marker
+      // written before this process booted still reaches the first poll. That
+      // replay is invisible to the MAX probe (the row is already counted in the
+      // seeded max), so it gets one forced full read.
+      const replayActionMarker = this.replayActionMarkerOnce;
+      this.replayActionMarkerOnce = false;
+      const appStateChanged =
+        appStateMaxTs > this.lastAppStateTs || replayActionMarker;
+
+      const [appResult, refreshResult, extensionMarkerTs] = appStateChanged
+        ? await Promise.all([
+            db.execute({
+              sql: "SELECT session_id, key, updated_at FROM application_state WHERE updated_at > ? ORDER BY updated_at ASC",
+              args: [this.lastAppStateTs],
+            }),
+            db.execute({
+              sql: "SELECT session_id, updated_at, value FROM application_state WHERE key = ?",
+              args: [SCREEN_REFRESH_KEY],
+            }),
+            readExtensionMarkerMaxUpdatedAt(db),
+          ])
+        : ([
+            { rows: [] as Record<string, unknown>[] },
+            null,
+            this.lastExtensionMarkerTs,
+          ] as const);
+
       // Check application_state for external writes. Preserve the changed key so
       // clients can invalidate one-shot command queries (`navigate`, `__set_url__`)
       // only when those command rows actually change; noisy keys such as
@@ -1497,54 +1530,59 @@ export class AppSyncState {
       // tool writes to application_state under a well-known key; when its
       // updated_at bumps, emit a distinct event so the client invalidates
       // all queries (not just the ones matching its default queryKey prefix).
-      const refreshTs = refreshResult.rows.reduce(
-        (max, row) => Math.max(max, timestampValue(row.updated_at)),
-        0,
-      );
-      if (!this.screenRefreshInitialized) {
-        this.lastScreenRefreshTs = refreshTs;
-        for (const row of refreshResult.rows) {
-          if (typeof row.session_id === "string") {
-            this.lastScreenRefreshTsBySession.set(
-              row.session_id,
-              timestampValue(row.updated_at),
-            );
-          }
-        }
-        this.screenRefreshInitialized = true;
-      } else if (refreshTs > this.lastScreenRefreshTs) {
-        // Emit a per-user event only for the session(s) whose row actually
-        // advanced, scoped with `owner` so canSeeChangeForUser delivers it only
-        // to that user — not every authenticated poller.
-        for (const row of refreshResult.rows) {
-          const owner =
-            typeof row.session_id === "string" ? row.session_id : undefined;
-          if (!owner) continue;
-          const rowTs = timestampValue(row.updated_at);
-          if (rowTs <= (this.lastScreenRefreshTsBySession.get(owner) ?? 0)) {
-            continue;
+      // `refreshResult` is null exactly when the MAX probe proved no
+      // application_state row moved, which is also exactly when this block
+      // could not emit anything.
+      if (refreshResult) {
+        const refreshTs = refreshResult.rows.reduce(
+          (max, row) => Math.max(max, timestampValue(row.updated_at)),
+          0,
+        );
+        if (!this.screenRefreshInitialized) {
+          this.lastScreenRefreshTs = refreshTs;
+          for (const row of refreshResult.rows) {
+            if (typeof row.session_id === "string") {
+              this.lastScreenRefreshTsBySession.set(
+                row.session_id,
+                timestampValue(row.updated_at),
+              );
+            }
           }
-          let scope: string | undefined;
-          try {
-            const raw = row.value;
-            if (typeof raw === "string") {
-              const parsed = JSON.parse(raw);
-              if (typeof parsed?.scope === "string") scope = parsed.scope;
+          this.screenRefreshInitialized = true;
+        } else if (refreshTs > this.lastScreenRefreshTs) {
+          // Emit a per-user event only for the session(s) whose row actually
+          // advanced, scoped with `owner` so canSeeChangeForUser delivers it only
+          // to that user — not every authenticated poller.
+          for (const row of refreshResult.rows) {
+            const owner =
+              typeof row.session_id === "string" ? row.session_id : undefined;
+            if (!owner) continue;
+            const rowTs = timestampValue(row.updated_at);
+            if (rowTs <= (this.lastScreenRefreshTsBySession.get(owner) ?? 0)) {
+              continue;
             }
-          } catch {}
-          this.recordChange(
-            {
-              source: "screen-refresh",
-              type: "change",
-              key: SCREEN_REFRESH_KEY,
-              owner,
-              ...(scope ? { scope } : {}),
-            },
-            { dedupeKey: `screen-refresh|${rowTs}` },
-          );
-          this.lastScreenRefreshTsBySession.set(owner, rowTs);
+            let scope: string | undefined;
+            try {
+              const raw = row.value;
+              if (typeof raw === "string") {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed?.scope === "string") scope = parsed.scope;
+              }
+            } catch {}
+            this.recordChange(
+              {
+                source: "screen-refresh",
+                type: "change",
+                key: SCREEN_REFRESH_KEY,
+                owner,
+                ...(scope ? { scope } : {}),
+              },
+              { dedupeKey: `screen-refresh|${rowTs}` },
+            );
+            this.lastScreenRefreshTsBySession.set(owner, rowTs);
+          }
+          this.lastScreenRefreshTs = refreshTs;
         }
-        this.lastScreenRefreshTs = refreshTs;
       }
 
       // Extension mutations write a durable marker row so delete and hide/unhide

package/corpus/core/src/server/voice-providers-status.ts

@@ -22,6 +22,7 @@ import {
 import { getOrgContext } from "../org/context.js";
 import { getSession } from "./auth.js";
 import {
+  prefetchSecrets,
   resolveHasCompleteBuilderConnection,
   resolveSecret,
 } from "./credential-provider.js";
@@ -74,10 +75,14 @@ export function createVoiceProvidersStatusHandler() {
     async function hasKey(key: string): Promise<boolean> {
       try {
         if (key === "GOOGLE_APPLICATION_CREDENTIALS") {
-          const resolved = await resolveGoogleRealtimeCredentials({
-            userEmail: session?.email,
-            orgId: orgCtx?.orgId ?? undefined,
-          });
+          // Same identity, passed explicitly — the context is here only so this
+          // scope sweep shares the prefetched per-request memo below.
+          const resolved = await withRequestContext(() =>
+            resolveGoogleRealtimeCredentials({
+              userEmail: session?.email,
+              orgId: orgCtx?.orgId ?? undefined,
+            }),
+          );
           return typeof resolved === "string" && resolved.length > 0;
         }
         const resolved = await withRequestContext(() => resolveSecret(key));
@@ -87,6 +92,16 @@ export function createVoiceProvidersStatusHandler() {
       }
     }
 
+    // One read per scope for every key below, instead of one per key per scope.
+    await withRequestContext(() =>
+      prefetchSecrets([
+        "GEMINI_API_KEY",
+        "OPENAI_API_KEY",
+        "GROQ_API_KEY",
+        "GOOGLE_APPLICATION_CREDENTIALS",
+      ]),
+    );
+
     let builder = false;
     try {
       builder =

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 ?? [],
+      })),
+    })),
+  }),
+});