@agent-native/core 0.99.3 → 0.100.1

package/corpus/core/src/shared/mcp-connect-content.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared copy and templates for connecting external MCP clients.
+ *
+ * Keep this module free of React and server-only imports so the server-rendered
+ * connect page and the client Agent access tab use the same instructions.
+ */
+
+export type McpConnectGuideId =
+  | "claude"
+  | "chatgpt"
+  | "cursor"
+  | "claude-code"
+  | "codex"
+  | "other";
+
+export interface McpConnectTemplateValues {
+  appName: string;
+  appUrl: string;
+  mcpUrl: string;
+  serverId: string;
+}
+
+export interface McpConnectGuide {
+  id: McpConnectGuideId;
+  label: string;
+  steps?: readonly string[];
+  intro?: string;
+  commandTemplate?: string;
+  configTemplate?: string;
+  action?: {
+    kind: "link" | "copy";
+    label: string;
+    href?: string;
+  };
+  note?: string;
+}
+
+export const MCP_CONNECT_MCP_URL_TEMPLATE = "{appUrl}/mcp";
+
+export const MCP_CONNECT_GUIDES: readonly McpConnectGuide[] = [
+  {
+    id: "claude",
+    label: "Claude",
+    steps: [
+      "Open Customize → Connectors in Claude.",
+      "Click the + button → Add custom connector.",
+      "Paste the MCP URL above, name it {appName}, click Connect.",
+      "On the consent page, click Authorize to approve mcp:read, mcp:write, mcp:apps.",
+    ],
+    action: {
+      kind: "link",
+      label: "Open Claude → Connectors",
+      href: "https://claude.ai/customize/connectors",
+    },
+    note: "Works in Claude web and Claude Desktop. Inline MCP Apps (charts, dashboards, drafts) render automatically inside the chat.",
+  },
+  {
+    id: "chatgpt",
+    label: "ChatGPT",
+    steps: [
+      "In ChatGPT, open Settings → Apps (Business/Enterprise/Edu workspaces with developer mode enabled).",
+      "Scroll to Advanced settings → Create app, paste the MCP URL above, name it {appName}.",
+      "Click Connect, sign in with your Agent-Native account, and approve mcp:read, mcp:write, mcp:apps.",
+    ],
+    action: {
+      kind: "link",
+      label: "Open ChatGPT",
+      href: "https://chatgpt.com/",
+    },
+    note: 'Got "Connector name already exists" but don\'t see it under Enabled apps? ChatGPT saves a hidden draft the moment you click Create — even if you closed the OAuth popup before approving. In Settings → Apps, scroll past Enabled apps to the Drafts section ("Private apps you\'ve created in developer mode"). Click the draft and either press Connect to finish OAuth, or use the ⋯ → Delete menu and re-create. Workspace admins may also need to enable custom connectors under org settings; each member still authorizes their own account.',
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    steps: [
+      "Open Cursor → Settings → MCP.",
+      "Click Add MCP Server, paste the MCP URL above, save.",
+      "When prompted, sign in with your Agent-Native account and approve the MCP scopes.",
+    ],
+    note: "Cursor supports remote-OAuth MCP servers, same paste-URL flow as Claude — no terminal needed.",
+  },
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    intro: "In your terminal, run:",
+    commandTemplate: "claude mcp add --transport http {serverId} {mcpUrl}",
+    action: { kind: "copy", label: "Copy command" },
+    note: "Then inside Claude Code type /mcp, choose {serverId}, and click Authenticate. Claude completes the OAuth flow itself — no static token needed.",
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    intro: "In your terminal, run:",
+    commandTemplate: "npx @agent-native/core@latest connect {appUrl}",
+    action: { kind: "copy", label: "Copy command" },
+    note: "Opens this page in your browser and writes Codex's ~/.codex/config.toml automatically. The same command works for Claude Cowork and Goose.",
+  },
+  {
+    id: "other",
+    label: "Other",
+    intro:
+      "Any MCP-compatible client with remote-OAuth support: paste the MCP URL above. For clients without OAuth, paste this .mcp.json snippet and generate a static bearer below:",
+    configTemplate: `{
+  "mcpServers": {
+    "{serverId}": {
+      "type": "http",
+      "url": "{mcpUrl}"
+    }
+  }
+}`,
+    action: { kind: "copy", label: "Copy config" },
+  },
+] as const;
+
+export const MCP_STATIC_TOKEN_FALLBACK = {
+  title: "Generate a static token",
+  state: "Advanced — clients without OAuth",
+  resultTitle: "Connection token created",
+  resultCopy:
+    "Paste this into your agent's MCP config. The token is shown only once.",
+} as const;
+
+export function interpolateMcpConnectTemplate(
+  template: string,
+  values: McpConnectTemplateValues,
+): string {
+  return template.replace(/\{(appName|appUrl|mcpUrl|serverId)\}/g, (_, key) => {
+    return values[key as keyof McpConnectTemplateValues];
+  });
+}

package/corpus/core/src/templates/default/app/routes/_index.tsx

@@ -74,6 +74,17 @@ export default function IndexPage() {
               {t("home.settingsDescription")}
             </p>
           </Link>
+          <Link
+            to="/agent"
+            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
+          >
+            <p className="text-[13px] font-medium text-foreground">
+              {t("settings.agentTitle")}
+            </p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              {t("settings.agentDescription")}
+            </p>
+          </Link>
         </div>
       </div>
     </div>

package/corpus/core/src/templates/default/app/routes/agent.tsx

@@ -0,0 +1,33 @@
+import { AgentTabsPage, useT } from "@agent-native/core/client";
+import { Link } from "react-router";
+
+export function meta() {
+  return [{ title: "Agent - {{APP_TITLE}}" }];
+}
+
+export default function AgentPage() {
+  const t = useT();
+
+  return (
+    <main className="min-h-screen bg-background px-6 py-10">
+      <div className="mx-auto w-full max-w-5xl space-y-6">
+        <div className="space-y-2">
+          <Link
+            to="/settings"
+            className="text-[13px] text-muted-foreground hover:text-foreground"
+          >
+            {t("settings.title")}
+          </Link>
+          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+            {t("settings.agentTitle")}
+          </h1>
+          <p className="text-[14px] leading-relaxed text-muted-foreground">
+            {t("settings.agentDescription")}
+          </p>
+        </div>
+
+        <AgentTabsPage className="min-h-[640px] rounded-lg border border-border/50" />
+      </div>
+    </main>
+  );
+}

package/corpus/core/src/templates/workspace-core/.agents/skills/agent-native-toolkit/SKILL.md

@@ -57,6 +57,12 @@ in the moment of agent use.
   missing-secret states, OAuth grants, and provider connection health.
 - **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
   approval, generative UI, progress, and screen-state exposure.
+- **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
+  `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
+  Access tabs plus a Personal/Organization scope toggle. The canonical home
+  for context transparency, MCP servers, A2A remote agents, recurring
+  jobs/automations, and external-client connect flows. See the `agent-page`
+  skill.
 - **History and recovery kit**: audit log, activity feed, version history,
   checkpoints, undo, redo, restore, and proof-of-done.
 - **Comments and review kit**: anchored comments, pins, mentions, review

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

@@ -0,0 +1,59 @@
+---
+name: agent-page
+description: >-
+  The full-page Agent surface (/agent) with Context, Files, Connections, Jobs,
+  and Access tabs. Use when mounting the Agent page in a template, adding an
+  app-specific tab, surfacing context transparency, MCP servers, A2A agents,
+  recurring jobs, or external-client connect flows in the UI.
+metadata:
+  internal: true
+---
+
+# Agent Page
+
+`AgentTabsPage` (from `@agent-native/core/client`, source
+`packages/core/src/client/agent-page/`) is the canonical full-page surface for
+everything that can influence the agent. Design principles:
+
+- The page answers "what can influence this agent, and why" — it is not a
+  generic admin console.
+- Capability and access stay separate: **Connections** is what this agent can
+  reach; **Access** is who can reach this agent.
+- It is a thin shell that re-hosts existing components (ResourcesPanel, MCP
+  hooks, AgentsSection, context X-Ray, jobs actions) — do not re-implement
+  those surfaces inside it.
+- Context must be inspectable, attributable, and governable — provenance and
+  governance tiers, not just a token meter.
+
+## Tabs
+
+| Tab | Contents |
+| --- | --- |
+| `context` | System-vs-conversation split meter, provenance-grouped system sections (governance tiers: required/inherited/user), live-thread manifest. Backed by `context-preview-get` / `context-manifest-get` (see `context-xray` skill). |
+| `files` | ResourcesPanel (skills, instructions, memory, uploads) with the virtual `mcp-servers/` folder hidden (`showMcpServers={false}`). |
+| `connections` | MCP server management (both scopes, admin-gated org writes) plus A2A remote agents this app can call. |
+| `jobs` | Recurring jobs (personal + org) and automations (personal) with pause/resume/delete (see `recurring-jobs` skill). |
+| `access` | Copyable MCP URL and A2A agent-card URL, per-client connect steps (Claude, ChatGPT, Cursor, Claude Code, Codex, Other) from `packages/core/src/shared/mcp-connect-content.ts` (shared with the `/mcp/connect` route — edit the shared module, never fork copy), static-token fallback link. Grants/scopes/revocation UI is future work. |
+
+## Mounting In A Template
+
+1. Add an `/agent` route following the template's settings-route pattern
+   (`app/routes/agent.tsx` or `_app.agent.tsx`), mounting `AgentTabsPage`.
+   CSR is fine; keep the app shell in `root.tsx` so navigation does not
+   remount it (`client-side-routing` skill).
+2. Add an "Agent" item to primary navigation and the command palette,
+   mirroring the Settings entries. Link-first (`native-navigation` skill).
+3. Pass `agentPageHref="/agent"` to `AgentSidebar` so the sidebar workspace
+   and settings modes link out to the full page.
+4. Hash deep-links work out of the box: `/agent#context`, `/agent#files`,
+   `/agent#connections`, `/agent#jobs`, `/agent#access`.
+5. App-specific additions go in `extraTabs` (same `SettingsTabItem` shape as
+   the settings page); hide built-ins only with `hiddenTabs` when a template
+   genuinely lacks the underlying capability.
+
+## Scope
+
+The page-level Personal/Organization toggle passes `scope` (and
+`canManageOrg`) to every tab via `AgentPageTabProps`. Hide nothing silently:
+if a capability is personal-only today (e.g. automations), the org view says
+so honestly instead of faking an org variant.

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

@@ -20,15 +20,40 @@ counts, then lets the user or agent pin, evict, or restore individual segments.
 | Action | When to use |
 | --- | --- |
 | `context-manifest-get` | Read the current manifest for a thread. Returns token totals, segment status, source, and whether changes are enforceable. |
+| `context-preview-get` | Compose the would-be system context for the current user/org/app without a live thread. Returns labeled system sections with provenance, governance tier, token counts, and bounded previews. Backs the Agent page Context tab. |
 | `context-pin` | Preserve a segment across future compaction/model calls. Use for task specs, acceptance criteria, user constraints, and other durable context. |
 | `context-evict` | Exclude a stale or irrelevant segment from future model calls. Eviction is reversible and never deletes chat history. |
 | `context-restore` | Undo a pin, evict, or summarize directive for a segment. |
 | `context-report` | External hosts can report their visible context inventory. These manifests are advisory unless Agent-Native owns the emitted content. |
 
+## System Sections
+
+Manifests now cover the system-prompt half of context, not just conversation
+segments. Each system section carries a `provenance` label (framework-core,
+actions-prompt, template, enterprise-workspace-core, sql-workspace,
+legacy-app-default, organization, personal, memory, db-schema, tools,
+model-overlay, runtime-context) and a `governance` tier:
+
+- `required` — framework/enterprise policy; can never be altered by the user.
+- `inherited` — template/org/workspace instructions; managed elsewhere,
+  visible here.
+- `user` — personal instructions and memory; editable through Files.
+
+System sections are display-only provenance: they cannot be pinned, evicted,
+or summarized. The persisted manifest stores source refs, scope, content
+hashes, token counts, and bounded previews (~200 chars) — never raw prompt
+bodies; full content stays behind the resource/access model. The in-chat
+X-Ray panel groups these under "System", and the Agent page Context tab
+renders the full breakdown (via `context-preview-get`) with a
+system-vs-conversation split meter. Manifests are the latest snapshot per
+thread; there is no per-iteration history.
+
 ## Rules
 
 - Never evict or summarize protected segments. The manifest marks active-turn
   user/tool/thinking context as `protected`.
+- System sections are never evictable; required/inherited tiers are locked by
+  design — do not present controls that imply otherwise.
 - Prefer pinning the user's task, requirements, and decisions before evicting
   large stale tool results.
 - Eviction excludes content from future model calls; it does not delete the

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

@@ -28,6 +28,13 @@ For a deliberately isolated app, add that app directly at
 `https://<app>.agent-native.com/mcp` or
 `https://<your-host>/mcp`.
 
+In-app, the Agent page's **Access** tab (`/agent#access`, see the
+`agent-page` skill) is the discoverable home for all of this: it shows the
+app's copyable MCP URL and A2A agent-card URL, per-client setup steps
+(Claude, ChatGPT, Cursor, Claude Code, Codex, Other), and links to the full
+`/mcp/connect` page including the static-token fallback. Point users there
+instead of dictating URLs in chat.
+
 OAuth-capable hosts should use the standard remote MCP OAuth flow. Claude
 connectors and Claude Code `/mcp` authentication discover the protected
 resource, open the Agent-Native authorization page, and store their own tokens.

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

@@ -29,6 +29,15 @@ Recurring jobs are scheduled tasks the agent executes automatically on a cron sc
 | `manage-jobs` | `list`     | List all jobs and their status                             |
 | `manage-jobs` | `update`   | Update schedule, instructions, or toggle enabled           |
 
+## UI Surface
+
+Users can see and manage jobs without the agent on the Agent page's Jobs tab
+(`/agent#jobs`, `AgentJobsTab` in `packages/core/src/client/agent-page/`):
+recurring jobs (personal and organization scope) with pause/resume/delete and
+run status, plus automations (personal-only today). Backed by the scoped
+list/manage actions in `packages/core/src/jobs/actions/` — direct users there
+instead of describing job files when they just want to view or toggle jobs.
+
 ## Key Files
 
 | File                                  | Purpose                                                  |

package/corpus/core/src/triggers/actions/list-automations.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { describeCron, isValidCron, nextOccurrence } from "../../jobs/cron.js";
+import { resourceGetByPath, resourceList } from "../../resources/store.js";
+import { parseTriggerFrontmatter } from "../dispatcher.js";
+
+const scopeSchema = z.enum(["personal", "organization"]);
+
+function hasTriggerFrontmatter(content: string): boolean {
+  const header = content.match(/^---\n([\s\S]*?)\n---/m)?.[1] ?? "";
+  return /^triggerType\s*:/m.test(header);
+}
+
+function nextRun(
+  meta: ReturnType<typeof parseTriggerFrontmatter>["meta"],
+): string | null {
+  if (!meta.enabled) return null;
+  if (meta.nextRun) return meta.nextRun;
+  if (
+    meta.triggerType === "schedule" &&
+    meta.schedule &&
+    isValidCron(meta.schedule)
+  ) {
+    return nextOccurrence(meta.schedule).toISOString();
+  }
+  return null;
+}
+
+export interface AutomationActionItem {
+  id: string;
+  name: string;
+  path: string;
+  scope: "personal" | "organization";
+  triggerType: "event" | "schedule";
+  event: string | null;
+  schedule: string | null;
+  scheduleDescription: string | null;
+  condition: string | null;
+  body: string;
+  enabled: boolean;
+  lastRun: string | null;
+  lastStatus: string | null;
+  lastError: string | null;
+  nextRun: string | null;
+  createdBy: string | null;
+  canUpdate: boolean;
+}
+
+export default defineAction({
+  description:
+    "List event-triggered and schedule-triggered automations in the selected scope. Automations are currently personal-only.",
+  agentTool: false,
+  schema: z.object({
+    scope: scopeSchema.default("personal"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async ({ scope }, ctx): Promise<AutomationActionItem[]> => {
+    const userEmail = ctx?.userEmail;
+    if (!userEmail) throw new Error("Not authenticated.");
+    if (scope === "organization") return [];
+
+    const owner = userEmail;
+    const resources = await resourceList(owner, "jobs/");
+    const automations: AutomationActionItem[] = [];
+
+    for (const resource of resources) {
+      if (!resource.path.endsWith(".md") || resource.path.endsWith(".keep")) {
+        continue;
+      }
+      const full = await resourceGetByPath(owner, resource.path);
+      if (!full || !hasTriggerFrontmatter(full.content)) continue;
+      const { meta, body } = parseTriggerFrontmatter(full.content);
+      automations.push({
+        id: full.id,
+        name: resource.path.replace(/^jobs\//, "").replace(/\.md$/, ""),
+        path: resource.path,
+        scope,
+        triggerType: meta.triggerType,
+        event: meta.event ?? null,
+        schedule: meta.schedule || null,
+        scheduleDescription: meta.schedule ? describeCron(meta.schedule) : null,
+        condition: meta.condition ?? null,
+        body,
+        enabled: meta.enabled,
+        lastRun: meta.lastRun ?? null,
+        lastStatus: meta.lastStatus ?? null,
+        lastError: meta.lastError ?? null,
+        nextRun: nextRun(meta),
+        createdBy: meta.createdBy ?? null,
+        canUpdate: true,
+      });
+    }
+
+    return automations;
+  },
+});

package/corpus/core/src/triggers/actions/manage-automation.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { isValidCron, nextOccurrence } from "../../jobs/cron.js";
+import {
+  resourceDelete,
+  resourceGetByPath,
+  resourcePut,
+} from "../../resources/store.js";
+import {
+  buildTriggerContent,
+  parseTriggerFrontmatter,
+  refreshEventSubscriptions,
+} from "../dispatcher.js";
+
+export default defineAction({
+  description:
+    "Enable, disable, or delete a personal automation from the Agent Jobs page.",
+  agentTool: false,
+  schema: z.object({
+    operation: z.enum(["update", "delete"]),
+    name: z.string().min(1),
+    scope: z.enum(["personal", "organization"]).default("personal"),
+    enabled: z.boolean().optional(),
+  }),
+  run: async ({ operation, name, scope, enabled }, ctx) => {
+    const userEmail = ctx?.userEmail;
+    if (!userEmail) throw new Error("Not authenticated.");
+    if (scope === "organization") {
+      throw Object.assign(new Error("Automations are personal today."), {
+        statusCode: 400,
+      });
+    }
+
+    const path = `jobs/${name}.md`;
+    const resource = await resourceGetByPath(userEmail, path);
+    if (!resource) {
+      throw Object.assign(new Error(`Automation "${name}" not found.`), {
+        statusCode: 404,
+      });
+    }
+    const { meta, body } = parseTriggerFrontmatter(resource.content);
+    const header = resource.content.match(/^---\n([\s\S]*?)\n---/m)?.[1] ?? "";
+    if (!/^triggerType\s*:/m.test(header)) {
+      throw Object.assign(new Error(`Automation "${name}" not found.`), {
+        statusCode: 404,
+      });
+    }
+
+    if (operation === "delete") {
+      await resourceDelete(resource.id);
+      await refreshEventSubscriptions();
+      return { deleted: true, name };
+    }
+    if (enabled === undefined) {
+      throw Object.assign(new Error("enabled is required for update."), {
+        statusCode: 400,
+      });
+    }
+
+    meta.enabled = enabled;
+    if (
+      enabled &&
+      meta.triggerType === "schedule" &&
+      meta.schedule &&
+      isValidCron(meta.schedule)
+    ) {
+      meta.nextRun = nextOccurrence(meta.schedule).toISOString();
+    }
+    await resourcePut(
+      resource.owner,
+      resource.path,
+      buildTriggerContent(meta, body),
+    );
+    await refreshEventSubscriptions();
+    return { name, enabled: meta.enabled, nextRun: meta.nextRun ?? null };
+  },
+});

package/corpus/templates/analytics/actions/data-source-status.ts

@@ -23,6 +23,16 @@ import { resolveAnalyticsProviderCredential } from "../server/lib/provider-crede
 
 const APP_ID = "analytics";
 
+const BUILT_IN_FIRST_PARTY_PROVIDER = {
+  provider: "first-party",
+  label: "First-party Analytics",
+  configured: true,
+  configuredKeys: [],
+  missingRequiredKeys: [],
+  optionalKeys: [],
+  queryAction: "query-agent-native-analytics",
+} as const;
+
 function summarizeWorkspaceConnections(
   providerId: string,
   connections: SerializedWorkspaceConnection[],
@@ -58,7 +68,7 @@ async function listWorkspaceConnectionsForStatus(): Promise<{
 
 export default defineAction({
   description:
-    "List which analytics data-source credentials and granted workspace connections are configured without revealing secret values. The `key` arg accepts exact credential names like JIRA_API_TOKEN and provider aliases like jira, pylon, bigquery, github, hubspot, gong, or slack.",
+    "List which analytics data sources are available without revealing secret values. This always includes the built-in first-party Analytics event store, which is queried with `query-agent-native-analytics`; it also reports configured credentials and granted workspace connections. The `key` arg accepts exact credential names like JIRA_API_TOKEN and provider aliases like jira, pylon, bigquery, github, hubspot, gong, or slack.",
   schema: z.object({
     key: z
       .string()
@@ -190,19 +200,27 @@ export default defineAction({
           workspaceConnection,
         };
       });
-    const configuredDataSources = providers
-      .filter((provider) => provider.configured)
-      .map((provider) => ({
-        provider: provider.provider,
-        label: provider.label,
-        via:
-          provider.configuredKeys.length > 0 &&
-          provider.workspaceConnection.grantState === "connected"
-            ? "credentials-and-workspace"
-            : provider.workspaceConnection.grantState === "connected"
-              ? "workspace"
-              : "credentials",
-      }));
+    const configuredDataSources = [
+      {
+        provider: BUILT_IN_FIRST_PARTY_PROVIDER.provider,
+        label: BUILT_IN_FIRST_PARTY_PROVIDER.label,
+        via: "built-in",
+        queryAction: BUILT_IN_FIRST_PARTY_PROVIDER.queryAction,
+      },
+      ...providers
+        .filter((provider) => provider.configured)
+        .map((provider) => ({
+          provider: provider.provider,
+          label: provider.label,
+          via:
+            provider.configuredKeys.length > 0 &&
+            provider.workspaceConnection.grantState === "connected"
+              ? "credentials-and-workspace"
+              : provider.workspaceConnection.grantState === "connected"
+                ? "workspace"
+                : "credentials",
+        })),
+    ];
     return {
       // Keep a compact, explicit summary first so models do not infer source
       // availability from the much larger per-credential list below.
@@ -210,7 +228,7 @@ export default defineAction({
       configuredDataSourceCount: configuredDataSources.length,
       configuredDataSources,
       credentials: results,
-      providers,
+      providers: [BUILT_IN_FIRST_PARTY_PROVIDER, ...providers],
       total: results.length,
       workspaceConnections: {
         appId: APP_ID,

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, 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.",
+    "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, 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()