@agent-native/core-corpus 0.221.0 → 0.221.1-nightly-20261028032829

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 14961
+- template files: 15033

package/corpus/templates/analytics/.agents/skills/first-touch-radar/SKILL.md

@@ -10,8 +10,10 @@ scope: dev
 
 1. Run `pnpm --filter analytics radar:watch --window daily` and read both the
    JSON and Markdown under `.tmp/first-touch-radar/runs/`.
-2. Treat exit 0 as clear, exit 1 as one or more fired checks, and exit 2 as
-   incomplete evidence. Never turn a missing source or failed query into zero.
+2. Treat exit 0 as clear, exit 1 as a fired, unavailable, or insufficient
+   check needing attention, and exit 2 as a run that could not complete. Keep
+   unavailable and insufficient metrics explicit; never turn missing evidence
+   into zero or a pass.
 3. On a fire, run `pnpm --filter analytics radar:triage` and inspect the
    outcome-ranked sessions. Use `metric-watch` and `replay-triage` for details.
 4. For a weekly review, run `pnpm --filter analytics radar:report --week
@@ -24,18 +26,21 @@ scope: dev
    report-wide cap, and treat a reached cap as incomplete evidence.
 5. Run `feedback-ingest` for Slack themes. Searches are read-only and begin at
    the saved watermark.
-6. Send one Telegram to Steve only when a check fired or the weekly report is
-   ready. Include counts and the private run-file path. Send nothing on a quiet
-   day. Never send Slack or email.
-7. Keep recipient emails and prompt text out of logs, reports, Telegram, and
-   commits. The campaign check reads its mode-0600 recipient file in memory and
-   emits aggregate counts only. With a PostgreSQL sink, recipient identifiers
-   are parameters to the read-only query and caching is disabled. A BigQuery
-   sink cannot run campaign follow-up until a keyed recipient matching
-   function is configured; report it as incomplete rather than treating it as
-   zero. Unknown signup campaign labels are grouped as `other`. Anonymous
-   landings cannot be assigned to a recipient; do not interpret identified
-   counts as a complete click total.
+6. Send one Telegram to Steve only when a check fired, is unavailable or is
+   insufficient, or the weekly report is ready. Include counts and the private
+   run-file path. Send nothing on a quiet day. Never send Slack or email.
+7. Keep recipient emails, HMAC keys, and prompt text out of logs, reports,
+   Telegram, and commits. The campaign check reads its mode-0600 recipient file
+   in memory, binds keyed email digests as query parameters, disables local and
+   BigQuery result caching, and emits aggregate counts only. BigQuery matching
+   requires `ANALYTICS_RADAR_CAMPAIGN_HMAC_KEY` and a configured
+   `ANALYTICS_RADAR_CAMPAIGN_HMAC_FUNCTION` backed by the same secret server-side.
+   The function accepts a normalized email and returns lowercase hex
+   `HMAC_SHA256`; keep its key in Secret Manager and never pass the key to
+   BigQuery. When either setting is missing, keep the campaign check
+   unavailable. Unknown signup campaign labels are grouped as `other`.
+   Anonymous landings cannot be assigned to a recipient; do not interpret
+   identified counts as a complete click total.
 8. This radar changes scripts and skills only. Do not make user-visible UI
    changes. If UI work becomes necessary, stop that scope and request Steve's
    screenshot approval before implementing it.

package/corpus/templates/analytics/.agents/skills/metric-watch/SKILL.md

@@ -11,10 +11,13 @@ scope: dev
 - Run `pnpm --filter analytics radar:watch --window daily`; use `--window
   hourly` for provisioning and environment-key checks.
 - Read the check status, numerator, denominator, seven-day comparison, and
-  coverage. `insufficient` is not a pass, and `unavailable` means the run exits
-  2.
+  coverage. `insufficient` is not a pass. `unavailable` and `insufficient`
+  remain explicit and make a completed watch exit 1; exit 2 means the run could
+  not complete.
 - Compare daily thresholds with the incident window and an ordinary week before
   changing them. Record both windows and the observed counts in the PR or report.
+- Use `pnpm --filter analytics radar:backtest` to compare the Oct 9–23 incident
+  window with the Oct 2–8 clean week.
 - Action success uses a weighted `action.response` rate. Keep its app-specific
   threshold below the quiet-week distribution; do not copy the 95% starting
   value without a backtest.

package/corpus/templates/analytics/.deploy-tmp/agent-native-provided-plugins.mjs

@@ -0,0 +1,10 @@
+// AUTO-GENERATED by @agent-native/core deploy build
+import { markDefaultPluginProvided } from "@agent-native/core/server/edge";
+
+const pluginStems = ["agent-chat","analytics-alert-jobs","analytics-rollup-backfill-jobs","auth","collab","config","content-metrics-collection-jobs","core-routes","creative-context","dashboard-report-jobs","db","feature-flags","labs","onboarding","otel","session-replay-retention-jobs","transactional-emails","uptime-monitor-jobs"];
+
+export default function markBuildDiscoveredPlugins(nitroApp) {
+  for (const stem of pluginStems) {
+    markDefaultPluginProvided(nitroApp, stem);
+  }
+}

package/corpus/templates/analytics/actions/open-traffic-dashboard.ts

@@ -15,6 +15,7 @@ function trafficDashboardDeepLink(): string {
 }
 
 export default defineAction({
+  mcpTool: true,
   description:
     "Open the first-party traffic dashboard in the real Analytics app. Use this directly when the user asks to see their traffic dashboard, site traffic, app traffic, or first-party analytics dashboard inline in ChatGPT or Claude. Do not call view-screen, ask_app, or broad resource discovery first for this known dashboard.",
   schema: z.object({}),

package/corpus/templates/analytics/changelog/2026-10-22-outside-assistants-can-open-the-traffic-dashboard-inside-the.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-10-22
+---
+
+Outside assistants can open the Traffic dashboard in Analytics.

package/corpus/templates/analytics/package.json

@@ -16,9 +16,13 @@
     "journey:capture": "tsx scripts/journey-capture.ts",
     "radar:query": "tsx scripts/radar/query.ts",
     "radar:watch": "tsx scripts/radar/watch.ts",
+    "radar:live-watch": "tsx scripts/first-touch-radar-live.ts watch",
     "radar:triage": "tsx scripts/radar/triage.ts",
     "radar:ab": "tsx scripts/radar/ab.ts",
+    "radar:live-ab": "tsx scripts/first-touch-radar-live.ts ab",
     "radar:report": "tsx scripts/radar/report.ts",
+    "radar:live-report": "tsx scripts/first-touch-radar-live.ts report",
+    "radar:backtest": "tsx scripts/first-touch-radar-live.ts backtest",
     "journey:snapshot": "tsx scripts/journey-snapshot.ts",
     "source-index": "tsx scripts/build-source-index.ts",
     "backfill:first-party-bigquery": "tsx scripts/first-party-analytics-bigquery-backfill.ts",

package/corpus/templates/analytics/scripts/first-touch-radar-live.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  runAbReadout,
+  formatAbMarkdown,
+  parseAbReadoutArgs,
+} from "./radar/ab.ts";
+import {
+  formatRadarBacktest,
+  parseRadarBacktestArgs,
+  runRadarBacktest,
+} from "./radar/backtest.ts";
+import { liveDatabaseUrlFromEnv } from "./radar/live.ts";
+import {
+  REPO_ROOT,
+  RadarQueryError,
+  configureRadarRuntimeEnvironment,
+  closeRadarQueries,
+  radarRunCliExitCode,
+} from "./radar/query.ts";
+import {
+  buildWeeklyReport,
+  formatWeeklyMarkdown,
+  parseReportArgs,
+  writeWeeklyReport,
+} from "./radar/report.ts";
+import { parseWatchArgs, runWatch, writeWatchRun } from "./radar/watch.ts";
+
+function loadLiveDatabaseUrl(): void {
+  const configuredFile = process.env.ANALYTICS_RADAR_ENV_FILE;
+  const envFile = path.resolve(
+    REPO_ROOT,
+    configuredFile ?? "templates/analytics/.env",
+  );
+  let contents: string;
+  try {
+    contents = fs.readFileSync(envFile, "utf8");
+  } catch {
+    throw new RadarQueryError(
+      "Live radar environment file could not be read.",
+      2,
+    );
+  }
+  configureRadarRuntimeEnvironment({
+    selectedFile: envFile,
+    contents,
+    databaseUrl: liveDatabaseUrlFromEnv(contents),
+  });
+}
+
+async function main(): Promise<void> {
+  try {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || !["watch", "report", "ab", "backtest"].includes(command)) {
+      throw new RadarQueryError(
+        "Usage: radar:live-watch [watch options], radar:live-report [report options], radar:live-ab [A/B options], or radar:backtest [--max-total-gb N].",
+        2,
+      );
+    }
+    loadLiveDatabaseUrl();
+
+    if (command === "watch") {
+      const run = await runWatch(parseWatchArgs(args));
+      const paths = await writeWatchRun(run);
+      console.log(JSON.stringify({ ...paths, exitCode: run.exitCode }));
+      process.exitCode = run.exitCode;
+    } else if (command === "report") {
+      const { week, skipJourneySnapshot, maxTotalGb, freshBigQuery } =
+        parseReportArgs(args);
+      if (!week) {
+        throw new RadarQueryError(
+          "Usage: radar:live-report --week YYYY-MM-DD [--max-total-gb N]",
+          2,
+        );
+      }
+      const report = await buildWeeklyReport(week, {
+        skipJourneySnapshot,
+        maxTotalGb,
+        freshBigQuery,
+      });
+      const paths = await writeWeeklyReport(report);
+      console.log(formatWeeklyMarkdown(report));
+      console.log(JSON.stringify({ ...paths, exitCode: report.exitCode }));
+      process.exitCode = report.exitCode;
+    } else if (command === "ab") {
+      const result = await runAbReadout(parseAbReadoutArgs(args));
+      console.log(formatAbMarkdown(result));
+      console.log(JSON.stringify(result));
+    } else {
+      const result = await runRadarBacktest(parseRadarBacktestArgs(args));
+      console.log(formatRadarBacktest(result));
+    }
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "Live radar could not run.",
+    );
+    process.exitCode = radarRunCliExitCode(error);
+  } finally {
+    await closeRadarQueries();
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  await main();
+}

package/corpus/templates/analytics/scripts/radar/ab.ts

@@ -133,6 +133,16 @@ export function buildPostgresAbSql(): string {
 export function buildBigQueryAbSql(eventsTableRange: string): string {
   const cte = bigQueryFirstTouchEventsCte(eventsTableRange, {
     includeAllApps: true,
+    columns: {
+      id: true,
+      eventDate: false,
+      sessionId: false,
+      url: false,
+      personKey: true,
+      identityEmail: false,
+      referralSource: false,
+      properties: true,
+    },
   });
   return `${cte},
 experiment_events AS (

package/corpus/templates/analytics/scripts/radar/backtest.ts

@@ -0,0 +1,399 @@
+import {
+  RadarQueryError,
+  resolveRadarBigQueryEventsTable,
+  resolveRadarFirstPartyBackend,
+  resolveRadarOrganizationId,
+  getRadarBigQueryScanBudget,
+  runBigQuery,
+  setRadarBigQueryScanBudget,
+} from "./query.ts";
+import {
+  buildBigQueryEventStatsSql,
+  buildBigQueryUploadRejectionSql,
+} from "./warehouse-sql.ts";
+import {
+  createEventChecks,
+  loadUploadRejectionRows,
+  uploadRejectionCheck,
+} from "./watch.ts";
+
+interface BacktestWindow {
+  start: string;
+  end: string;
+}
+
+interface Observation {
+  check: string;
+  app: string;
+  period: string;
+  status: string;
+  numerator: number | null;
+  denominator: number | null;
+  value: number | null;
+  detail: string | null;
+}
+
+export interface RadarBacktestResult {
+  incident: BacktestWindow;
+  clean: BacktestWindow;
+  observations: Observation[];
+  scanEstimateGb: number;
+  maxTotalGb: number;
+}
+
+export interface RadarBacktestOptions {
+  maxTotalGb?: number;
+}
+
+export const DEFAULT_BACKTEST_MAX_TOTAL_GB = 100;
+
+const INCIDENT: BacktestWindow = {
+  start: "2026-10-09",
+  end: "2026-10-23",
+};
+const CLEAN: BacktestWindow = { start: "2026-10-02", end: "2026-10-08" };
+const TRACKED_CHECKS = new Set([
+  "builder-connect-success",
+  "env-key-share",
+  "ai-connection-none",
+  "replay-upload-rejection",
+]);
+const BACKTEST_EVENT_NAMES = [
+  "signup",
+  "builder_connect_succeeded",
+  "builder connect succeeded",
+  "builder_connect_failed",
+  "builder connect failed",
+  "generation_started",
+  "design_prompt_submitted",
+] as const;
+
+function addDays(date: string, amount: number): string {
+  const result = new Date(`${date}T00:00:00.000Z`);
+  result.setUTCDate(result.getUTCDate() + amount);
+  return result.toISOString().slice(0, 10);
+}
+
+function dateOf(value: unknown): string {
+  if (value instanceof Date) return value.toISOString().slice(0, 10);
+  const text = String(value ?? "");
+  const parsed = new Date(
+    text.includes("T") ? text : `${text.replace(" ", "T")}Z`,
+  );
+  return Number.isFinite(parsed.getTime())
+    ? parsed.toISOString().slice(0, 10)
+    : text.slice(0, 10);
+}
+
+export function backtestHourOf(value: unknown): string {
+  if (value instanceof Date) return value.toISOString().slice(0, 13);
+  const text = String(value ?? "").replace(" ", "T");
+  return text.slice(0, 13);
+}
+
+export function noReplayRejectionObservation(
+  date: string,
+  app: string,
+  label: "clean" | "incident",
+): Observation {
+  return {
+    check: "replay-upload-rejection",
+    app,
+    period: `${label}:${date}`,
+    status: "insufficient",
+    numerator: 0,
+    denominator: null,
+    value: null,
+    detail: `No replay upload rejection events establish recorder coverage for ${app} on ${date}.`,
+  };
+}
+
+export function parseRadarBacktestArgs(args: readonly string[]): {
+  maxTotalGb: number;
+} {
+  let maxTotalGb = DEFAULT_BACKTEST_MAX_TOTAL_GB;
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== "--max-total-gb") {
+      throw new RadarQueryError(`Unknown argument: ${args[index]}`, 2);
+    }
+    const value = Number(args[index + 1]);
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new RadarQueryError("--max-total-gb must be positive.", 2);
+    }
+    maxTotalGb = value;
+    index += 1;
+  }
+  return { maxTotalGb };
+}
+
+function datesBetween(window: BacktestWindow): string[] {
+  const dates: string[] = [];
+  for (let date = window.start; date <= window.end; date = addDays(date, 1)) {
+    dates.push(date);
+  }
+  return dates;
+}
+
+function hourKeys(window: BacktestWindow): string[] {
+  return datesBetween(window).flatMap((date) =>
+    Array.from(
+      { length: 24 },
+      (_, hour) => `${date}T${String(hour).padStart(2, "0")}`,
+    ),
+  );
+}
+
+function observation(
+  check: string,
+  app: string,
+  period: string,
+  result: {
+    status: string;
+    numerator?: number | null;
+    denominator?: number | null;
+    value?: number | null;
+    detail?: string;
+  },
+): Observation {
+  return {
+    check,
+    app,
+    period,
+    status: result.status,
+    numerator: result.numerator ?? null,
+    denominator: result.denominator ?? null,
+    value: result.value ?? null,
+    detail: result.detail ?? null,
+  };
+}
+
+export async function runRadarBacktest(
+  options: RadarBacktestOptions = {},
+): Promise<RadarBacktestResult> {
+  const maxTotalGb = options.maxTotalGb ?? DEFAULT_BACKTEST_MAX_TOTAL_GB;
+  const backend = await resolveRadarFirstPartyBackend();
+  if (backend.sink !== "bigquery") {
+    throw new RadarQueryError(
+      "The historical backtest requires the BigQuery first-party event sink.",
+      2,
+    );
+  }
+  const orgId = await resolveRadarOrganizationId();
+  const table = await resolveRadarBigQueryEventsTable();
+  const eventStart = addDays(CLEAN.start, -7);
+  setRadarBigQueryScanBudget(maxTotalGb);
+  try {
+    const params = [
+      { name: "start_date", type: "DATE" as const, value: eventStart },
+      { name: "end_date", type: "DATE" as const, value: INCIDENT.end },
+      { name: "org_id", type: "STRING" as const, value: orgId },
+    ];
+    const eventStats = await runBigQuery(
+      buildBigQueryEventStatsSql(table, "BOTH", BACKTEST_EVENT_NAMES),
+      {
+        maxGb: maxTotalGb,
+        fresh: true,
+        cache: false,
+        params,
+      },
+    );
+    const hourlyRows = eventStats.rows.filter(
+      (row) => row.period_grain === "hourly",
+    );
+    const dailyRows = eventStats.rows.filter(
+      (row) => row.period_grain === "daily",
+    );
+    const observations: Observation[] = [];
+
+    for (const [label, window] of [
+      ["clean", CLEAN],
+      ["incident", INCIDENT],
+    ] as const) {
+      for (const hour of hourKeys(window)) {
+        const targetDate = hour.slice(0, 10);
+        const hourOfDay = hour.slice(11, 13);
+        const baselineStart = addDays(targetDate, -7);
+        const relevantHourlyRows = hourlyRows.filter((row) => {
+          const period = backtestHourOf(row.period_start);
+          const rowDate = dateOf(row.period_start);
+          return (
+            period.slice(11, 13) === hourOfDay &&
+            rowDate >= baselineStart &&
+            rowDate <= targetDate
+          );
+        });
+        const checks = createEventChecks(
+          relevantHourlyRows,
+          [],
+          [],
+          [],
+          [],
+          hour.slice(0, 10),
+          hour.slice(0, 10),
+          hour,
+          "hourly",
+        ).checks;
+        for (const check of checks) {
+          if (check.id === "builder-connect-success") {
+            observations.push(
+              observation(check.id, check.app, `${label}:${hour}`, check),
+            );
+          }
+        }
+      }
+      for (const date of datesBetween(window)) {
+        const relevantDailyRows = dailyRows.filter(
+          (row) => dateOf(row.period_start) === date,
+        );
+        const checks = createEventChecks(
+          relevantDailyRows,
+          [],
+          [],
+          [],
+          [],
+          date,
+          date,
+          `${date}T00`,
+          "daily",
+        ).checks;
+        for (const check of checks) {
+          if (
+            (check.id === "env-key-share" ||
+              check.id === "ai-connection-none") &&
+            (check.id !== "ai-connection-none" || check.app === "slides")
+          ) {
+            observations.push(
+              observation(check.id, check.app, `${label}:${date}`, check),
+            );
+          }
+        }
+      }
+    }
+
+    const rejectionResult = await runBigQuery(
+      buildBigQueryUploadRejectionSql(table),
+      {
+        maxGb: maxTotalGb,
+        fresh: true,
+        cache: false,
+        params: [
+          { name: "start_date", type: "DATE", value: CLEAN.start },
+          { name: "end_date", type: "DATE", value: INCIDENT.end },
+          { name: "org_id", type: "STRING", value: orgId },
+        ],
+      },
+    );
+    const rejectionRows = rejectionResult.rows;
+    const rejectionAttributionRows =
+      rejectionRows.length > 0
+        ? await loadUploadRejectionRows(
+            backend,
+            CLEAN.start,
+            orgId,
+            rejectionRows,
+            INCIDENT.end,
+          )
+        : undefined;
+    for (const window of [CLEAN, INCIDENT]) {
+      for (const date of datesBetween(window)) {
+        const rows = (rejectionAttributionRows ?? []).filter(
+          (row) => dateOf(row.event_date) === date,
+        );
+        const checkedApps = new Set<string>();
+        for (const row of rows) {
+          const check = uploadRejectionCheck(row);
+          if (check) {
+            checkedApps.add(check.app);
+            const label = date >= INCIDENT.start ? "incident" : "clean";
+            observations.push(
+              observation(check.id, check.app, `${label}:${date}`, check),
+            );
+          }
+        }
+        for (const app of ["design", "slides", "clips"]) {
+          if (checkedApps.has(app)) continue;
+          const label = date >= INCIDENT.start ? "incident" : "clean";
+          observations.push(noReplayRejectionObservation(date, app, label));
+        }
+      }
+    }
+
+    const scanEstimateGb =
+      (getRadarBigQueryScanBudget()?.reservedBytes ?? 0) / 1_000_000_000;
+    return {
+      incident: INCIDENT,
+      clean: CLEAN,
+      observations,
+      scanEstimateGb,
+      maxTotalGb,
+    };
+  } finally {
+    setRadarBigQueryScanBudget(undefined);
+  }
+}
+
+export function formatRadarBacktest(result: RadarBacktestResult): string {
+  const lines = [
+    "| Check | Window | App | Fired periods | Quiet periods | Unavailable periods | Insufficient periods | Evidence |",
+    "| --- | --- | --- | ---: | ---: | ---: | ---: | --- |",
+  ];
+  for (const check of TRACKED_CHECKS) {
+    for (const window of ["clean", "incident"] as const) {
+      const rows = result.observations.filter(
+        (row) => row.check === check && row.period.startsWith(`${window}:`),
+      );
+      const periodRows = new Map<string, Observation>();
+      const statusPriority: Record<string, number> = {
+        clear: 1,
+        observed: 1,
+        insufficient: 2,
+        unavailable: 3,
+        fired: 4,
+      };
+      for (const row of rows) {
+        const key = `${row.period}|${row.app}`;
+        const current = periodRows.get(key);
+        if (
+          !current ||
+          (statusPriority[row.status] ?? 0) >
+            (statusPriority[current.status] ?? 0)
+        ) {
+          periodRows.set(key, row);
+        }
+      }
+      const evaluated = [...periodRows.values()];
+      const apps = [...new Set(evaluated.map((row) => row.app))].sort();
+      const fired = evaluated.filter((row) => row.status === "fired");
+      const unavailable = evaluated.filter(
+        (row) => row.status === "unavailable",
+      );
+      const quiet = evaluated.filter(
+        (row) => row.status === "clear" || row.status === "observed",
+      );
+      const insufficient = evaluated.filter(
+        (row) => row.status === "insufficient",
+      );
+      const evidence = [...fired]
+        .sort((left, right) => (right.numerator ?? 0) - (left.numerator ?? 0))
+        .slice(0, 3)
+        .map(
+          (row) =>
+            `${row.period.slice(window.length + 1)} ${row.app}: ${row.detail ?? `${row.numerator ?? 0}/${row.denominator ?? 0}`}`,
+        )
+        .join("; ");
+      lines.push(
+        `| ${check} | ${window} | ${apps.join(", ") || "-"} | ${fired.length} | ${quiet.length} | ${unavailable.length} | ${insufficient.length} | ${evidence || "-"} |`,
+      );
+    }
+  }
+  lines.push(
+    "",
+    `Incident: ${result.incident.start} through ${result.incident.end}; clean baseline: ${result.clean.start} through ${result.clean.end}.`,
+    `BigQuery dry-run estimate: ${result.scanEstimateGb.toFixed(2)} GB / ${result.maxTotalGb} GB.`,
+  );
+  return lines.join("\n");
+}
+
+export function trackedRadarBacktestChecks(): string[] {
+  return [...TRACKED_CHECKS];
+}