@agent-native/core 0.137.7 → 0.138.0

package/agent-native.eject.json

@@ -30,6 +30,7 @@
         "canva",
         "vercel",
         "github",
+        "fullstory",
         "slack",
         "asana",
         "hubspot",
@@ -92,6 +93,7 @@
         "gcloud",
         "github",
         "figma",
+        "fullstory",
         "gmail",
         "gong",
         "google_calendar",

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7581
+- template files: 7638

package/corpus/templates/analytics/.agents/skills/agent-native-docs/SKILL.md

@@ -31,6 +31,26 @@ the framework monorepo checkout.
 
 From a generated app directory:
 
+```bash
+pnpm action framework-search --pattern "defineAction"
+pnpm action framework-search --pattern "templates/*/actions/*.ts" --mode glob --scope source
+pnpm action framework-search --pattern "Agent(?:Panel|Sidebar)" --mode regex --scope source
+```
+
+Use `framework-search` first when a question may cross the docs and source
+boundary. It searches the version-matched framework docs, runtime-visible
+skills, readable Core or Toolkit package source, and first-party template
+corpus in one bounded read-only call. Use `scope: docs` or `scope: source` to
+narrow it, then use the existing focused readers for the page or file you need.
+
+The same tool is available in the headless `pnpm agent` loop and every built-in
+app agent. Its default substring mode is safest for ordinary questions; use
+`glob` for wildcard paths, `sql-like` for `%` and `_` wildcards, and `regex`
+for precise structural matches. Results are bounded, so refine the pattern or
+path instead of treating a truncated result as exhaustive.
+
+From a generated app directory, the lower-level readers remain available:
+
 ```bash
 pnpm action docs-search --query "<feature>"
 pnpm action docs-search --slug <slug>
@@ -41,9 +61,9 @@ pnpm action source-search --path templates/chat/actions/hello.ts
 pnpm action source-search --list
 ```
 
-The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
-read-only `source-search` tool with `query`, `path`, and `list`.
+The headless `pnpm agent` loop and built-in app agent also expose read-only
+`framework-search`, `docs-search`, and `source-search` tools. Use the unified
+tool for discovery, then the focused tools for full page or file reads.
 
 If the action runner is unavailable, search the package directly:
 

package/corpus/templates/analytics/.agents/skills/agent-native-toolkit/SKILL.md

@@ -65,6 +65,22 @@ Contextual agent UI is not a reason to expose every option at once. Start with
 the domain task's primary action, reveal review or configuration only when the
 current state needs it, and let the sidebar carry conversational depth.
 
+## Visual Direction And Workspace Variety
+
+Shared workspace behavior should be consistent without forcing every app into
+the same visual skin. Keep shell and component tokens semantic, then let each
+app declare a named direction in `DESIGN.md` before styling. A new app should
+choose its palette family and composition from the product context, compare
+nearby apps, and avoid inheriting their accent by default. Use the
+`frontend-design` visual-direction reference for mode, palette, type, density,
+shape, anti-references, and the `distill` / `typeset` / `colorize` / `layout` /
+`polish` / `audit` review vocabulary.
+
+Do not make warm beige plus terracotta the workspace fallback. Preserve a
+workspace-level brand when one exists; otherwise keep shared chrome neutral and
+allow app-owned accents to distinguish products while retaining accessible
+semantic states and the shared AgentSidebar contract.
+
 ## Discover Before Building
 
 Before creating an app-local version of repeated workspace or agent UI:

package/corpus/templates/analytics/.agents/skills/data-querying/SKILL.md

@@ -20,6 +20,21 @@ The analytics app connects to multiple data sources. This skill covers general p
 
 For events recorded by the analytics template itself via its `/track` endpoint, use `pnpm action query-agent-native-analytics --sql "SELECT ... FROM analytics_events ..."`. This includes pageviews, site/app traffic, template usage, app usage, and event counts collected by this analytics app. Pageviews and traffic can also live in GA4, BigQuery/warehouse tables, Mixpanel, PostHog, Amplitude, or another configured provider, so choose the source from the user's wording, connected-source status, existing dashboards, data dictionary, and user/org resources. Ask one concise clarification if multiple configured sources are plausible. Do not use `db-query` for data-source analysis; `db-query` is only for internal app tables and will confuse analytics questions. The shipped `agent-native-templates-first-party` SQL dashboard is the template engagement dashboard for the first-party collector source.
 
+For first-party counts, active-user, and retention questions, prefer the compact
+tenant-scoped daily event and user-day rollups. Use `analytics_events` only for a
+bounded recent drill-down with an explicit date/time range; the built-in source
+does not require a customer warehouse connection.
+
+Before a large or historical first-party query, call
+`get-first-party-analytics-health`. Keep Neon as the default while its status is
+`healthy` or `monitor`; a `recommend_bigquery` result means the app has observed
+1M+ events, repeated slow queries, or a timeout/30-second query. If BigQuery is
+not configured, use the returned setup link or `data-source-status --key
+bigquery` to guide the user through the existing Data Sources walkthrough. Do
+not silently move the collector: `/track` still lands in first-party Analytics,
+and BigQuery is the opt-in backend for high-volume or historical analysis after
+the user connects it.
+
 Example pageviews query for a local calendar day:
 
 ```sql

package/corpus/templates/analytics/.agents/skills/frontend-design/SKILL.md

@@ -34,6 +34,22 @@ Before coding, decide:
 
 Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
 
+## Visual Direction Contract
+
+Before styling a new app or workspace surface, define its product mode,
+audience, visual world, palette family, type treatment, composition, shape
+language, and anti-references in `DESIGN.md`. Read
+`references/visual-direction.md` for the direction families and review
+vocabulary. This is the Impeccable-inspired design contract for Agent-Native
+apps: understand the product, name the mode, deal a few coherent directions,
+commit to one, and audit the result instead of averaging back to a starter.
+
+Preserve an existing brand system and component library. When no brand exists,
+choose a deliberate direction based on the domain and compare sibling apps
+before selecting its accent family. Shared behavior and semantic token names
+should stay consistent; palette, density, composition, type contrast, and
+shape language should not be identical by default.
+
 ## Minimalism And Progressive Disclosure
 
 Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.
@@ -81,13 +97,13 @@ passed this requirement yet.
   operational apps, make a clear sans-serif hierarchy the default; reserve a
   serif or editorial face for a deliberate content preview or brand moment,
   not the whole application shell.
-- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
+- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes, default warm beige/terracotta, and default purple/blue gradients unless the brand demands them. New apps should choose a product-fitting accent family rather than inherit the previous app's color.
 - **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
 - **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
 - **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
 - **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
 
-**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option. Commit to one named direction, pair any reference with the reason it fits, and match implementation effort to the vision. If the brief is open, consider two or three coherent visual worlds, then commit to one instead of averaging them. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
 
 ## Agent-Native UI Rules
 
@@ -164,6 +180,9 @@ as an operator would use it repeatedly:
 - For review flows, stack the source/original first and the generated or safe
   result second by default. Use side-by-side comparison only when the content
   is short enough to scan without excessive horizontal reading.
+- Compare the result with sibling apps. Shared toolkit behavior should feel
+  consistent, but a repeated palette, hero composition, type pairing, and
+  radius language without a product reason is visual drift, not consistency.
 - Check the result at the target desktop width and a narrow width. If the first
   viewport feels like documentation instead of a tool, subtract again.
 
@@ -216,6 +235,8 @@ For substantial frontend work:
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,
    `portalContainer`, and z-index stacking checks.
+6. For a new app or a visual redesign, review `DESIGN.md` against the rendered
+   surface and run the anti-slop audit in `references/visual-direction.md`.
 
 ## Related Skills
 

package/corpus/templates/analytics/.agents/skills/frontend-design/references/visual-direction.md

@@ -0,0 +1,99 @@
+# Visual Direction Reference
+
+Use this reference when a new app or workspace needs a visual point of view and
+does not already have an established brand system. It adapts the useful parts
+of Impeccable's workflow: understand the product, name the surface mode, deal
+several coherent directions, commit to one, and audit the result for defaults
+that became the design by accident.
+
+## The direction contract
+
+Before writing UI, capture these decisions in the app's `DESIGN.md`:
+
+| Decision             | What to record                                                      |
+| -------------------- | ------------------------------------------------------------------- |
+| Product mode         | `operate`, `read`, `persuade`, or `experience`                      |
+| Audience and cadence | Who uses it, how often, and under what conditions                   |
+| Visual world         | A short name and the feeling it creates                             |
+| Palette family       | The semantic accent family and neutral undertone                    |
+| Type treatment       | Sans-first, editorial contrast, or display-led emphasis             |
+| Composition          | Dense console, focused workbench, document, canvas, or guided steps |
+| Shape language       | Quiet corners, crisp geometry, or soft utility surfaces             |
+| Anti-references      | Defaults this app must not drift toward                             |
+
+`DESIGN.md` is a portable design contract, not a license to bypass the app's
+tokens or component system. If the app already has a brand system, document it
+and preserve it. If it does not, choose a direction before styling.
+
+## Palette families
+
+Use one family as an accent and keep the rest of the system semantic and quiet.
+These are starting points, not a fixed theme library:
+
+| Family           | Good fit                                    | Typical character                 |
+| ---------------- | ------------------------------------------- | --------------------------------- |
+| Ink / graphite   | Admin, security, sensitive review           | Serious, low-noise, high contrast |
+| Cobalt / sky     | Planning, collaboration, scheduling         | Clear, trustworthy, alert         |
+| Pine / teal      | Automation, systems, finance, data          | Calm, capable, grounded           |
+| Indigo / violet  | Slides, creative tools, research            | Exploratory, focused, expressive  |
+| Plum / berry     | Publishing, knowledge, editorial work       | Distinctive, thoughtful, human    |
+| Coral / rose     | Communication, people, customer workflows   | Warm, direct, social              |
+| Ochre / citron   | Lightweight planning or energetic utilities | Optimistic, sparing, directional  |
+| Paper / charcoal | Long-form reading, exports, approvals       | Tactile, restrained, legible      |
+
+Do not make warm beige plus terracotta the universal fallback. Do not rotate
+through saturated colors mechanically. Choose the family that supports the
+workflow, then verify contrast, dark mode, focus states, destructive states,
+and the sidebar boundary.
+
+## Variation without chaos
+
+Vary at least two independent axes when sibling apps share a workspace:
+
+- accent family or neutral undertone;
+- information density and page composition;
+- type contrast and display treatment;
+- radius and border language;
+- navigation emphasis and use of whitespace.
+
+Keep shared behavior, semantic token names, accessibility, and AgentSidebar
+placement consistent. The goal is a family of products, not five unrelated
+themes and not five copies of the same starter.
+
+For a batch of apps, keep a small direction ledger in the workspace
+`DESIGN.md` or the handoff. Record each app's mode, direction, and palette
+family, then choose a new family or a clearly different composition for the
+next app unless an existing brand requires reuse. Never copy a sibling's
+`global.css` palette block or treat the last app's accent as the generator
+default.
+
+## Review vocabulary
+
+Make one named intervention at a time so the agent can reason about the
+change:
+
+- `distill` - remove copy, controls, cards, and chrome that do not serve the
+  next decision;
+- `typeset` - repair hierarchy, measure, line length, and emphasis;
+- `colorize` - establish a restrained semantic palette and contrast states;
+- `layout` - repair grouping, density, alignment, and responsive composition;
+- `polish` - resolve the small visual inconsistencies after the structure is
+  right;
+- `audit` - check slop, accessibility, responsive behavior, and visual drift.
+
+Do not average several directions into a generic compromise. Deal two or three
+coherent options when the brief is open, select one, and encode the decision in
+tokens and `DESIGN.md`.
+
+## Anti-slop audit
+
+Before handoff, inspect the first viewport and ask:
+
+- Did the app inherit the neighboring app's palette or hero layout without a
+  product reason?
+- Are there equal-weight cards, status chips, helper paragraphs, or controls
+  that should be removed or disclosed?
+- Does the typography fit the product mode instead of decorating the shell?
+- Is the AgentSidebar distinct but quiet, with the domain page still primary?
+- Are focus, loading, empty, error, dark, and narrow-width states part of the
+  same design direction?

package/corpus/templates/analytics/AGENTS.md

@@ -4,8 +4,8 @@ Analytics is an agent-native BI workspace for data sources, queries, dashboards,
 charts, and warehouse integrations. Dashboards are the canonical user-facing
 artifact; legacy analyses remain readable only for compatibility.
 
-**This agent is Claude with BigQuery/Gong/HubSpot/Prometheus access.** Reason
-over fetched data here; do not suggest another AI tool.
+Use all connected sources and MCP tools; reason over fetched data here, and do
+not suggest another AI tool.
 
 Prompt cap: 6,000; put detail in `.agents/skills/*`.
 

package/corpus/templates/analytics/actions/get-first-party-analytics-health.ts

@@ -0,0 +1,65 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import {
+  getFirstPartyAnalyticsHealth,
+  unavailableFirstPartyAnalyticsHealth,
+} from "../server/lib/first-party-analytics-health.js";
+
+function resolveScope() {
+  const userEmail = getRequestUserEmail();
+  if (!userEmail) throw new Error("no authenticated user");
+  return { userEmail, orgId: getRequestOrgId() || null };
+}
+
+const healthSchema = z.object({
+  status: z.enum(["healthy", "monitor", "recommend_bigquery", "unavailable"]),
+  recommendation: z.enum(["none", "connect_bigquery", "use_bigquery"]),
+  reasons: z.array(z.enum(["event_volume", "slow_queries", "query_timeout"])),
+  observedAt: z.string(),
+  metrics: z.object({
+    eventCount: z.number(),
+    dailyRollupRows: z.number(),
+    firstEventDate: z.string().nullable(),
+    lastEventDate: z.string().nullable(),
+    spanDays: z.number(),
+    slowQueryCount24h: z.number(),
+    timeoutCount24h: z.number(),
+    errorCount24h: z.number(),
+    maxQueryDurationMs24h: z.number(),
+  }),
+  thresholds: z.object({
+    slowQueryMs: z.number(),
+    recommendEventCount: z.number(),
+    recommendSlowQueries24h: z.number(),
+    recommendMaxQueryMs: z.number(),
+  }),
+  bigQuery: z.object({
+    configured: z.boolean().nullable(),
+    missingRequiredKeys: z.array(z.string()),
+    setupLink: z.string(),
+  }),
+});
+
+export default defineAction({
+  description:
+    "Check whether the built-in first-party Analytics source is still a good fit for Neon/Postgres. Use this before recommending BigQuery for tracking data. It reads compact daily rollups and the small slow-query pressure ledger, never the raw event table. `healthy` means Neon is fine, `monitor` means keep Neon but watch growth, and `recommend_bigquery` means connect or use BigQuery for high-volume or historical queries. A recommendation is based on 1M+ observed events, three or more slow queries in 24 hours, or any query timeout/30-second query. The result also includes BigQuery credential status and a safe setup link without revealing credential values.",
+  schema: z.object({}),
+  outputSchema: healthSchema,
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async () => {
+    const scope = resolveScope();
+    try {
+      return await getFirstPartyAnalyticsHealth(scope);
+    } catch (error) {
+      console.warn("[first-party-analytics] Health check unavailable:", error);
+      return unavailableFirstPartyAnalyticsHealth();
+    }
+  },
+});

package/corpus/templates/analytics/actions/provider-api-catalog.ts

@@ -1,12 +1,9 @@
 import { createProviderApiCatalogAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
-import {
-  ANALYTICS_PROVIDER_API_IDS,
-  getAnalyticsProviderApiRuntime,
-} from "../server/lib/provider-api";
+import { getAnalyticsProviderApiRuntime } from "../server/lib/provider-api";
 
-const ProviderSchema = z.enum(ANALYTICS_PROVIDER_API_IDS);
+const ProviderSchema = z.string().min(1);
 
 export default createProviderApiCatalogAction(
   getAnalyticsProviderApiRuntime(),
@@ -15,7 +12,7 @@ export default createProviderApiCatalogAction(
       "List raw HTTP API capabilities for configured Analytics providers. Use before provider-api-request when canned actions are too narrow. Returns provider base URLs, auth style, credential key names, docs/spec URLs, placeholders, examples, and reusable corpus recipes; never returns secret values.",
     schema: z.object({
       provider: ProviderSchema.optional().describe(
-        "Optional provider id to inspect. Omit to list every provider API escape hatch.",
+        "Optional built-in or custom provider id to inspect. Omit to list every provider API escape hatch visible to this organization.",
       ),
     }),
     http: { method: "GET" },

package/corpus/templates/analytics/actions/provider-api-docs.ts

@@ -1,12 +1,9 @@
 import { createProviderApiDocsAction } from "@agent-native/core/provider-api/actions/provider-api";
 import { z } from "zod";
 
-import {
-  ANALYTICS_PROVIDER_API_IDS,
-  getAnalyticsProviderApiRuntime,
-} from "../server/lib/provider-api";
+import { getAnalyticsProviderApiRuntime } from "../server/lib/provider-api";
 
-const ProviderSchema = z.enum(ANALYTICS_PROVIDER_API_IDS);
+const ProviderSchema = z.string().min(1);
 const BooleanFromQuerySchema = z.preprocess(
   (value) => (typeof value === "string" ? value === "true" : value),
   z.boolean(),
@@ -28,7 +25,7 @@ export default createProviderApiDocsAction(getAnalyticsProviderApiRuntime(), {
     "Inspect provider API docs/spec metadata, or fetch a public provider docs/spec/changelog URL. Use this before arbitrary provider-api-request calls when the exact endpoint, filter operator, payload shape, pagination, or API version is uncertain.",
   schema: z.object({
     provider: ProviderSchema.describe(
-      "Provider whose API docs/spec to inspect.",
+      "Built-in or custom provider whose API docs/spec to inspect.",
     ),
     url: z
       .string()

package/corpus/templates/analytics/actions/provider-api-request.ts

@@ -2,13 +2,10 @@ import { createProviderApiRequestAction } from "@agent-native/core/provider-api/
 import { z } from "zod";
 
 import { requireRequestCredentialContext } from "../server/lib/credentials-context";
-import {
-  ANALYTICS_PROVIDER_API_IDS,
-  getAnalyticsProviderApiRuntime,
-} from "../server/lib/provider-api";
+import { getAnalyticsProviderApiRuntime } from "../server/lib/provider-api";
 import { ANALYTICS_APP_ID } from "../server/lib/provider-credentials";
 
-const ProviderSchema = z.enum(ANALYTICS_PROVIDER_API_IDS);
+const ProviderSchema = z.string().min(1);
 const MethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
 
 const PaginationSchema = z
@@ -83,7 +80,7 @@ export default createProviderApiRequestAction(
       "For APIs that page through POST bodies, pass cursorBodyPath instead of cursorParam.",
     schema: z.object({
       provider: ProviderSchema.describe(
-        "Configured provider API to call, e.g. hubspot, gong, slack, stripe, jira, bigquery, ga4, gcloud, grafana, sentry.",
+        "Configured built-in or custom provider API to call, e.g. hubspot, gong, slack, stripe, jira, bigquery, ga4, fullstory, or a provider registered for this organization.",
       ),
       method: MethodSchema.default("GET").describe("HTTP method to use."),
       path: z

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

@@ -15,12 +15,12 @@ function resolveScope() {
 
 export default defineAction({
   description:
-    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track) and session replay summaries recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, 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. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, tools, tools_truncated, delegated, delegation_protocol, caller_app, delegation_task_id, a2a_task_id, parent_run_id, parent_turn_id, and error_message/$ai_error. Agent Teams child runs use delegation_protocol = 'agent-team' and retain their own run_id while linking to the launching run through parent_run_id. The bounded tools array contains names, relative start times, durations, statuses, and coarse error classes only, never args or results; failed runs and interrupted tools remain queryable. 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.",
+    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track), compact daily rollups, identifiable user-day rollups, and session replay summaries recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, 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, analytics_event_daily_rollups, analytics_user_days, and session_recordings; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. Prefer analytics_event_daily_rollups for event counts and analytics_user_days for active-user or retention questions. Use analytics_events only for bounded recent drill-downs with an explicit event_date or timestamp range. Aggregate, project only needed columns, and add a LIMIT for raw or high-cardinality reads; do not issue an unbounded raw-event scan or paginate a large cohort. An explicit all-time or lifetime request remains all-time, so do not invent a default lower time bound. Safe scoped results are cached for up to five minutes for this agent action. 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. analytics_event_daily_rollups columns include tenant_key, owner_email, org_id, event_date, event_name, app, template, and event_count. analytics_user_days columns include tenant_key, owner_email, org_id, event_date, and user_key. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, tools, tools_truncated, delegated, delegation_protocol, caller_app, delegation_task_id, a2a_task_id, parent_run_id, parent_turn_id, and error_message/$ai_error. Agent Teams child runs use delegation_protocol = 'agent-team' and retain their own run_id while linking to the launching run through parent_run_id. The bounded tools array contains names, relative start times, durations, statuses, and coarse error classes only, never args or results; failed runs and interrupted tools remain queryable. 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. 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",
+        "Read-only SQL over analytics_events, analytics_event_daily_rollups, analytics_user_days, and session_recordings. Use literal values, not bind placeholders. Prefer the daily rollups for counts, active-user, and retention questions. For raw analytics_events reads, use an explicit event_date or timestamp range, aggregate or project only needed columns, and add a LIMIT; do not issue an unbounded raw-event scan or paginate a large cohort. An explicit all-time or lifetime request remains all-time, so do not invent a default lower time bound. Example: SELECT event_date, event_name, SUM(event_count) AS events FROM analytics_event_daily_rollups WHERE event_date >= '2026-05-01' AND event_date < '2026-06-01' GROUP BY event_date, event_name ORDER BY event_date, events DESC",
       ),
   }),
   outputSchema: z.object({
@@ -40,6 +40,6 @@ export default defineAction({
   http: false,
   publicAgent: { expose: true, readOnly: true, requiresAuth: true },
   run: async (args) => {
-    return queryFirstPartyAnalytics(args.sql, resolveScope());
+    return queryFirstPartyAnalytics(args.sql, resolveScope(), { cache: true });
   },
 });

package/corpus/templates/analytics/agent-native.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "onboarding": {
+    "firstRun": {
+      "development": "off",
+      "production": "connect-and-integrations"
+    }
+  },
+  "doctor": {
+    "failOnBuild": false
+  }
+}