@agent-native/core 0.80.0 → 0.80.2

package/corpus/core/src/styles/agent-native.css

@@ -162,6 +162,17 @@
     box-shadow 260ms cubic-bezier(0.32, 0.72, 0, 1);
 }
 
+.agent-layout-main-surface::before,
+.agent-sidebar-main-surface::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  pointer-events: none;
+  border-radius: inherit;
+  box-shadow: var(--agent-native-raised-outline);
+}
+
 .agent-layout-shell
   :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
   > :first-child
@@ -213,23 +224,19 @@
   .agent-layout-shell > .agent-sidebar-shell > .agent-sidebar-main-surface {
     border-start-start-radius: var(--agent-native-raised-radius);
     border-end-start-radius: var(--agent-native-raised-radius);
-    box-shadow:
-      var(--agent-native-raised-outline), var(--agent-native-raised-shadow-left);
+    box-shadow: var(--agent-native-raised-shadow-left);
   }
 
   .agent-sidebar-main-surface[data-agent-sidebar-main-state="open"][data-agent-sidebar-main-position="right"] {
     border-start-end-radius: var(--agent-native-raised-radius);
     border-end-end-radius: var(--agent-native-raised-radius);
-    box-shadow:
-      var(--agent-native-raised-outline),
-      var(--agent-native-raised-shadow-right);
+    box-shadow: var(--agent-native-raised-shadow-right);
   }
 
   .agent-sidebar-main-surface[data-agent-sidebar-main-state="open"][data-agent-sidebar-main-position="left"] {
     border-start-start-radius: var(--agent-native-raised-radius);
     border-end-start-radius: var(--agent-native-raised-radius);
-    box-shadow:
-      var(--agent-native-raised-outline), var(--agent-native-raised-shadow-left);
+    box-shadow: var(--agent-native-raised-shadow-left);
   }
 }
 

package/corpus/core/src/usage/store.ts

@@ -112,12 +112,12 @@ const PRICING: Array<{ match: RegExp; pricing: ModelPricing }> = [
   // ── Google Gemini ───────────────────────────────────────────────────────────
   // Gemini 3 Pro / 3.1 Pro: ~$1.25/$10 per MTok (approximate; verify on billing)
   {
-    match: /gemini-3[\.\-]1-pro/i,
+    match: /gemini-3[.\-]1-pro/i,
     pricing: { input: 125, output: 1000, cacheRead: 31, cacheWrite: 0 },
   },
   // Gemini 3.5 Flash / 3 Flash: ~$0.15/$0.60 per MTok
   {
-    match: /gemini-3[\.\-][0-9]+-flash/i,
+    match: /gemini-3[.\-][0-9]+-flash/i,
     pricing: { input: 15, output: 60, cacheRead: 4, cacheWrite: 0 },
   },
   // Gemini 2.5 Pro/Flash (catch-all for older 2.5)

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

@@ -1,3 +1,14 @@
+import {
+  buildDashboardPanelGroups,
+  columnExpansionForDropSlot,
+  movePanelToDropSlot,
+  type DashboardDropSlot,
+} from "../app/pages/adhoc/sql-dashboard/dashboard-layout";
+import {
+  clampDashboardColumns,
+  MAX_DASHBOARD_COLUMNS,
+  type SqlPanel,
+} from "../app/pages/adhoc/sql-dashboard/types";
 import { movePanelsById, type PanelOrderTarget } from "./dashboard-panel-order";
 
 export const DASHBOARD_MUTATION_API_TYPES = `type DashboardScript = {
@@ -57,6 +68,14 @@ type PanelSelection = {
   moveBefore(panelId: string): void;
   moveAfter(panelId: string): void;
   moveToIndex(index: number): void;
+  moveNextTo(panelId: string): void; // same visible row, after panelId; expands row columns when needed
+  nextTo(panelId: string): void; // alias for moveNextTo
+  moveToRow(rowNumber: number): void; // 1-based visible row number, end of row
+  moveToRowStart(rowNumber: number): void;
+  moveToRowEnd(rowNumber: number): void;
+  atRow(rowNumber: number): void; // alias for moveToRow
+  atRowStart(rowNumber: number): void;
+  atRowEnd(rowNumber: number): void;
   remove(): void;
   set(patch: PanelPatch): void;
   setTitle(title: string): void;
@@ -77,6 +96,10 @@ type InsertedPanel = {
   before(panelId: string): void;
   after(panelId: string): void;
   atIndex(index: number): void;
+  nextTo(panelId: string): void; // same visible row, after panelId; expands row columns when needed
+  atRow(rowNumber: number): void; // 1-based visible row number, end of row
+  atRowStart(rowNumber: number): void;
+  atRowEnd(rowNumber: number): void;
 };`;
 
 export const DASHBOARD_MUTATION_EXAMPLES = [
@@ -88,6 +111,8 @@ export const DASHBOARD_MUTATION_EXAMPLES = [
   '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);',
 ] as const;
 
 export type DashboardMutationOperation =
@@ -98,6 +123,9 @@ export type DashboardMutationOperation =
       index?: number;
       beforePanelId?: string;
       afterPanelId?: string;
+      nextToPanelId?: string;
+      rowNumber?: number;
+      rowPosition?: "start" | "end";
     }
   | {
       op: "removePanels";
@@ -121,6 +149,9 @@ export type DashboardMutationOperation =
       index?: number;
       beforePanelId?: string;
       afterPanelId?: string;
+      nextToPanelId?: string;
+      rowNumber?: number;
+      rowPosition?: "start" | "end";
     }
   | {
       op: "duplicatePanel";
@@ -131,6 +162,9 @@ export type DashboardMutationOperation =
       index?: number;
       beforePanelId?: string;
       afterPanelId?: string;
+      nextToPanelId?: string;
+      rowNumber?: number;
+      rowPosition?: "start" | "end";
     }
   | {
       op: "setDashboard";
@@ -156,8 +190,17 @@ type MutationTarget = {
   index?: number;
   beforePanelId?: string;
   afterPanelId?: string;
+  nextToPanelId?: string;
+  rowNumber?: number;
+  rowPosition?: "start" | "end";
 };
 
+type VisualPlacementTarget =
+  | { nextToPanelId: string }
+  | { rowNumber: number; rowPosition?: "start" | "end" };
+
+type DashboardPlacementTarget = PanelOrderTarget | VisualPlacementTarget;
+
 const DASHBOARD_SUBJECTS = [
   "set",
   "panel",
@@ -173,6 +216,14 @@ const PANEL_METHODS = [
   "moveBefore",
   "moveAfter",
   "moveToIndex",
+  "moveNextTo",
+  "nextTo",
+  "moveToRow",
+  "moveToRowStart",
+  "moveToRowEnd",
+  "atRow",
+  "atRowStart",
+  "atRowEnd",
   "remove",
   "set",
   "setTitle",
@@ -189,11 +240,19 @@ const PLACEMENT_METHODS = [
   "moveBefore",
   "moveAfter",
   "moveToIndex",
+  "moveNextTo",
+  "moveToRow",
+  "moveToRowStart",
+  "moveToRowEnd",
   "atTop",
   "atBottom",
   "before",
   "after",
   "atIndex",
+  "nextTo",
+  "atRow",
+  "atRowStart",
+  "atRowEnd",
 ];
 
 function panelsFromConfig(config: Record<string, unknown>) {
@@ -339,6 +398,14 @@ function assertNumber(value: unknown, label: string): number {
   return value;
 }
 
+function assertPositiveInteger(value: unknown, label: string): number {
+  const number = assertNumber(value, label);
+  if (!Number.isInteger(number) || number < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return number;
+}
+
 function assertObject(value: unknown, label: string): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`${label} must be an object`);
@@ -359,23 +426,172 @@ function uniqueStrings(values: string[]): string[] {
 
 function targetFromOperation(
   op: MutationTarget & { op: string },
-): PanelOrderTarget {
-  const targets = [
-    op.index !== undefined,
-    !!op.beforePanelId,
-    !!op.afterPanelId,
-  ].filter(Boolean).length;
-  if (targets > 1) {
+): DashboardPlacementTarget {
+  const targetNames = [
+    op.position !== undefined ? "position" : null,
+    op.index !== undefined ? "index" : null,
+    op.beforePanelId ? "beforePanelId" : null,
+    op.afterPanelId ? "afterPanelId" : null,
+    op.nextToPanelId ? "nextToPanelId" : null,
+    op.rowNumber !== undefined ? "rowNumber" : null,
+  ].filter((item): item is string => item !== null);
+  if (targetNames.length > 1) {
     throw new Error(
-      `${op.op} accepts only one of index, beforePanelId, or afterPanelId`,
+      `${op.op} accepts only one placement target (${targetNames.join(", ")})`,
     );
   }
+  if (op.rowPosition !== undefined && op.rowNumber === undefined) {
+    throw new Error(`${op.op} rowPosition requires rowNumber`);
+  }
+  if (op.nextToPanelId) return { nextToPanelId: op.nextToPanelId };
+  if (op.rowNumber !== undefined) {
+    if (!Number.isInteger(op.rowNumber) || op.rowNumber < 1) {
+      throw new Error(`${op.op} rowNumber must be a positive integer`);
+    }
+    return {
+      rowNumber: op.rowNumber,
+      rowPosition: op.rowPosition ?? "end",
+    };
+  }
   if (op.beforePanelId) return { beforePanelId: op.beforePanelId };
   if (op.afterPanelId) return { afterPanelId: op.afterPanelId };
   if (op.index !== undefined) return { index: op.index };
   return { position: op.position ?? "bottom" };
 }
 
+function isVisualPlacementTarget(
+  target: DashboardPlacementTarget,
+): target is VisualPlacementTarget {
+  return "nextToPanelId" in target || "rowNumber" in target;
+}
+
+function dashboardColumns(config: Record<string, unknown>): number {
+  return clampDashboardColumns(config.columns);
+}
+
+function panelsForLayout(config: Record<string, unknown>): SqlPanel[] {
+  return panelsFromConfig(config) as unknown as SqlPanel[];
+}
+
+function setGroupColumns(
+  config: Record<string, unknown>,
+  sectionPanelId: string | null,
+  columns: number,
+): void {
+  if (sectionPanelId === null) {
+    config.columns = columns;
+    return;
+  }
+  const section = requirePanel(panelsFromConfig(config), sectionPanelId);
+  section.columns = columns;
+}
+
+function resolveVisualDropSlot(
+  config: Record<string, unknown>,
+  target: VisualPlacementTarget,
+): DashboardDropSlot {
+  const groups = buildDashboardPanelGroups(
+    panelsForLayout(config),
+    dashboardColumns(config),
+  );
+
+  if ("nextToPanelId" in target) {
+    for (const group of groups) {
+      for (let rowIndex = 0; rowIndex < group.rows.length; rowIndex++) {
+        const row = group.rows[rowIndex];
+        const columnIndex = row.panels.findIndex(
+          (panel) => panel.id === target.nextToPanelId,
+        );
+        if (columnIndex >= 0) {
+          return {
+            type: "column",
+            groupKey: group.key,
+            rowIndex,
+            columnIndex: columnIndex + 1,
+          };
+        }
+      }
+    }
+    throw new Error(
+      `target ${missingPanelHelp(panelsFromConfig(config), target.nextToPanelId)}`,
+    );
+  }
+
+  let rowNumber = 1;
+  for (const group of groups) {
+    for (let rowIndex = 0; rowIndex < group.rows.length; rowIndex++) {
+      const row = group.rows[rowIndex];
+      if (rowNumber === target.rowNumber) {
+        return {
+          type: "column",
+          groupKey: group.key,
+          rowIndex,
+          columnIndex: target.rowPosition === "start" ? 0 : row.panels.length,
+        };
+      }
+      rowNumber++;
+    }
+  }
+
+  throw new Error(
+    `rowNumber ${target.rowNumber} was not found; dashboard has ${rowNumber - 1} visible row(s)`,
+  );
+}
+
+function ensureVisualDropSlotCapacity(
+  config: Record<string, unknown>,
+  panelId: string,
+  slot: DashboardDropSlot,
+): { columns: number; sectionPanelId: string | null } | null {
+  if (slot.type !== "column") return null;
+  const groups = buildDashboardPanelGroups(
+    panelsForLayout(config),
+    dashboardColumns(config),
+  );
+  const group = groups.find((item) => item.key === slot.groupKey);
+  const row = group?.rows[slot.rowIndex];
+  if (!group || !row) return null;
+  const rowContainsPanel = row.panels.some((panel) => panel.id === panelId);
+  const requiredColumns = rowContainsPanel
+    ? row.panels.length
+    : row.panels.length + 1;
+  if (requiredColumns > MAX_DASHBOARD_COLUMNS) {
+    throw new Error(
+      `row ${slot.rowIndex + 1} already has ${MAX_DASHBOARD_COLUMNS} panels; cannot place another panel in that row`,
+    );
+  }
+
+  return columnExpansionForDropSlot(groups, panelId, slot);
+}
+
+function moveSinglePanelToVisualTarget(
+  config: Record<string, unknown>,
+  panelId: string,
+  target: VisualPlacementTarget,
+): number {
+  if ("nextToPanelId" in target && target.nextToPanelId === panelId) {
+    throw new Error("nextTo target cannot be the moving panel itself");
+  }
+  requirePanel(panelsFromConfig(config), panelId);
+  const slot = resolveVisualDropSlot(config, target);
+  const expansion = ensureVisualDropSlotCapacity(config, panelId, slot);
+  const currentPanels = panelsForLayout(config);
+  const nextPanels = movePanelToDropSlot(
+    currentPanels,
+    panelId,
+    slot,
+    dashboardColumns(config),
+  );
+  if (nextPanels === currentPanels) {
+    throw new Error("visual placement did not change the dashboard layout");
+  }
+  config.panels = nextPanels;
+  if (expansion) {
+    setGroupColumns(config, expansion.sectionPanelId, expansion.columns);
+  }
+  return findPanelIndex(panelsFromConfig(config), panelId);
+}
+
 function findPanelIndex(
   panels: Array<Record<string, unknown>>,
   id: string,
@@ -418,7 +634,7 @@ function enhancePanelError(
 function insertPanel(
   config: Record<string, unknown>,
   panel: Record<string, unknown>,
-  target: PanelOrderTarget,
+  target: DashboardPlacementTarget,
 ): number {
   const panels = panelsFromConfig(config);
   const id = assertString(panel.id, "panel.id");
@@ -426,6 +642,28 @@ function insertPanel(
     throw new Error(`panel "${id}" already exists`);
   }
   const placeholderId = `__agent_native_insert_${id}`;
+  if (isVisualPlacementTarget(target)) {
+    const slot = resolveVisualDropSlot(config, target);
+    config.panels = [...panels, { ...panel, id: placeholderId }];
+    const expansion = ensureVisualDropSlotCapacity(config, placeholderId, slot);
+    const currentPanels = panelsForLayout(config);
+    const nextPanels = movePanelToDropSlot(
+      currentPanels,
+      placeholderId,
+      slot,
+      dashboardColumns(config),
+    );
+    if (nextPanels === currentPanels) {
+      throw new Error("visual placement did not change the dashboard layout");
+    }
+    config.panels = nextPanels;
+    if (expansion) {
+      setGroupColumns(config, expansion.sectionPanelId, expansion.columns);
+    }
+    const inserted = requirePanel(panelsFromConfig(config), placeholderId);
+    inserted.id = id;
+    return findPanelIndex(panelsFromConfig(config), id);
+  }
   config.panels = [...panels, { ...panel, id: placeholderId }];
   const result = movePanelsById(config, [placeholderId], target);
   const nextPanels = panelsFromConfig(config);
@@ -520,7 +758,7 @@ function duplicatePanel(
   panelIdToCopy: string,
   newPanelId: string,
   patch: Record<string, unknown>,
-  target: PanelOrderTarget,
+  target: DashboardPlacementTarget,
 ): number {
   const panels = panelsFromConfig(config);
   const source = requirePanel(panels, panelIdToCopy);
@@ -552,13 +790,25 @@ export function applyDashboardMutationOperations(
     try {
       switch (op.op) {
         case "movePanels": {
-          let result;
-          try {
-            result = movePanelsById(
+          const target = targetFromOperation(op);
+          if (isVisualPlacementTarget(target)) {
+            if (op.panelIds.length !== 1) {
+              throw new Error(
+                "row-aware visual placement supports one moving panel at a time",
+              );
+            }
+            const index = moveSinglePanelToVisualTarget(
               config,
-              op.panelIds,
-              targetFromOperation(op),
+              op.panelIds[0],
+              target,
             );
+            changedPanelIds.add(op.panelIds[0]);
+            commandLog.push(`movePanels(${op.panelIds[0]}) -> index ${index}`);
+            break;
+          }
+          let result;
+          try {
+            result = movePanelsById(config, op.panelIds, target);
           } catch (err) {
             enhancePanelError(config, err);
           }
@@ -887,6 +1137,31 @@ function targetFromChainCall(call: ParsedCall): MutationTarget {
     case "moveToIndex":
     case "atIndex":
       return { index: assertNumber(call.args[0], `${call.name} index`) };
+    case "moveNextTo":
+    case "nextTo":
+      return {
+        nextToPanelId: assertString(call.args[0], `${call.name} panelId`),
+      };
+    case "moveToRow":
+    case "moveToRowEnd":
+    case "atRow":
+    case "atRowEnd":
+      return {
+        rowNumber: assertPositiveInteger(
+          call.args[0],
+          `${call.name} rowNumber`,
+        ),
+        rowPosition: "end",
+      };
+    case "moveToRowStart":
+    case "atRowStart":
+      return {
+        rowNumber: assertPositiveInteger(
+          call.args[0],
+          `${call.name} rowNumber`,
+        ),
+        rowPosition: "start",
+      };
     default:
       throw new Error(
         `unsupported placement method "${call.name}".${methodHelp(call.name, PLACEMENT_METHODS)}`,
@@ -904,6 +1179,14 @@ function operationFromPanelCommand(
     case "moveBefore":
     case "moveAfter":
     case "moveToIndex":
+    case "moveNextTo":
+    case "nextTo":
+    case "moveToRow":
+    case "moveToRowStart":
+    case "moveToRowEnd":
+    case "atRow":
+    case "atRowStart":
+    case "atRowEnd":
       return [
         {
           op: "movePanels",

package/corpus/templates/analytics/actions/get-sql-dashboard.ts

@@ -22,6 +22,7 @@ function dashboardLayoutSummary(config: Record<string, unknown>) {
   const columns = clampDashboardColumns(config.columns);
   const groups = buildDashboardPanelGroups(panels, columns);
   const panelOrder = getPanelOrder(config);
+  let visibleRowNumber = 1;
 
   return {
     panelCount: panelOrder.length,
@@ -32,10 +33,14 @@ function dashboardLayoutSummary(config: Record<string, unknown>) {
       sectionId: group.section?.id ?? null,
       sectionTitle: group.section?.title ?? null,
       columns: group.columns,
-      rows: group.rows.map((row, rowIndex) => ({
-        rowIndex,
-        panelIds: row.panels.map((panel) => panel.id),
-      })),
+      rows: group.rows.map((row, rowIndex) => {
+        const rowNumber = visibleRowNumber++;
+        return {
+          rowNumber,
+          rowIndex,
+          panelIds: row.panels.map((panel) => panel.id),
+        };
+      }),
     })),
   };
 }

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

@@ -27,6 +27,20 @@ const mutationTargetSchema = {
   index: z.number().int().nonnegative().optional(),
   beforePanelId: z.string().optional(),
   afterPanelId: z.string().optional(),
+  nextToPanelId: z
+    .string()
+    .optional()
+    .describe("Place the panel in the same visible row, after this panel id."),
+  rowNumber: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("1-based visible row number for row-aware placement."),
+  rowPosition: z
+    .enum(["start", "end"])
+    .optional()
+    .describe("Where in rowNumber to place the panel. Defaults to end."),
 };
 
 const mutationOperationSchema = z.discriminatedUnion("op", [
@@ -101,8 +115,9 @@ const apiHelp =
   "Constrained TypeScript-like dashboard mutation script. The server parses only calls on `dashboard`; it does not execute arbitrary JavaScript. " +
   "No variables, imports, loops, functions, templates, network, filesystem, or DB access. Arguments must be JSON-compatible literals, so quote object keys. " +
   "Subjects: dashboard.set, dashboard.panel, dashboard.panels, dashboard.panelsMatching, dashboard.section, dashboard.insertPanel. " +
-  "Selection methods: moveToTop, moveToBottom, moveBefore, moveAfter, moveToIndex, remove, set, setTitle, setSql, setWidth, setConfig, setConfigPath, duplicate. " +
-  `Examples: ${DASHBOARD_MUTATION_EXAMPLES.slice(0, 3).join(" ")}`;
+  "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. " +
+  `Examples: ${DASHBOARD_MUTATION_EXAMPLES.slice(0, 5).join(" ")}`;
 
 function resolveScope() {
   const orgId = getRequestOrgId() || null;
@@ -177,6 +192,7 @@ export default defineAction({
   description:
     "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. " +
     "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]}`,

package/corpus/templates/analytics/actions/query-agent-native-analytics.ts

@@ -15,14 +15,24 @@ function resolveScope() {
 
 export default defineAction({
   description:
-    "Query first-party analytics events recorded through this app's analytics collector endpoint (/track) and session replay summaries recorded through /api/analytics/replay. Use this for questions about app/site traffic, product events, template/app usage, conversions, session recordings, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events and session_recordings only; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org.",
+    "Query first-party analytics events recorded through this app's analytics collector endpoint (/track) and session replay summaries recorded through /api/analytics/replay. Use this for questions about app/site traffic, product events, template/app usage, conversions, session recordings, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events and session_recordings only; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. analytics_events columns include event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, and context. session_recordings columns include id, session_id, user_id, anonymous_id, user_key, started_at, ended_at, duration_ms, chunk_count, event_count, page_count, error_count, rage_click_count, app, template, status, first_url, last_url, path, hostname, referrer, and metadata.",
   schema: z.object({
     sql: z
       .string()
       .describe(
-        "Read-only SQL over analytics_events and session_recordings, e.g. SELECT event_name, COUNT(*) AS events FROM analytics_events WHERE timestamp >= '2026-05-01T04:00:00Z' AND timestamp < '2026-05-02T04:00:00Z' GROUP BY event_name ORDER BY events DESC",
+        "Read-only SQL over analytics_events and session_recordings. Use literal values, not bind placeholders. Example: SELECT event_name, COUNT(*) AS events FROM analytics_events WHERE timestamp >= '2026-05-01T04:00:00Z' AND timestamp < '2026-05-02T04:00:00Z' GROUP BY event_name ORDER BY events DESC",
       ),
   }),
+  outputSchema: z.object({
+    rows: z.array(z.record(z.string(), z.unknown())),
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        type: z.string(),
+      }),
+    ),
+  }),
+  readOnly: true,
   http: false,
   run: async (args) => {
     return queryFirstPartyAnalytics(args.sql, resolveScope());

package/corpus/templates/analytics/app/hooks/use-replay-storage-status.ts

@@ -0,0 +1,66 @@
+import { agentNativePath } from "@agent-native/core/client";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect } from "react";
+
+export interface ReplayStorageStatus {
+  configured: boolean;
+  activeProvider?: { id: string; name: string } | null;
+  builderConfigured?: boolean;
+}
+
+export const REPLAY_STORAGE_STATUS_KEY = [
+  "analytics",
+  "replay-storage-status",
+] as const;
+
+export async function fetchReplayStorageStatus(): Promise<ReplayStorageStatus> {
+  let uploadStatus: ReplayStorageStatus | null = null;
+  try {
+    const r = await fetch(agentNativePath("/_agent-native/file-upload/status"));
+    uploadStatus = r.ok ? ((await r.json()) as ReplayStorageStatus) : null;
+    if (uploadStatus?.configured) return uploadStatus;
+  } catch {
+    // Fall through to the Builder status check.
+  }
+
+  try {
+    const r = await fetch(agentNativePath("/_agent-native/builder/status"));
+    const builderStatus = r.ok
+      ? ((await r.json()) as { configured?: boolean })
+      : null;
+    if (builderStatus?.configured) {
+      return {
+        configured: true,
+        activeProvider: { id: "builder", name: "Builder.io" },
+        builderConfigured: true,
+      };
+    }
+  } catch {
+    // Treat an unreachable status route as not configured.
+  }
+
+  return {
+    configured: false,
+    activeProvider: uploadStatus?.activeProvider ?? null,
+    builderConfigured: uploadStatus?.builderConfigured ?? false,
+  };
+}
+
+export function useReplayStorageStatus() {
+  return useQuery({
+    queryKey: REPLAY_STORAGE_STATUS_KEY,
+    queryFn: fetchReplayStorageStatus,
+    staleTime: 60_000,
+  });
+}
+
+export function usePrefetchReplayStorageStatus() {
+  const qc = useQueryClient();
+  useEffect(() => {
+    qc.prefetchQuery({
+      queryKey: REPLAY_STORAGE_STATUS_KEY,
+      queryFn: fetchReplayStorageStatus,
+      staleTime: 60_000,
+    });
+  }, [qc]);
+}