@agent-native/core-corpus 0.210.2 → 0.211.0

package/corpus/templates/analytics/server/lib/dashboard-panel-verification.ts

@@ -38,6 +38,18 @@ import {
   describeError,
   runResolvedPanel,
 } from "./dashboard-panel-runner";
+import {
+  describeReportSchedules,
+  estimateResolvedPanels,
+  formatBytes,
+  formatUsd,
+  QUERY_COST_THRESHOLDS,
+  scheduledDashboardRuns,
+  totalCost,
+  usdForBytes,
+  type PanelCostEstimate,
+  type QueryCostFailure,
+} from "./query-cost-estimate";
 
 export type PanelVerificationStatus =
   | "ok"
@@ -83,6 +95,8 @@ export interface PanelVerification {
   truncated?: boolean;
   error?: string;
   note?: PanelUnverifiedNote;
+  /** The dry run's bytes, kept when they stopped the panel from running (`too_expensive`). */
+  estimatedBytes?: number;
   /** A section or extension panel: nothing to run, so only its config was checked. */
   visualOnly?: true;
   hint?: string;
@@ -144,7 +158,7 @@ const NOTE_REASONS: Record<PanelUnverifiedNote, string> = {
     "its data source is not connected (the viewer sees a connect prompt)",
   "skipped:program": "data-program panels are not run during verification",
   too_expensive:
-    "the dry run is larger than the automatic-verification byte limit",
+    "the dry run is larger than the automatic-verification byte limit, so it was not run",
   "not_executed:over_budget":
     "more panels were affected than the per-save verification cap runs",
 };
@@ -274,6 +288,46 @@ export function touchedPanelIds(
   };
 }
 
+/**
+ * The touched panels whose query changed: new panels, panels that start or
+ * stop running a query (a section turned into a chart), and panels whose
+ * source or resolved SQL differs. Any other chart-type or config edit reads
+ * the same bytes. Compares the first copy of each id, the one the edit API
+ * addresses.
+ */
+function queryChangedPanelIds(
+  rawBase: Record<string, unknown> | null,
+  rawNext: Record<string, unknown>,
+  ids: readonly string[],
+): string[] {
+  const base = rawBase && normalizeDashboardConfig(rawBase);
+  const next = normalizeDashboardConfig(rawNext);
+  const firstCopies = (config: Record<string, unknown> | null) => {
+    const panels = new Map<string, Record<string, unknown>>();
+    for (const panel of config ? panelsOf(config) : []) {
+      if (typeof panel.id === "string" && !panels.has(panel.id)) {
+        panels.set(panel.id, panel);
+      }
+    }
+    return panels;
+  };
+  const before = firstCopies(base);
+  const after = firstCopies(next);
+  const baseVars = base ? resolveVerificationVars(base) : {};
+  const nextVars = resolveVerificationVars(next);
+  return ids.filter((id) => {
+    const was = before.get(id);
+    const now = after.get(id);
+    if (!now) return false;
+    return (
+      !was ||
+      hasSqlToRun(was) !== hasSqlToRun(now) ||
+      was.source !== now.source ||
+      resolvedSqlOf(was, baseVars) !== resolvedSqlOf(now, nextVars)
+    );
+  });
+}
+
 export interface VisualPanelChange {
   panelId: string;
   title: string;
@@ -610,7 +664,11 @@ async function verifyOne(
     dryRun?.totalBytesProcessed !== undefined &&
     dryRun.totalBytesProcessed > state.maxBytes
   ) {
-    return finish({ status: "unverified", note: "too_expensive" });
+    return finish({
+      status: "unverified",
+      note: "too_expensive",
+      estimatedBytes: dryRun.totalBytesProcessed,
+    });
   }
   if (!execute) {
     return finish({ status: "unverified", note: "not_executed:over_budget" });
@@ -955,6 +1013,170 @@ export interface PanelWriteVerdict {
     reason: string;
   }[];
   nextStep?: string;
+  /** What the changed panels cost to refresh; absent when none could be priced. */
+  cost?: PanelWriteCost;
+}
+
+export interface PanelWriteCost {
+  /** Each changed panel's estimate at the dashboard's default filters. */
+  panels: PanelCostEstimate[];
+  total: ReturnType<typeof totalCost> & {
+    /** Some changed panel could not be priced, so the total counts only the rest. */
+    partial: boolean;
+  };
+  runsPerMonth: number | null;
+  runsPerMonthBasis: string;
+}
+
+const MAX_COST_PANELS = 60;
+/** Once verification is done, how much longer a write waits for its price. */
+const COST_GRACE_MS = 3_000;
+const COST_LATE =
+  "Stopped: pricing took longer than the save. Estimate this panel with estimate-query-cost.";
+/** Sources whose panels can bill BigQuery, whether or not they can be priced. */
+const BILLABLE_SOURCES = new Set(["bigquery", "first-party", "program"]);
+
+type WriteCostPanel = ReturnType<typeof resolveDashboardPanelQueries>[number];
+
+/** The first copy of each panel to price, the one the edit API addresses. */
+function writeCostPanels(
+  config: Record<string, unknown>,
+  panelIds: readonly string[],
+): WriteCostPanel[] {
+  if (panelIds.length === 0) return [];
+  const wanted = new Set(panelIds);
+  const seen = new Set<string>();
+  return resolveDashboardPanelQueries(config).filter((panel) => {
+    if (!wanted.has(panel.panelId) || seen.has(panel.panelId)) return false;
+    seen.add(panel.panelId);
+    return true;
+  });
+}
+
+function writeCostOf(
+  estimates: PanelCostEstimate[],
+  runsPerMonth: number | null,
+  runsPerMonthBasis: string,
+): PanelWriteCost {
+  return {
+    panels: estimates,
+    total: {
+      ...totalCost(estimates),
+      partial: estimates.some(
+        (panel) =>
+          panel.status === "failed" || panel.status === "not_estimated",
+      ),
+    },
+    runsPerMonth,
+    runsPerMonthBasis,
+  };
+}
+
+/** Every panel that can bill, marked unpriced; null when none can bill. */
+function unpricedWriteCost(
+  panels: readonly WriteCostPanel[],
+  failure: QueryCostFailure,
+  error: string,
+): PanelWriteCost | null {
+  const billable = panels.filter((panel) => BILLABLE_SOURCES.has(panel.source));
+  if (billable.length === 0) return null;
+  return writeCostOf(
+    billable.map((panel) => ({
+      panelId: panel.panelId,
+      title: panel.title,
+      source: panel.source,
+      status: "failed",
+      failure,
+      error,
+    })),
+    null,
+    "none",
+  );
+}
+
+/** `work`'s result, or undefined if `stop` fires first. */
+function beforeStop<T>(
+  work: Promise<T>,
+  stop: AbortSignal,
+): Promise<T | undefined> {
+  if (stop.aborted) return Promise.resolve(undefined);
+  let onStop: (() => void) | undefined;
+  const stopped = new Promise<undefined>((resolve) => {
+    onStop = () => resolve(undefined);
+    stop.addEventListener("abort", onStop, { once: true });
+  });
+  return Promise.race([work, stopped]).finally(() => {
+    if (onStop) stop.removeEventListener("abort", onStop);
+  });
+}
+
+/**
+ * Prices the panels a write changed with the same free dry runs as
+ * estimate-query-cost, at the default filters a fresh tab shows. Once `late`
+ * fires it settles at once: panels already priced keep their estimates and
+ * the rest go unpriced.
+ */
+async function estimateWriteCost(
+  panels: readonly WriteCostPanel[],
+  dashboardId: string | undefined,
+  signal: AbortSignal,
+  late: AbortSignal,
+): Promise<PanelWriteCost | null> {
+  const scope = getCredentialContext();
+  if (!scope || !dashboardId || panels.length === 0) return null;
+  try {
+    const schedule = await beforeStop(
+      scheduledDashboardRuns(dashboardId, scope),
+      late,
+    );
+    if (!schedule) return unpricedWriteCost(panels, "timeout", COST_LATE);
+    const { reportSchedules, runsPerMonth } = schedule;
+    const estimates = await estimateResolvedPanels(
+      panels.slice(0, MAX_COST_PANELS),
+      scope,
+      runsPerMonth,
+      Date.now() + PANEL_VERIFICATION_BUDGET_MS,
+      signal,
+      { signal: late, error: COST_LATE },
+    );
+    const skipped: PanelCostEstimate[] = panels
+      .slice(MAX_COST_PANELS)
+      .filter((panel) => BILLABLE_SOURCES.has(panel.source))
+      .map((panel) => ({
+        panelId: panel.panelId,
+        title: panel.title,
+        source: panel.source,
+        status: "not_estimated",
+        reason: `One write prices at most ${MAX_COST_PANELS} panels; estimate-query-cost can price this one.`,
+      }));
+    return writeCostOf(
+      [...estimates, ...skipped],
+      runsPerMonth,
+      reportSchedules > 0
+        ? describeReportSchedules(reportSchedules, scope.orgId)
+        : "none",
+    );
+  } catch (error) {
+    // coercion-ok: a failed estimate leaves the save and its verdict as they were; the summary says the panels went unpriced.
+    return unpricedWriteCost(panels, "no_estimate", describeError(error));
+  }
+}
+
+/**
+ * Pricing is informational, so once verification is done an estimate still
+ * running gets COST_GRACE_MS more. Then `late` fires, and the estimate
+ * settles with what it has priced.
+ */
+async function settleWriteCost(
+  pending: Promise<PanelWriteCost | null>,
+  late: AbortController,
+): Promise<PanelWriteCost | null> {
+  const timer = setTimeout(() => late.abort(), COST_GRACE_MS);
+  try {
+    return await pending;
+  } finally {
+    clearTimeout(timer);
+  }
 }
 
 /** One line saying what the viewer sees, or why that could not be checked. */
@@ -969,7 +1191,11 @@ export function describePanelOutcome(panel: PanelVerification): string {
         }`;
   }
   if (panel.status === "unverified") {
-    const why = panel.note ? NOTE_REASONS[panel.note] : "could not be checked";
+    const why = `${panel.note ? NOTE_REASONS[panel.note] : "could not be checked"}${
+      panel.estimatedBytes === undefined
+        ? ""
+        : ` (~${formatBytes(panel.estimatedBytes)}, ${formatUsd(usdForBytes(panel.estimatedBytes))} per refresh)`
+    }`;
     return panel.error ? `${why} (${clipHead(panel.error, 200)})` : why;
   }
   if (panel.status === "empty") {
@@ -1024,6 +1250,23 @@ export async function verifyPanelWrite(
   const visualIds = visual
     .filter((change) => change.change !== "removed")
     .map((change) => change.panelId);
+  // The estimate runs beside verification and stops if the write is refused.
+  const stopEstimate = new AbortController();
+  const costLate = new AbortController();
+  const costPanels = options.dashboardId
+    ? writeCostPanels(
+        next,
+        queryChangedPanelIds(base, next, [...direct, ...affected]),
+      )
+    : [];
+  const pendingCost = estimateWriteCost(
+    costPanels,
+    options.dashboardId,
+    options.signal
+      ? AbortSignal.any([options.signal, stopEstimate.signal])
+      : stopEstimate.signal,
+    costLate.signal,
+  );
   const verification = await verifyDashboardPanels(
     next,
     [...direct, ...affected, ...visualIds],
@@ -1033,13 +1276,17 @@ export async function verifyPanelWrite(
       memo: options.memo,
       serverAuthoredPanelIds: options.serverAuthoredPanelIds,
     },
-  );
+  ).catch((error: unknown) => {
+    stopEstimate.abort();
+    throw error;
+  });
   const allowEmpty = options.allowEmptyResult === true;
   const directIds = new Set([...direct, ...visualIds]);
   const blockers = verification.panels.filter(
     (panel) => directIds.has(panel.panelId) && blocksSave(panel, allowEmpty),
   );
   if (blockers.length > 0 && options.mode !== "report") {
+    stopEstimate.abort();
     fail(formatVerificationFailure(blockers), {
       errorCode: "dashboard_panel_verification_failed",
       statusCode: 422,
@@ -1064,9 +1311,11 @@ export async function verifyPanelWrite(
       .slice(0, 5)
       .map((panel) => panel.panelId)
       .join(", ")}${panels.length > 5 ? ` (+${panels.length - 5} more)` : ""}`;
+  const cost = await settleWriteCost(pendingCost, costLate);
   return {
     verified,
     ...(visual.length > 0 ? { visualOnly: visual } : {}),
+    ...(cost ? { cost } : {}),
     verification,
     proof: verification.panels
       .filter((panel) => panel.rowCount !== null)
@@ -1123,9 +1372,52 @@ export function verdictFields(
       ? { unverified: verdict.unverified }
       : {}),
     ...(verdict.nextStep ? { nextStep: verdict.nextStep } : {}),
+    ...(verdict.cost ? { cost: verdict.cost } : {}),
   };
 }
 
+/**
+ * "Cost of ...: ~X · $Y per refresh · ~$Z/month ...", or empty when no
+ * changed panel reads BigQuery. Over a threshold it tells the agent to say so.
+ */
+export function describeWriteCost(verdict: PanelWriteVerdict): string {
+  const cost = verdict.cost;
+  if (!cost) return "";
+  const priced = cost.panels.filter((panel) => panel.status === "estimated");
+  const unpriced = cost.panels.filter(
+    (panel) => panel.status === "failed" || panel.status === "not_estimated",
+  ).length;
+  if (priced.length === 0) {
+    return unpriced > 0
+      ? `Cost: ${unpriced} changed panel(s) could not be priced; estimate-query-cost says why.`
+      : "";
+  }
+  const { total } = cost;
+  const subject =
+    priced.length === 1
+      ? `"${priced[0].title}"`
+      : `the ${priced.length} changed panels that read BigQuery`;
+  const monthly =
+    total.usdPerMonth === null
+      ? "no email reports scheduled"
+      : `~${formatUsd(total.usdPerMonth)}/month for ${cost.runsPerMonthBasis}`;
+  const over = [
+    total.overPerRunThreshold &&
+      `the ${formatUsd(QUERY_COST_THRESHOLDS.perRunUsd)}/run`,
+    total.overPerMonthThreshold &&
+      `the ${formatUsd(QUERY_COST_THRESHOLDS.perMonthUsd)}/month`,
+  ].filter(Boolean);
+  return [
+    `Cost of ${subject} at default filters: ~${formatBytes(total.estimatedBytes)} · ${formatUsd(total.usdPerRun)} per refresh · ${monthly}.`,
+    unpriced > 0 ? `${unpriced} more could not be priced.` : "",
+    over.length > 0
+      ? `That is over ${over.join(" and ")} threshold; tell the user this cost.`
+      : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
 /** Says the viewer-visible edits no data check covered; empty when the edit touched no section or extension panel. */
 export function describeVisualOnly(verdict: PanelWriteVerdict): string {
   const changes = verdict.visualOnly ?? [];
@@ -1157,11 +1449,14 @@ export function annotateSummary(
       shown.length > 0
         ? `Verified: ${shown.join("; ")}${more > 0 ? ` (+${more} more)` : ""}.`
         : "No data panel was affected.";
-    return [summary, checked, visual].filter(Boolean).join(" ");
+    return [summary, checked, visual, describeWriteCost(verdict)]
+      .filter(Boolean)
+      .join(" ");
   }
   return [
     `${options.saved === false ? "NOT VERIFIED" : "SAVED BUT NOT VERIFIED"}: ${summary} ${verdict.nextStep}`,
     visual,
+    describeWriteCost(verdict),
   ]
     .filter(Boolean)
     .join(" ");

package/corpus/templates/analytics/server/lib/dashboard-seeds.ts

@@ -3,12 +3,14 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import firstPartyTemplateTrafficSeed from "../../seeds/dashboards/agent-native-templates-first-party.json" with { type: "json" };
+import contentViewSeed from "../../seeds/dashboards/content-view.json" with { type: "json" };
 import googleAnalyticsSeed from "../../seeds/dashboards/google-analytics.json" with { type: "json" };
 import nodeExporterFullSeed from "../../seeds/dashboards/node-exporter-full.json" with { type: "json" };
 import skillsCliFunnelSeed from "../../seeds/dashboards/skills-cli-funnel.json" with { type: "json" };
 import { isSafeDashboardId } from "./dashboard-id";
 
 const shippedSeeds: Record<string, Record<string, unknown>> = {
+  "content-view": contentViewSeed as Record<string, unknown>,
   "agent-native-templates-first-party": firstPartyTemplateTrafficSeed as Record<
     string,
     unknown

package/corpus/templates/analytics/server/lib/dashboards-store.ts

@@ -929,6 +929,34 @@ export async function loadAccessibleDashboardMetadataByIds(
     );
 }
 
+/**
+ * Owners of dashboards in one org, without a sharing check. Use it only to
+ * name who to ask for access; never return a title or config from it.
+ */
+export async function loadOrgDashboardOwnersByIds(
+  orgId: string,
+  ids: readonly string[],
+): Promise<Array<{ id: string; kind: DashboardKind; ownerEmail: string }>> {
+  const uniqueIds = [
+    ...new Set(ids.map((id) => id.trim()).filter(Boolean)),
+  ].slice(0, MAX_DASHBOARD_METADATA_HYDRATION);
+  if (!uniqueIds.length) return [];
+
+  return getDb()
+    .select({
+      id: schema.dashboards.id,
+      kind: schema.dashboards.kind,
+      ownerEmail: schema.dashboards.ownerEmail,
+    })
+    .from(schema.dashboards)
+    .where(
+      and(
+        eq(schema.dashboards.orgId, orgId),
+        inArray(schema.dashboards.id, uniqueIds),
+      ),
+    );
+}
+
 export type DashboardReviewScope =
   | { kind: "organization"; orgId: string }
   | { kind: "super-organization"; orgId: string };

package/corpus/templates/analytics/server/lib/first-party-analytics-backend.ts

@@ -1510,24 +1510,139 @@ function httpResponseExclusionEnd(
   }
 }
 
+type ConditionTokens = {
+  tokens: AgentSqlToken[];
+  depths: number[];
+  sourceName: string;
+};
+
+function widensCondition(tokens: AgentSqlToken[], index: number): boolean {
+  const token = tokens[index];
+  return (
+    isWord(token, "or") ||
+    isWord(token, "case") ||
+    (isWord(token, "not") && !isWord(tokens[index - 1], "is"))
+  );
+}
+
+/** Whether some AND conjunct of tokens [from, to) at `level` drops every `http.response` row. */
+function conjunctionExcludesHttpResponse(
+  condition: ConditionTokens,
+  from: number,
+  to: number,
+  level: number,
+): boolean {
+  let start = from;
+  let between = false;
+  for (let index = from; index <= to; index++) {
+    if (index < to) {
+      if (condition.depths[index] !== level) continue;
+      const token = condition.tokens[index];
+      if (isWord(token, "between")) between = true;
+      if (!isWord(token, "and")) continue;
+      // BETWEEN's own AND joins its bounds, not two conditions.
+      if (between) {
+        between = false;
+        continue;
+      }
+    }
+    if (conjunctExcludesHttpResponse(condition, start, index, level)) {
+      return true;
+    }
+    start = index + 1;
+  }
+  return false;
+}
+
+function conjunctExcludesHttpResponse(
+  condition: ConditionTokens,
+  from: number,
+  to: number,
+  level: number,
+): boolean {
+  const { tokens, depths } = condition;
+  if (
+    to - from >= 2 &&
+    tokens[from].text === "(" &&
+    tokens[to - 1].text === ")"
+  ) {
+    // A subquery's event_name belongs to its own FROM, not to this source.
+    if (
+      isWord(tokens[from + 1], "select") ||
+      isWord(tokens[from + 1], "with")
+    ) {
+      return false;
+    }
+    for (let index = from + 1; index < to - 1; index++) {
+      if (depths[index] <= level) return false;
+    }
+    return groupExcludesHttpResponse(condition, from + 1, to - 1, level + 1);
+  }
+  const column = tokens[from + 1]?.text === "." ? from + 2 : from;
+  return (
+    isEventNameColumn(tokens, column, condition.sourceName) &&
+    httpResponseExclusionEnd(tokens, column) === to
+  );
+}
+
+// A parenthesized condition excludes `http.response` only when every OR
+// branch does: one branch without an event restriction readmits it.
+function groupExcludesHttpResponse(
+  condition: ConditionTokens,
+  from: number,
+  to: number,
+  level: number,
+): boolean {
+  let start = from;
+  for (let index = from; index <= to; index++) {
+    if (index < to) {
+      if (condition.depths[index] !== level) continue;
+      if (!isWord(condition.tokens[index], "or")) {
+        if (widensCondition(condition.tokens, index)) return false;
+        continue;
+      }
+    }
+    if (!conjunctionExcludesHttpResponse(condition, start, index, level)) {
+      return false;
+    }
+    start = index + 1;
+  }
+  return true;
+}
+
 /**
  * The model omits every `http.response` row, so a read can move to it only
  * when its own WHERE provably drops them: a top-level conjunct on
- * `event_name`, with no OR or NOT in that WHERE that could let them back in.
- * An unfiltered count or an `event_name` breakdown would otherwise lose those
- * rows without any sign the number changed.
+ * `event_name`, or a parenthesized OR whose every branch has one. ANDed
+ * conditions only narrow, so OR and NOT may appear inside any other
+ * parenthesized conjunct, but an OR, NOT, or CASE at the WHERE's own level
+ * could let `http.response` back in. An unfiltered count or an
+ * `event_name` breakdown would otherwise lose those rows without any sign the
+ * number changed.
  */
 function eventsReadsIneligibility(
   sql: string,
 ): "reads_no_events" | "http_response_not_excluded" | null {
   const query = readAgentSqlQuery(sql, { dialect: "bigquery" });
   const { tokens } = query;
+  // A pipe stage filters an earlier stage's result, so its WHERE says nothing
+  // about which rows the source fed in.
+  if (
+    tokens.some(
+      (token, index) =>
+        token.text === "|>" ||
+        (token.text === "|" && tokens[index + 1]?.text === ">"),
+    )
+  ) {
+    return "http_response_not_excluded";
+  }
   const depths: number[] = [];
   let depth = 0;
+  // Array brackets nest expressions just as parentheses do.
   for (const token of tokens) {
-    if (token.text === ")") depth--;
+    if (token.text === ")" || token.text === "]") depth--;
     depths.push(depth);
-    if (token.text === "(") depth++;
+    if (token.text === "(" || token.text === "[") depth++;
   }
   const tokenIndex = new Map(
     tokens.map((token, index) => [token.start, index]),
@@ -1558,28 +1673,17 @@ function eventsReadsIneligibility(
       where++;
     }
     if (atLevelEnd(where)) return "http_response_not_excluded";
-    let excluded = false;
-    for (let index = where + 1; !atLevelEnd(index); index++) {
-      const token = tokens[index];
-      if (isWord(token, "or")) return "http_response_not_excluded";
-      if (isWord(token, "not") && !isWord(tokens[index - 1], "is")) {
+    let end = where + 1;
+    while (!atLevelEnd(end)) end++;
+    for (let index = where + 1; index < end; index++) {
+      if (depths[index] === level && widensCondition(tokens, index)) {
         return "http_response_not_excluded";
       }
-      if (
-        depths[index] !== level ||
-        !isEventNameColumn(tokens, index, sourceName)
-      ) {
-        continue;
-      }
-      const column = tokens[index - 1]?.text === "." ? index - 2 : index;
-      const before = tokens[column - 1];
-      if (!isWord(before, "where") && !isWord(before, "and")) continue;
-      const end = httpResponseExclusionEnd(tokens, index);
-      if (end !== -1 && (atLevelEnd(end) || isWord(tokens[end], "and"))) {
-        excluded = true;
-      }
     }
-    if (!excluded) return "http_response_not_excluded";
+    const condition = { tokens, depths, sourceName };
+    if (!conjunctionExcludesHttpResponse(condition, where + 1, end, level)) {
+      return "http_response_not_excluded";
+    }
   }
   return null;
 }