@agent-native/core 0.99.1 → 0.99.2

package/corpus/templates/analytics/AGENTS.md

@@ -119,11 +119,11 @@ details live in `.agents/skills/`.
   without raw replay events or storage references. Do not add replay blob or
   dashboard mutation actions to this catalog without an explicit security
   review.
-- While Demo mode is enabled, session and error identities display anonymized
-  (`anonymous@builder.io`), so incident lookups must filter by the stable
+- Demo mode is a browser-local presentation preference. Analytics backend
+  actions, agent/MCP reads, session replays, and error issues always return real
+  authorized identities, so incident lookups should use the actual
   `userId`/email parameter (e.g. `userId: "user@example.com"`) or recording/
-  issue id — never by matching emails read back from previously displayed
-  output.
+  issue id.
 - Analytics keeps its direct MCP surface explicitly curated, so external
   agents should use `ask_app` for multi-step investigation and changes. The
   six incident reads above are bounded, user/org-scoped fallback tools for

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

@@ -11,6 +11,7 @@ import {
 } from "@agent-native/core/server";
 import { z } from "zod";
 
+import { validateFirstPartyDashboardTimeScope } from "../server/lib/dashboard-time-scope";
 import {
   getDashboard,
   upsertDashboard,
@@ -138,7 +139,7 @@ export default defineAction({
     "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).",
+    "Each metric accepts an optional per-metric `window` of '30d' | '90d' | 'all' (only affects windowed virality/time metrics). Catalog panels are time-scoped by construction; custom first-party SQL added later must use `{{timeRange}}` or declare `config.timeScope`.",
   schema: z.object({
     dashboardId: z
       .string()
@@ -200,6 +201,7 @@ export default defineAction({
     const unknownMetrics: string[] = [];
     const invalidMetrics: Array<{ metric: string; reason: string }> = [];
     const composedPanels: ComposedPanel[] = [];
+    const catalogDashboard = withFirstPartyDashboardFilters({ filters: [] });
 
     for (const req of requests) {
       const panel = buildPanel(req.metric, {
@@ -220,6 +222,15 @@ export default defineAction({
       // 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 {
+        const timeScopeError = validateFirstPartyDashboardTimeScope(
+          panel,
+          catalogDashboard,
+          0,
+        );
+        if (timeScopeError) {
+          invalidMetrics.push({ metric: req.metric, reason: timeScopeError });
+          continue;
+        }
         validateFirstPartyAnalyticsSql(panel.sql);
       } catch (e: any) {
         invalidMetrics.push({

package/corpus/templates/analytics/actions/dashboard-mutation-api.ts

@@ -32,6 +32,17 @@ type DashboardPatch = {
   parentId?: string;
 };
 
+type PanelTimeScope =
+  | "dashboard"
+  | "fixed-window"
+  | "cohort-history"
+  | "all-time";
+
+type PanelConfig = Record<string, unknown> & {
+  /** Use "dashboard" for AI-generated first-party panels by default. */
+  timeScope?: PanelTimeScope;
+};
+
 type PanelPatch = {
   title?: string;
   sql?: string;
@@ -40,7 +51,7 @@ type PanelPatch = {
   width?: number;
   columns?: number;
   tab?: string;
-  config?: Record<string, unknown>;
+  config?: PanelConfig;
   description?: string; // shorthand for config.description
 };
 
@@ -112,9 +123,9 @@ export const DASHBOARD_MUTATION_EXAMPLES = [
   'dashboard.panelsMatching({"source":"first-party"}).setWidth(2);',
   'dashboard.panel("retention").setConfigPath("yAxis.format","percent");',
   'dashboard.section("retention-activity-section").append(["repeat-users","retention-over-time"]);',
-  'dashboard.insertPanel({"id":"new-kpi","title":"New KPI","source":"first-party","chartType":"metric","width":1,"sql":"SELECT COUNT(*) AS value FROM analytics_events"}).atTop();',
-  'dashboard.insertPanel({"id":"new-chart","title":"New Chart","source":"first-party","chartType":"line","width":1,"sql":"SELECT date, COUNT(*) AS value FROM analytics_events GROUP BY date ORDER BY date"}).nextTo("retention-over-time");',
-  'dashboard.insertPanel({"id":"row-chart","title":"Row Chart","source":"first-party","chartType":"bar","width":1,"sql":"SELECT name, COUNT(*) AS value FROM analytics_events GROUP BY name"}).atRow(2);',
+  `dashboard.insertPanel({"id":"new-kpi","title":"New KPI","source":"first-party","chartType":"metric","width":1,"config":{"timeScope":"dashboard"},"sql":"SELECT COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}'"}).atTop();`,
+  `dashboard.insertPanel({"id":"new-chart","title":"New Chart","source":"first-party","chartType":"line","width":1,"config":{"timeScope":"dashboard"},"sql":"SELECT event_date AS date, COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}' GROUP BY event_date ORDER BY event_date"}).nextTo("retention-over-time");`,
+  `dashboard.insertPanel({"id":"row-chart","title":"Row Chart","source":"first-party","chartType":"bar","width":1,"config":{"timeScope":"dashboard"},"sql":"SELECT event_name AS name, COUNT(*) AS value FROM analytics_events WHERE event_date >= '{{dateStart}}' AND event_date < '{{dateEnd}}' GROUP BY event_name"}).atRow(2);`,
   'dashboard.insertPanel({"id":"pipeline-widget","title":"Pipeline Widget","chartType":"extension","width":3,"config":{"extensionId":"<existing-extension-id>"}}).atBottom();',
 ] as const;
 

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

@@ -122,6 +122,7 @@ const apiHelp =
   "Subjects: dashboard.set, dashboard.panel, dashboard.panels, dashboard.panelsMatching, dashboard.section, dashboard.insertPanel. " +
   "Selection methods: moveToTop, moveToBottom, moveBefore, moveAfter, moveToIndex, moveNextTo, moveToRow, remove, set, setTitle, setSql, setWidth, setConfig, setConfigPath, duplicate. " +
   "Inserted panels support atTop, atBottom, before, after, atIndex, nextTo, atRow, atRowStart, and atRowEnd. Use nextTo(panelId) or atRow(rowNumber) for visible row placement. " +
+  "AI-generated first-party panels are dashboard-time-bound by default: set config.timeScope to dashboard and include a matching dashboard time filter in SQL. Allowed values are dashboard, fixed-window, cohort-history, and all-time; use all-time only when the user requests full available history and put all-time, lifetime, or historical in the title or description. A {{timeRange}} token requires the timeRange select filter; {{<id>Start}}/{{<id>End}} require a matching date-range filter. Server validation rejects unbound first-party SQL. " +
   `Examples: ${DASHBOARD_MUTATION_EXAMPLES.slice(0, 5).join(" ")}`;
 
 function resolveScope() {
@@ -198,7 +199,7 @@ export default defineAction({
     "Apply general SQL dashboard edits through a small typed mutation API in ONE atomic save. " +
     "Prefer this for dashboard layout and panel edits: move panels by id, edit titles/SQL/width/config, remove panels, duplicate panels, insert panels, or patch dashboard fields. " +
     "For user placement requests like 'second row' or 'next to return rates', use row-aware placement such as `dashboard.insertPanel(...).nextTo(\"retention-over-time\")` or `.atRow(2)`, then verify rendered rows from `get-sql-dashboard.layout.groups`. " +
-    "This is code-shaped but not arbitrary code execution: the server parses the allowed dashboard methods, validates the resulting config with the same invariants as update-dashboard, saves once, syncs collab, and returns compact proof. " +
+    "This is code-shaped but not arbitrary code execution: the server parses the allowed dashboard methods, validates the resulting config with the same invariants as update-dashboard, saves once, syncs collab, and returns compact proof. First-party SQL must be explicitly time-bound as described in the API help; server validation rejects unbound first-party SQL. " +
     "The main code argument is a string, so it avoids brittle JSON-pointer indexes and native-array serialization issues. " +
     `Common example: ${DASHBOARD_MUTATION_EXAMPLES[0]}`,
   schema: z.object({

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

@@ -13,6 +13,7 @@ import { z } from "zod";
 
 import { interpolate } from "../app/pages/adhoc/sql-dashboard/interpolate";
 import { dryRunQuery } from "../server/lib/bigquery";
+import { validateFirstPartyDashboardTimeScope } from "../server/lib/dashboard-time-scope";
 import {
   upsertDashboard,
   upsertDashboardWithRetry,
@@ -421,8 +422,20 @@ export async function validatePanelSql(
       const raw = typeof p.sql === "string" ? p.sql : "";
       if (raw.trim()) {
         try {
+          const timeScopeError = validateFirstPartyDashboardTimeScope(
+            p,
+            config,
+            i,
+          );
+          if (timeScopeError) return timeScopeError;
           validateFirstPartyAnalyticsSql(interpolate(raw, vars));
         } catch (e: any) {
+          if (
+            typeof e?.message === "string" &&
+            e.message.startsWith("panel[")
+          ) {
+            return e.message;
+          }
           return `panel[${i}] "${p.title || p.id}" first-party analytics SQL is invalid: ${e?.message ?? e}`;
         }
       }
@@ -552,6 +565,7 @@ export default defineAction({
     "Use this action when creating a brand-new dashboard from a complete config, for the UI full-config save path, or for an explicitly requested low-level JSON-pointer compatibility edit. " +
     "Do not use `ops` or `panelOrder` for ordinary agent edits like moving charts, adding panels to an existing dashboard, changing widths, or updating panel config; call `mutate-dashboard` once with the full edit script. " +
     "When this action is appropriate, provide only one of `ops`, `panelOrder`, or `config`; `config` replaces the whole dashboard config. " +
+    "First-party event panels must bind to a declared dashboard time filter with `{{timeRange}}` or date-range variables. Intentional fixed-window, cohort-history, and all-time exceptions must be explicit in `panel.config.timeScope`; unbounded first-party SQL is rejected at save time. " +
     "To add a shipped catalog template's panels to an existing dashboard, prefer `install-dashboard-template` with `mergePanels: true` — it appends the template's panels in one call without you having to author each panel. " +
     "The result is compact by default: `panelCount`, `appliedOps`, `panelOrder`, `firstPanelIds`, and `summary`. Set `returnConfig: true` only when you truly need the full config in the tool result. " +
     "The UI auto-refreshes after this action — do NOT call `refresh-screen`.",

package/corpus/templates/analytics/app/components/layout/Sidebar.tsx

@@ -14,6 +14,7 @@ import {
   IconReportAnalytics,
   IconSearch,
   IconArchive,
+  IconActivity,
   IconHeartbeat,
   IconPin,
   IconPlus,
@@ -26,7 +27,6 @@ import {
   IconPlayerPlay,
   IconLayoutSidebarLeftCollapse,
   IconLayoutSidebarLeftExpand,
-  IconShieldCheck,
 } from "@tabler/icons-react";
 import {
   useQuery,
@@ -97,7 +97,7 @@ import {
   type ChatThreadSummary,
 } from "@agent-native/core/client";
 import { ExtensionsSidebarSection } from "@agent-native/core/client/extensions";
-import { OrgSwitcher, useOrgRole } from "@agent-native/core/client/org";
+import { OrgSwitcher } from "@agent-native/core/client/org";
 
 import {
   AlertDialog,
@@ -1593,7 +1593,6 @@ export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
   const navigate = useNavigate();
   const t = useT();
   const queryClient = useQueryClient();
-  const { canManageOrg } = useOrgRole();
   const { setTheme } = useTheme();
 
   const isAskRoute = location.pathname === "/ask";
@@ -2428,16 +2427,12 @@ export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
       href: "/monitoring",
       active: location.pathname.startsWith("/monitoring"),
     },
-    ...(canManageOrg
-      ? [
-          {
-            icon: IconShieldCheck,
-            label: t("navigation.admin"),
-            href: "/agents?view=dashboards",
-            active: location.pathname.startsWith("/agents"),
-          },
-        ]
-      : []),
+    {
+      icon: IconActivity,
+      label: t("navigation.agents"),
+      href: "/agents",
+      active: location.pathname.startsWith("/agents"),
+    },
     {
       icon: IconDatabase,
       label: t("navigation.dataSources"),
@@ -2641,20 +2636,19 @@ export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
                 {t("navigation.monitoring")}
               </Link>
 
-              {canManageOrg ? (
-                <Link
-                  to="/agents?view=dashboards"
-                  className={cn(
-                    "order-6 flex items-center gap-3 rounded-lg px-3 py-2 transition-colors hover:text-primary",
-                    location.pathname.startsWith("/agents")
-                      ? "bg-sidebar-accent text-sidebar-accent-foreground"
-                      : "text-muted-foreground hover:bg-sidebar-accent/50",
-                  )}
-                >
-                  <IconShieldCheck className="h-4 w-4" />
-                  {t("navigation.admin")}
-                </Link>
-              ) : null}
+              {/* Agents link */}
+              <Link
+                to="/agents"
+                className={cn(
+                  "order-6 flex items-center gap-3 rounded-lg px-3 py-2 transition-colors hover:text-primary",
+                  location.pathname.startsWith("/agents")
+                    ? "bg-sidebar-accent text-sidebar-accent-foreground"
+                    : "text-muted-foreground hover:bg-sidebar-accent/50",
+                )}
+              >
+                <IconActivity className="h-4 w-4" />
+                {t("navigation.agents")}
+              </Link>
 
               {/* Data Sources link */}
               <Link

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/index.tsx

@@ -297,7 +297,10 @@ const PanelCell = memo(function PanelCell({
     [panel, vars],
   );
   const resolvedSql = useMemo(
-    () => interpolate(serializePanelSql(panel.sql), vars),
+    () =>
+      interpolate(serializePanelSql(panel.sql), vars, {
+        failClosedTimeVariables: true,
+      }),
     [panel.sql, vars],
   );
   const handleSelectForChat = useCallback(

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/interpolate.ts

@@ -14,9 +14,23 @@ function escapeSqlValue(value: string): string {
   return value.replace(/'/g, "''");
 }
 
+export interface InterpolateOptions {
+  /**
+   * Replace missing/empty time variables with a value that cannot satisfy the
+   * canonical dashboard predicates. This keeps a stale or malformed panel
+   * fail-closed at render time instead of turning into an all-time query.
+   */
+  failClosedTimeVariables?: boolean;
+}
+
+function isTimeVariable(name: string): boolean {
+  return name === "timeRange" || /(?:Start|End)$/.test(name);
+}
+
 export function interpolate(
   sql: string | undefined | null,
   vars: Record<string, string> = {},
+  options: InterpolateOptions = {},
 ): string {
   // Defensive: a malformed dashboard config (e.g. agent wrote a panel without
   // a `sql` field) should not crash the page. Treat missing/non-string SQL
@@ -33,6 +47,13 @@ export function interpolate(
 
   return withConditionals.replace(/\{\{(\w+)\}\}/g, (_match, name) => {
     const value = vars[name];
+    if (
+      options.failClosedTimeVariables &&
+      isTimeVariable(name) &&
+      (value == null || value.length === 0)
+    ) {
+      return "__missing_dashboard_time_filter__";
+    }
     if (value == null) return "";
     return escapeSqlValue(String(value));
   });

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/types.ts

@@ -63,7 +63,21 @@ export interface PivotConfig {
   valueKey: string;
 }
 
+/**
+ * Declares how a query's time coverage relates to the dashboard filter.
+ * `dashboard` is the default for ordinary event metrics; the other values are
+ * explicit exceptions that make intentional history scans visible to agents
+ * and reviewers.
+ */
+export type DashboardTimeScope =
+  | "dashboard"
+  | "fixed-window"
+  | "cohort-history"
+  | "all-time";
+
 export interface SqlPanelConfig {
+  /** Time coverage contract for first-party SQL panels. */
+  timeScope?: DashboardTimeScope;
   xKey?: string;
   yKey?: string;
   yKeys?: string[];

package/corpus/templates/analytics/app/pages/sessions/SessionDetailPage.tsx

@@ -47,6 +47,13 @@ import { Link, useParams } from "react-router";
 
 import { Button } from "@/components/ui/button";
 import { Card, CardContent } from "@/components/ui/card";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
 import { Input } from "@/components/ui/input";
 import {
   Popover,
@@ -1087,22 +1094,34 @@ function ReplayPlayer({
                 {formatClock(totalTime)}
               </span>
 
-              <div className="flex items-center rounded-md bg-muted p-1">
-                {SPEED_OPTIONS.map((option) => (
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
                   <button
-                    key={option}
                     type="button"
-                    className={cn(
-                      "rounded px-2 py-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground",
-                      speed === option &&
-                        "bg-background text-foreground shadow-sm",
-                    )}
-                    onClick={() => updateSpeed(option)}
+                    disabled={disabled}
+                    aria-label={`${speed}x`}
+                    className="inline-flex h-8 min-w-11 items-center justify-center rounded-md border px-2 text-xs font-medium tabular-nums transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
                   >
-                    {option}x
+                    {speed}x
                   </button>
-                ))}
-              </div>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="center" side="top">
+                  <DropdownMenuRadioGroup
+                    value={String(speed)}
+                    onValueChange={(value) => updateSpeed(Number(value))}
+                  >
+                    {SPEED_OPTIONS.map((option) => (
+                      <DropdownMenuRadioItem
+                        key={option}
+                        value={String(option)}
+                        className="tabular-nums"
+                      >
+                        {option}x
+                      </DropdownMenuRadioItem>
+                    ))}
+                  </DropdownMenuRadioGroup>
+                </DropdownMenuContent>
+              </DropdownMenu>
 
               <Tooltip>
                 <TooltipTrigger asChild>

package/corpus/templates/analytics/changelog/2026-07-13-dashboard-charts-now-honor-the-selected-time-range-by-defaul.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-13
+---
+
+Dashboard charts now honor the selected time range by default and reject accidental unbounded first-party queries

package/corpus/templates/analytics/changelog/2026-07-13-keep-real-authorized-identities-in-analytics-incident-lookup.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-13
+---
+
+Keep real authorized identities in Analytics incident lookups when browser Demo mode is enabled

package/corpus/templates/analytics/changelog/2026-07-13-the-analytics-agents-tab-is-available-again-from-the-main-na.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-13
+---
+
+The Analytics Agents tab is available again from the main navigation.

package/corpus/templates/analytics/seeds/dashboards/agent-native-templates-first-party.json

@@ -226,7 +226,7 @@
       "chartType": "bar",
       "source": "first-party",
       "width": 2,
-      "sql": "SELECT COALESCE(NULLIF(app, ''), 'unknown') AS app, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' GROUP BY COALESCE(NULLIF(app, ''), 'unknown') ORDER BY count DESC LIMIT 20",
+      "sql": "SELECT COALESCE(NULLIF(app, ''), 'unknown') AS app, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))) AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io')) GROUP BY COALESCE(NULLIF(app, ''), 'unknown') ORDER BY count DESC LIMIT 20",
       "config": {
         "xKey": "app",
         "yKey": "count",
@@ -240,7 +240,7 @@
       "chartType": "bar",
       "source": "first-party",
       "width": 1,
-      "sql": "SELECT COALESCE(NULLIF(signed_in, ''), 'unknown') AS signed_in, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' GROUP BY COALESCE(NULLIF(signed_in, ''), 'unknown') ORDER BY signed_in",
+      "sql": "SELECT COALESCE(NULLIF(signed_in, ''), 'unknown') AS signed_in, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))) AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io')) GROUP BY COALESCE(NULLIF(signed_in, ''), 'unknown') ORDER BY signed_in",
       "config": {
         "xKey": "signed_in",
         "yKey": "count",
@@ -254,7 +254,7 @@
       "chartType": "area",
       "source": "first-party",
       "width": 1,
-      "sql": "SELECT event_date AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' GROUP BY event_date ORDER BY date",
+      "sql": "SELECT event_date AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))) AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io')) GROUP BY event_date ORDER BY date",
       "config": {
         "xKey": "date",
         "yKey": "count",

package/corpus/templates/analytics/server/lib/agent-readable-resource-context.ts

@@ -56,6 +56,10 @@ function panelSummaries(config: Record<string, unknown>) {
       width: typeof panel.width === "number" ? panel.width : undefined,
       columns: typeof panel.columns === "number" ? panel.columns : undefined,
       tab: typeof panel.tab === "string" ? panel.tab : undefined,
+      timeScope:
+        typeof panelConfig.timeScope === "string"
+          ? panelConfig.timeScope
+          : undefined,
       description:
         typeof panelConfig.description === "string"
           ? panelConfig.description

package/corpus/templates/analytics/server/lib/dashboard-time-scope.ts

@@ -0,0 +1,170 @@
+import type { DashboardTimeScope } from "../../app/pages/adhoc/sql-dashboard/types";
+
+export const DASHBOARD_TIME_SCOPES: readonly DashboardTimeScope[] = [
+  "dashboard",
+  "fixed-window",
+  "cohort-history",
+  "all-time",
+];
+
+type DashboardFilterLike = {
+  id?: unknown;
+  key?: unknown;
+  type?: unknown;
+  default?: unknown;
+};
+
+type DashboardPanelLike = {
+  id?: unknown;
+  title?: unknown;
+  chartType?: unknown;
+  source?: unknown;
+  sql?: unknown;
+  config?: unknown;
+};
+
+type DashboardConfigLike = {
+  filters?: unknown;
+};
+
+const TEMPORAL_VARIABLE_RE = /\{\{(timeRange|[A-Za-z_]\w*(?:Start|End))\}\}/g;
+
+/** Return the time variables a panel actually references. */
+export function extractDashboardTimeVariables(sql: string): string[] {
+  const variables = new Set<string>();
+  for (const match of sql.matchAll(TEMPORAL_VARIABLE_RE)) {
+    variables.add(match[1]);
+  }
+  return [...variables];
+}
+
+function filterId(filter: DashboardFilterLike): string {
+  const value = filter.id ?? filter.key;
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function filtersFrom(config: DashboardConfigLike): DashboardFilterLike[] {
+  return Array.isArray(config.filters)
+    ? (config.filters as DashboardFilterLike[])
+    : [];
+}
+
+function panelConfig(panel: DashboardPanelLike): Record<string, unknown> {
+  return panel.config && typeof panel.config === "object"
+    ? (panel.config as Record<string, unknown>)
+    : {};
+}
+
+function hasExplicitLowerBound(sql: string): boolean {
+  // This intentionally recognizes the bounded shapes used by the shipped
+  // first-party catalog. It is a compatibility escape hatch for fixed-window
+  // catalog metrics; new ad-hoc panels should use a dashboard placeholder.
+  return /\b(?:event_date|timestamp|started_at|ended_at|cohort_date|created_at|date)\b[\s\S]{0,100}?(?:>=|>)\s*[\s\S]{0,160}?(?:CURRENT_DATE|CURRENT_TIMESTAMP|NOW\s*\(|INTERVAL\s*['"]|DATE\s*['"]|TIMESTAMP\s*['"]|\b20\d{2}-\d{2}-\d{2}\b)/i.test(
+    sql,
+  );
+}
+
+function hasIntentionalHistoryDescription(
+  panel: DashboardPanelLike,
+  config: Record<string, unknown>,
+): boolean {
+  const values = [panel.title, config.description].filter(
+    (value): value is string => typeof value === "string",
+  );
+  return /all[- ]?time|lifetime|histor(?:y|ical)/i.test(values.join(" "));
+}
+
+function scopeValue(panel: DashboardPanelLike): DashboardTimeScope | undefined {
+  const value = panelConfig(panel).timeScope;
+  return typeof value === "string" &&
+    (DASHBOARD_TIME_SCOPES as readonly string[]).includes(value)
+    ? (value as DashboardTimeScope)
+    : undefined;
+}
+
+/**
+ * Validate the temporal contract for a first-party dashboard panel.
+ *
+ * Ordinary panels must bind to a dashboard filter. Intentional exceptions are
+ * explicit in `config.timeScope`, while legacy fixed-window catalog SQL is
+ * accepted when its lower bound is visible in the SQL itself.
+ */
+export function validateFirstPartyDashboardTimeScope(
+  panel: DashboardPanelLike,
+  dashboard: DashboardConfigLike,
+  index: number,
+): string | null {
+  if (panel.source !== "first-party") return null;
+  if (panel.chartType === "section" || panel.chartType === "extension") {
+    return null;
+  }
+
+  const sql = typeof panel.sql === "string" ? panel.sql : "";
+  const variables = extractDashboardTimeVariables(sql);
+  const filters = filtersFrom(dashboard);
+  const label =
+    typeof panel.title === "string" && panel.title.trim()
+      ? `"${panel.title}"`
+      : `at index ${index}`;
+
+  for (const variable of variables) {
+    const expectedFilterId =
+      variable === "timeRange"
+        ? "timeRange"
+        : variable.replace(/(?:Start|End)$/, "");
+    const filter = filters.find(
+      (candidate) => filterId(candidate) === expectedFilterId,
+    );
+    if (!filter) {
+      return `panel[${index}] ${label} uses {{${variable}}} but config.filters has no matching "${expectedFilterId}" filter; bind first-party SQL to a declared dashboard time filter`;
+    }
+    if (variable === "timeRange") {
+      if (filter.type !== "select") {
+        return `panel[${index}] ${label} uses {{timeRange}}, but filter "timeRange" must have type "select"`;
+      }
+    } else if (filter.type !== "date-range") {
+      return `panel[${index}] ${label} uses {{${variable}}}, but filter "${expectedFilterId}" must have type "date-range"`;
+    }
+    if (typeof filter.default !== "string" || !filter.default.trim()) {
+      return `panel[${index}] ${label} uses a time filter without a non-empty default; choose a bounded default such as "90d" so missing filter state cannot become all-time`;
+    }
+  }
+
+  const configuredScope = panelConfig(panel).timeScope;
+  if (
+    configuredScope !== undefined &&
+    (typeof configuredScope !== "string" ||
+      !(DASHBOARD_TIME_SCOPES as readonly string[]).includes(configuredScope))
+  ) {
+    return `panel[${index}] ${label} config.timeScope must be one of ${DASHBOARD_TIME_SCOPES.join(", ")}`;
+  }
+
+  const scope = scopeValue(panel);
+  const hasDashboardBinding = variables.length > 0;
+  const hasLowerBound = hasExplicitLowerBound(sql);
+
+  if (scope === "dashboard" && !hasDashboardBinding) {
+    return `panel[${index}] ${label} declares timeScope "dashboard" but does not reference {{timeRange}} or a date-range variable`;
+  }
+  if (scope === "fixed-window" && hasDashboardBinding) {
+    return `panel[${index}] ${label} declares timeScope "fixed-window" but uses dashboard time variables; use timeScope "dashboard" or remove the placeholders`;
+  }
+  if (scope === "fixed-window" && !hasLowerBound) {
+    return `panel[${index}] ${label} declares timeScope "fixed-window" without a recognizable lower date bound`;
+  }
+  if (scope === "all-time" && hasDashboardBinding) {
+    return `panel[${index}] ${label} declares timeScope "all-time" but uses dashboard time variables; use timeScope "dashboard" for filter-bound output`;
+  }
+  if (
+    scope === "all-time" &&
+    !hasIntentionalHistoryDescription(panel, panelConfig(panel))
+  ) {
+    return `panel[${index}] ${label} declares timeScope "all-time"; add a description or title that says lifetime, historical, or all-time so the exception is explicit`;
+  }
+
+  if (!scope && !hasDashboardBinding && !hasLowerBound) {
+    return `panel[${index}] ${label} reads first-party analytics without a time bound; use {{timeRange}} with a non-empty default filter, or explicitly set config.timeScope to "cohort-history" or "all-time" for intentional history scans`;
+  }
+
+  return null;
+}