@agent-native/core 0.85.7 → 0.86.0

package/corpus/core/src/templates/workspace-core/.agents/skills/observability/SKILL.md

@@ -232,3 +232,25 @@ This layer is optional and **no-op by default**:
 - Even with the api package installed, it ships a default no-op tracer. Spans become real only once the **host registers a `TracerProvider`** (via `@opentelemetry/sdk-node` or similar). The framework deliberately does not depend on the heavy SDK/exporter packages and never registers a provider itself — instrumentation is opt-in by the embedding app.
 
 The loop emits `agent.run` (with `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model`), `tool.call` (`tool.name` + status), and `llm.call` spans, each finished with OK/ERROR status. This is purely additive to the in-house `agent_trace_spans` / `agent_trace_summaries` tables. Source: `packages/core/src/observability/tracing.ts` + `traces.ts`. See the Observability doc for the full table.
+
+## Tracking Bridge
+
+Instrumented agent loops also emit one server-side tracking event per completed
+LLM generation:
+
+- Event name: `$ai_generation`
+- Provider path: `track()` from `@agent-native/core/tracking`, so configured
+  PostHog, Agent Native Analytics, Mixpanel, Amplitude, and webhook providers
+  receive it through the same best-effort fan-out as other tracking events.
+- PostHog shape: uses AI Observability properties such as `$ai_trace_id`,
+  `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`,
+  `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and `$ai_is_error`.
+- Agent Native Analytics shape: the same event lands in `analytics_events` with
+  mirrored query-friendly properties such as `run_id`, `thread_id`,
+  `cost_cents_x100`, `duration_ms`, `tool_calls`, `successful_tools`,
+  `failed_tools`, and `status`.
+
+Do not build a separate LLM-observability ingestion API unless there is a clear
+reason the tracking provider registry cannot express the use case. Keep prompt,
+tool input, and model output content out of tracking by default; use the existing
+observability config flags for local trace content capture.

package/corpus/core/src/templates/workspace-core/.agents/skills/real-time-collab/SKILL.md

@@ -249,34 +249,97 @@ type PatchDeckOp =
 Concurrent edits to different slides both succeed at the action level; there
 is no whole-deck LWW. Forms use the same shape with field-level ops.
 
-## Collaborative Undo Scoping (Y.UndoManager)
+## Agent Presence & Lingering Edit Highlights
+
+The agent is a *visible* collaborator, not a silent content-swapper. Core
+handles most of this automatically:
+
+- **Auto-presence on agent writes** — any `applyText` / `searchAndReplace` /
+  `applyJson` / `applyPatchOps` call with `requestSource: "agent"` publishes
+  an agent awareness entry plus a `recentEdits` attribution describing what
+  changed. Actions that route writes through the collab layer get full
+  presence UX with zero extra wiring.
+- **Linger** — `agentLeaveDocument` (and the auto-presence path) keeps the
+  agent's awareness entry alive for ~6s (`AGENT_PRESENCE_LINGER_MS`) after the
+  last edit so viewers see who just changed what. Pass `{ lingerMs: 0 }` to
+  clear immediately. On serverless the linger degrades to the 30s awareness
+  expiry.
+- **`agentTouchDocument(docId, { edit, metadata })`** — refcount-neutral
+  presence + attribution for actions that write SQL directly (no collab doc).
+  `edit.descriptor` is one of `{kind:"text",quote}`, `{kind:"selector",selector}`,
+  `{kind:"paths",paths}`, `{kind:"doc"}`.
+- **Durable across instances** — awareness is mirrored to the additive
+  `_collab_awareness` table, so presence written by an action in one
+  serverless invocation is visible to clients polling any other instance.
+
+Client rendering:
+
+```tsx
+import {
+  usePresence, useRecentEdits, RecentEditHighlights,
+  PresenceBar, LiveCursorOverlay, RemoteSelectionRings,
+} from "@agent-native/core/client";
+
+const { others, setPresence } = usePresence(awareness, ydoc?.clientID);
+const recentEdits = useRecentEdits(others); // non-expired, ~6s TTL
+
+<RecentEditHighlights
+  edits={recentEdits}
+  containerRef={containerRef}
+  resolveRect={(edit) => /* map descriptor → DOMRect, or null */ null}
+/>
+```
+
+Humans get the same treatment: call `publishRecentEdit(awareness, { descriptor })`
+from local mutation paths so peers see lingering highlights for human edits
+too. `CollabUser.avatarUrl` puts faces on avatars, cursors, and edit tags.
+
+## Per-User Undo (never revert someone else's work)
 
-Scope undo/redo to the local user's own edits so peer and agent changes are
-never accidentally reversed:
+Undo must only reverse the local user's edits — and must never restore a
+whole-document snapshot (that clobbers concurrent edits by peers/the agent).
+Core ships two primitives:
+
+**Yjs surfaces — `useCollabUndo`** (wraps `Y.UndoManager` lifecycle):
 
 ```ts
-import * as Y from "yjs";
+import { useCollabUndo } from "@agent-native/core/client";
+
+const { undo, redo, canUndo, canRedo, transactLocal, localOrigin } =
+  useCollabUndo({
+    ydoc,
+    scope: (doc) => doc.getText("content"),
+    captureTimeout: 500,
+    enableKeyboardShortcuts: true, // Mod+Z / Shift+Mod+Z / Mod+Y
+  });
 
-const LOCAL_EDIT_ORIGIN = "local";
+// Tag every local mutation so it is captured:
+transactLocal(() => { /* mutate shared types */ });
+```
 
-const undoManager = new Y.UndoManager(ydoc.getText("content"), {
-  trackedOrigins: new Set([LOCAL_EDIT_ORIGIN]),
-  captureTimeout: 800, // coalesces rapid slider drags into one undo step
-});
+Remote (`"remote"`) and agent (`"agent"`/`"server"`) origins are never
+captured. The manager is recreated/destroyed automatically when `ydoc`
+changes. (TipTap's Collaboration extension already provides this behavior
+for its own editor content.)
 
-// Mark local edits with the tracked origin
-ydoc.transact(() => {
-  // apply local change
-}, LOCAL_EDIT_ORIGIN);
+**Op-based surfaces (slides/forms) — `useLocalOpUndo`**: record inverse
+granular ops for each local mutation; undo replays the inverse ops through
+your normal granular mutation path:
 
-undoManager.undo(); // only reverses LOCAL_EDIT_ORIGIN transactions
-undoManager.redo();
+```ts
+const { push, undo, redo, canUndo, canRedo } = useLocalOpUndo({
+  apply: (ops) => applyGranularOps(ops), // your patch path
+});
+
+push({
+  undo: [{ type: "patch", slideId, fields: prevFields }],
+  redo: [{ type: "patch", slideId, fields: nextFields }],
+  coalesceKey: `${slideId}:content`, // merge rapid bursts into one step
+});
 ```
 
-Rules:
-- Pass a `Set` to `trackedOrigins` — not an array.
-- Remote (`"remote"`) and agent (`"agent"`) origins are never captured.
-- Recreate and destroy the manager when the active document changes.
+Entries whose target no longer exists should fail soft (skip), never reset
+the whole history — external/agent edits must not wipe the user's undo stack.
 
 ## Common Pitfalls
 

package/corpus/core/src/templates/workspace-core/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/corpus/core/src/templates/workspace-core/.agents/skills/storing-data/SKILL.md

@@ -25,6 +25,14 @@ Agent-native apps use Drizzle ORM over the configured SQL backend. Local develop
 
 For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |

package/corpus/core/src/templates/workspace-core/.agents/skills/tracking/SKILL.md

@@ -141,6 +141,7 @@ Other framework-level baseline events:
 - `signup` from Better Auth user creation, with `auth_provider`, `auth_user_id`, and first-touch referral attribution (`referral_source`, `referrer_user`, `referral_medium`, `referral_campaign`, `utm_*`, `first_touch_path`, `landing_referrer` — see "Referral / viral attribution" above)
 - `builder connect clicked` and `builder connect popup blocked` from browser Connect Builder CTAs
 - `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes, with LLM connection context when resolvable
+- `$ai_generation` from instrumented agent loops, with PostHog AI Observability fields such as `$ai_trace_id`, `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`, `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and mirrored Agent Native query fields such as `run_id`, `thread_id`, `cost_cents_x100`, `duration_ms`, `tool_calls`, and `status`. Prompt, tool argument, and output content is not included by default.
 
 For new lifecycle events, call `track()` server-side when the server is the source of truth, and `trackEvent()` client-side only for browser interactions.
 

package/corpus/core/src/tracking/providers.ts

@@ -134,16 +134,37 @@ function shouldSkipAgentNativeAnalyticsForLocalhost(): boolean {
 
 // ─── PostHog ───────────────────────────────────────────────────────────────
 
+function isPostHogAiObservabilityEvent(eventName: string): boolean {
+  return eventName.startsWith("$ai_");
+}
+
 function createPostHogProvider(apiKey: string, host: string): TrackingProvider {
   return {
     name: "posthog",
     track(event: TrackingEvent) {
+      const distinctId = event.userId || "anonymous";
+      if (isPostHogAiObservabilityEvent(event.name)) {
+        enqueue(
+          `${host}/i/v0/e/`,
+          JSON.stringify({
+            api_key: apiKey,
+            event: event.name,
+            properties: {
+              distinct_id: distinctId,
+              ...event.properties,
+              timestamp: event.timestamp,
+            },
+          }),
+        );
+        return;
+      }
+
       enqueue(
         `${host}/capture/`,
         JSON.stringify({
           api_key: apiKey,
           event: event.name,
-          distinct_id: event.userId || "anonymous",
+          distinct_id: distinctId,
           properties: {
             ...event.properties,
             timestamp: event.timestamp,

package/corpus/templates/analytics/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/corpus/templates/analytics/.agents/skills/session-replay/SKILL.md

@@ -46,10 +46,15 @@ agent answers about browser recordings in the Analytics template.
   custom events tagged `agent-native.console` and `agent-native.network`.
 - Capture is on by default whenever session replay is enabled. Tune or disable
   it with the `console` / `network` options on the session replay config; each
-  accepts a boolean or an options object (`{ maxEvents?: number }`).
-- Privacy bounds: request/response bodies and headers are never captured, URLs
-  are scrubbed, messages are truncated, and recorder self-traffic (the replay
-  ingest and tracking endpoints) is excluded.
+  accepts a boolean or an options object (`{ maxEvents?: number }`); `network`
+  also accepts `captureErrorBodies` (default true) and `maxErrorBodyLength`
+  (default 2048) to control the bounded 5xx response-body snippet.
+- Privacy bounds: request bodies and headers are never captured. Response
+  bodies are captured only as a bounded, redacted snippet for 5xx (server
+  error) responses, capped at `maxErrorBodyLength` chars; non-5xx and
+  network-failure (status 0) responses never carry a body. URLs are scrubbed,
+  messages are truncated, and recorder self-traffic (the replay ingest and
+  tracking endpoints) is excluded.
 - Per-session budgets: 1000 console events and 2000 network events, with a
   truncation notice event once a budget is hit.
 - On ingest, `deriveReplaySignals` computes the real `errorCount` from tagged
@@ -65,9 +70,19 @@ agent answers about browser recordings in the Analytics template.
 - The agent timeline includes `console-error` / `network-error` markers; error
   markers are kept preferentially under the 200-marker cap.
 - `apis.diagnostics` advertises the fuller bounded list:
-  `GET /api/session-replay/agent-diagnostics.json?id=<recordingId>&agent_access=<token>&kind=console|network|all&level=<level>&limit=<n>`
+  `GET /api/session-replay/agent-diagnostics.json?id=<recordingId>&agent_access=<token>&kind=console|network|all&level=<level>&limit=<n>&offset=<n>&fromMs=<n>&toMs=<n>`
   (limit defaults to 200, max 500). It uses the same recording-scoped
   `agent_access` token as the other agent JSON APIs.
+- `offset` and `fromMs`/`toMs` (inclusive offsetMs window) enable full
+  enumeration of a session's captured entries: page with `offset`, or window
+  with `fromMs`/`toMs` around a timeline marker's `offsetMs`. Providing any of
+  these switches ordering to strictly chronological (no errors-first
+  reshuffle) so pages are stable and disjoint. `total`/`errorCount`/
+  `warnCount`/`failedCount` reflect the filtered (windowed/level/kind)
+  population, not just the returned page, and each kind's response includes
+  `hasMore` alongside `truncated` so an agent can tell whether more entries
+  remain. Route validation rejects negative/non-numeric `offset`/`fromMs`/
+  `toMs` and `fromMs > toMs` with 400.
 
 ## Dev Tools Panel
 

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

@@ -25,6 +25,14 @@ Agent-native apps use Drizzle ORM over the configured SQL backend. Local develop
 
 For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |

package/corpus/templates/analytics/AGENTS.md

@@ -71,6 +71,25 @@ details live in `.agents/skills/`.
 - For shipped dashboard templates, call `list-dashboard-templates` first, then
   `install-dashboard-template` with the selected `templateId`. Do not recreate a
   catalog template by hand unless the user asks for a custom variant.
+- Agent LLM observability is collected through the same first-party tracking
+  API as product analytics. Core emits PostHog-compatible `$ai_generation`
+  events when emitting apps are configured with `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY`
+  and `AGENT_NATIVE_ANALYTICS_ENDPOINT` (or the default hosted endpoint). Query
+  these with `query-agent-native-analytics` using `event_name = '$ai_generation'`;
+  useful JSON properties include `$ai_trace_id` / `run_id`, `$ai_session_id` /
+  `thread_id`, `$ai_model` / `model`, `$ai_provider` / `provider`,
+  `$ai_input_tokens`, `$ai_output_tokens`, `cache_read_tokens`,
+  `cache_write_tokens`, `cost_cents_x100`, `$ai_total_cost_usd`, `duration_ms`
+  / `$ai_latency`, `status`, `tool_calls`, `successful_tools`, `failed_tools`,
+  and `$ai_error` / `error_message`. Do not expect prompts, tool args, or model
+  responses in these tracked events by default.
+- `/agents` is the Analytics home for core agent-admin surfaces. The default
+  Monitoring view embeds the shared observability dashboard for traces,
+  conversations, evals, experiments, and feedback. The Advanced menu opens
+  `/agents?view=database`, which embeds the shared Code-mode database admin
+  tool for table browsing, row editing, and SQL inspection. Keep future
+  agent-admin additions inside this route instead of adding many top-level
+  sidebar tabs.
 - For dashboard edits, default to `mutate-dashboard` with its typed
   `dashboard.*` script API. It supports id-based panel moves, title/SQL/config
   edits, inserts, duplication, removal, and dashboard field patches in one
@@ -136,8 +155,9 @@ details live in `.agents/skills/`.
 - `navigation` exposes current dashboard, analysis, source, chart, and selected
   context.
 - `navigate` moves the user to the relevant analytics view, including
-  `view="catalog"` for the template catalog and `view="sessions"` for session
-  replay.
+  `view="catalog"` for the template catalog, `view="sessions"` for session
+  replay, and `view="agents"` / `agentsView="database"` for agent monitoring
+  or advanced database admin.
 - Use `view-screen` when the active dashboard/chart context is unclear.
 
 ## Session Replay
@@ -155,14 +175,18 @@ details live in `.agents/skills/`.
   scoped to one recording for two hours; SSR embeds an agent discovery payload
   and the JSON APIs expose only summary/timeline metadata plus bounded event
   reads.
-- Recordings also capture console logs and network request metadata (no
-  bodies/headers, scrubbed URLs, truncated messages, per-session budgets);
-  ingest derives `errorCount`/`networkErrorCount` and adds
+- Recordings also capture console logs and network request metadata (request
+  bodies/headers never captured; response bodies captured only as bounded,
+  redacted 5xx snippets; scrubbed URLs, truncated messages, per-session
+  budgets); ingest derives `errorCount`/`networkErrorCount` and adds
   `console-error`/`network-error` timeline markers.
 - The agent context includes a bounded `diagnostics` section (errors first) and
   advertises `GET /api/session-replay/agent-diagnostics.json` with
   `kind`/`level`/`limit` params (limit max 500) under the same `agent_access`
-  token — the primary signal when debugging a user-reported issue.
+  token — the primary signal when debugging a user-reported issue. `offset` and
+  `fromMs`/`toMs` page/window the same endpoint in strictly chronological order
+  (with `hasMore`/`truncated` per kind) so an agent can enumerate every
+  captured entry in a large session.
 - The replay player has a Dev Tools panel with Console and Network tabs
   (filters, search, jump-to-seek, error badge); extend it rather than adding a
   separate replay debugging surface. See the `session-replay` skill.
@@ -185,6 +209,9 @@ details live in `.agents/skills/`.
 - `install-dashboard-template` installs a catalog template into normal
   SQL-backed dashboards. Required: `templateId`. Optional: `dashboardId`,
   `name`, `overwrite`, `forceNew`, and `mergePanels`.
+- The LLM observability dashboard template is `agent-observability-llm`. Install
+  it when the user wants model cost, token volume, latency, error rate, or top
+  expensive agent-run visibility from first-party `$ai_generation` events.
 - To add a template's panels to an existing dashboard, call
   `install-dashboard-template` with `mergePanels: true` and the existing
   `dashboardId`. It appends only the template panels whose id is not already

package/corpus/templates/analytics/actions/navigate.ts

@@ -4,13 +4,13 @@ import { z } from "zod";
 
 export default defineAction({
   description:
-    "Navigate the UI to a specific view, dashboard, analysis, extension, or Analytics session recording. For filter changes (dashboard filter query params like ?f_date=... or session filters like ?range=30d&q=signup), use the framework-level `set-search-params` tool instead of this action.",
+    "Navigate the UI to a specific view, dashboard, analysis, extension, Analytics session recording, or Analytics agent-admin surface. For filter changes (dashboard filter query params like ?f_date=... or session filters like ?range=30d&q=signup), use the framework-level `set-search-params` tool instead of this action.",
   schema: z.object({
     view: z
       .string()
       .optional()
       .describe(
-        "View to navigate to (ask, adhoc, analyses, extensions, sessions, catalog, data-dictionary, data-sources, settings)",
+        "View to navigate to (ask, adhoc, analyses, extensions, sessions, agents, catalog, data-dictionary, data-sources, settings)",
       ),
     dashboardId: z
       .string()
@@ -28,6 +28,10 @@ export default defineAction({
       .string()
       .optional()
       .describe("Session recording id to open (used with view=sessions)"),
+    agentsView: z
+      .enum(["monitoring", "database"])
+      .optional()
+      .describe("Agents subview to open (monitoring or database)"),
   }),
   http: false,
   run: async (args) => {
@@ -36,10 +40,11 @@ export default defineAction({
       !args.dashboardId &&
       !args.analysisId &&
       !args.extensionId &&
-      !args.recordingId
+      !args.recordingId &&
+      !args.agentsView
     ) {
       throw new Error(
-        "At least --view, --dashboardId, --analysisId, --extensionId, or --recordingId is required.",
+        "At least --view, --dashboardId, --analysisId, --extensionId, --recordingId, or --agentsView is required.",
       );
     }
     const nav: Record<string, string> = {};
@@ -60,6 +65,10 @@ export default defineAction({
       nav.recordingId = args.recordingId;
       if (!args.view) nav.view = "sessions";
     }
+    if (args.agentsView) {
+      nav.agentsView = args.agentsView;
+      if (!args.view) nav.view = "agents";
+    }
     await writeAppState("navigate", nav);
 
     const parts: string[] = [];
@@ -68,6 +77,7 @@ export default defineAction({
     if (nav.analysisId) parts.push(`analysis:${nav.analysisId}`);
     if (nav.extensionId) parts.push(`extension:${nav.extensionId}`);
     if (nav.recordingId) parts.push(`recording:${nav.recordingId}`);
+    if (nav.agentsView) parts.push(`agents:${nav.agentsView}`);
     return `Navigating to ${parts.join(" ")}`;
   },
 });

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

@@ -15,7 +15,7 @@ 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. 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.",
+    "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, 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, and error_message/$ai_error. 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()

package/corpus/templates/analytics/actions/view-screen.ts

@@ -194,6 +194,63 @@ export default defineAction({
           ),
         }));
       }
+    } else if (nav?.view === "agents") {
+      screen.page = "agents";
+      screen.agentsView = nav?.agentsView || "monitoring";
+      screen.agentAdminSurfaces = [
+        {
+          id: "monitoring",
+          label: "Monitoring",
+          path: "/agents",
+          includes: [
+            "agent traces",
+            "agent conversations",
+            "eval results",
+            "experiments",
+            "feedback",
+          ],
+        },
+        {
+          id: "database",
+          label: "Database",
+          path: "/agents?view=database",
+          advanced: true,
+          codeModeOnly: true,
+          includes: ["table browser", "row editor", "SQL editor"],
+        },
+      ];
+      const email = getRequestUserEmail();
+      if (email) {
+        const orgId = getRequestOrgId() || null;
+        const [keys, catalog] = await Promise.all([
+          listAnalyticsPublicKeys({
+            userEmail: email,
+            orgId,
+          }),
+          listDashboardCatalog({
+            email,
+            orgId,
+          }),
+        ]);
+        const llmTemplate = catalog.find(
+          (template) => template.id === "agent-observability-llm",
+        );
+        screen.firstPartyAnalytics = {
+          activeKeys: keys.filter((key: any) => !key.revokedAt).length,
+          serverEnv: "AGENT_NATIVE_ANALYTICS_PUBLIC_KEY",
+          browserEnv: "VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY",
+        };
+        if (llmTemplate) {
+          screen.llmObservabilityDashboard = {
+            templateId: llmTemplate.id,
+            name: llmTemplate.name,
+            installed: llmTemplate.installed,
+            installedDashboardIds: llmTemplate.installedDashboards.map(
+              (dashboard) => dashboard.id,
+            ),
+          };
+        }
+      }
     } else if (nav?.view === "settings") {
       screen.page = "settings";
       const email = getRequestUserEmail();

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

@@ -62,15 +62,33 @@ interface ExtensionSearchItem {
 }
 
 const defaultTools = [
+  {
+    id: "agents",
+    nameKey: "navigation.agents",
+    href: "/agents",
+    keywords: [
+      "agent monitoring",
+      "observability",
+      "evals",
+      "experiments",
+      "feedback",
+      "database",
+      "db admin",
+      "ab testing",
+      "llm",
+    ],
+  },
   {
     id: "explorer",
     nameKey: "commandPalette.toolExplorer",
     href: "/dashboards/explorer",
+    keywords: [],
   },
   {
     id: "customer-health",
     nameKey: "commandPalette.toolCustomerHealth",
     href: "/dashboards/customer-health",
+    keywords: [],
   },
 ];
 
@@ -414,7 +432,11 @@ export function CommandPalette() {
               <CommandItem
                 key={`tool-${tool.id}`}
                 onSelect={() => go(tool.href)}
-                keywords={commandPaletteKeywords(t(tool.nameKey), "tool")}
+                keywords={commandPaletteKeywords(
+                  t(tool.nameKey),
+                  "tool",
+                  ...tool.keywords,
+                )}
               >
                 <IconTool className="me-2 h-4 w-4 text-muted-foreground" />
                 {t(tool.nameKey)}

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

@@ -20,6 +20,7 @@ const pageTitleKeys: Record<string, string> = {
   "/catalog": "navigation.templateCatalog",
   "/analyses": "navigation.analyses",
   "/sessions": "navigation.sessions",
+  "/agents": "navigation.agents",
   "/dashboards/explorer": "navigation.explorer",
   "/settings": "navigation.settings",
 };

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

@@ -14,6 +14,7 @@ import {
   IconReportAnalytics,
   IconSearch,
   IconArchive,
+  IconActivity,
   IconPin,
   IconPlus,
   IconBuilding,
@@ -2281,6 +2282,12 @@ export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
       href: "/sessions",
       active: location.pathname.startsWith("/sessions"),
     },
+    {
+      icon: IconActivity,
+      label: t("navigation.agents"),
+      href: "/agents",
+      active: location.pathname.startsWith("/agents"),
+    },
     {
       icon: IconDatabase,
       label: t("navigation.dataSources"),
@@ -2458,6 +2465,20 @@ export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
                 {t("navigation.sessions")}
               </Link>
 
+              {/* Agents link */}
+              <Link
+                to="/agents"
+                className={cn(
+                  "flex items-center gap-3 rounded-lg px-3 py-2 transition-all 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
                 to="/data-sources"