@agent-native/core 0.5.0-dev.b51eaae → 0.7.1

package/docs/content/integrations.md

@@ -0,0 +1,198 @@
+---
+title: "Integrations"
+description: "Connect your agent to Slack, Telegram, WhatsApp, and other messaging platforms."
+---
+
+# Integrations
+
+Connect your agent to messaging platforms so you can chat with it from Slack, Telegram, WhatsApp, and more. Same agent, same tools, same thread history.
+
+## Overview {#overview}
+
+Messaging integrations let users talk to their agent from the platforms they already use. Instead of opening the web UI, you send a message in Slack or Telegram and the agent responds right there. It has access to the same actions, the same database, and the same conversation history as the web chat.
+
+Each integration works through webhooks. The messaging platform sends incoming messages to your app, the agent processes them, and the response is posted back. No polling, no long-lived connections — just standard HTTP webhooks.
+
+## How it works {#how-it-works}
+
+The flow for every platform follows the same pattern:
+
+1. A user sends a message on the external platform (Slack, Telegram, etc.)
+2. The platform delivers the message to your app via a webhook at `/_agent-native/integrations/<platform>/webhook`
+3. The integrations plugin validates the request, extracts the message text and thread context, and maps it to an internal conversation thread
+4. The agent processes the message in the background using the same pipeline as the web chat — same system prompt, same actions, same tools
+5. The response is posted back to the external platform in the same thread
+
+`User (Slack/Telegram/WhatsApp)` → `Webhook` → `Agent Processing` → `Response posted back`
+
+## Setup {#setup}
+
+The integrations plugin auto-mounts when no custom version exists in your template. To customize it, create a plugin file:
+
+```ts
+// server/plugins/integrations.ts
+import { createIntegrationsPlugin } from "@agent-native/core/server";
+import { scriptRegistry } from "../../agent.config";
+
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+});
+```
+
+The plugin registers webhook routes for each enabled platform under `/_agent-native/integrations/`. Which platforms are active depends on which environment variables are configured.
+
+## Slack {#slack}
+
+### 1. Create a Slack app
+
+Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app. Under **OAuth & Permissions**, add the following bot token scopes:
+
+- `chat:write` — send messages
+- `app_mentions:read` — receive @-mentions (optional)
+
+### 2. Enable Event Subscriptions
+
+Under **Event Subscriptions**, set the Request URL to:
+
+```text
+https://your-app.example.com/_agent-native/integrations/slack/webhook
+```
+
+Subscribe to the `message.im` bot event (and optionally `app_mention` for channel mentions).
+
+### 3. Set environment variables
+
+```
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_SIGNING_SECRET=your-signing-secret
+```
+
+The bot token is found under **OAuth & Permissions** after installing the app to your workspace. The signing secret is under **Basic Information**.
+
+## Telegram {#telegram}
+
+### 1. Create a bot
+
+Message [@BotFather](https://t.me/BotFather) on Telegram and use the `/newbot` command. You will receive a bot token.
+
+### 2. Set environment variables
+
+```
+TELEGRAM_BOT_TOKEN=your-bot-token
+```
+
+### 3. Register the webhook
+
+After deploying your app, call the setup endpoint to register the webhook with Telegram:
+
+```text
+// The integrations plugin exposes a setup endpoint
+POST /_agent-native/integrations/telegram/setup
+
+// This calls Telegram's setWebhook API pointing to:
+// https://your-app.example.com/_agent-native/integrations/telegram/webhook
+```
+
+You can also register the webhook manually using the Telegram Bot API if you prefer.
+
+## WhatsApp {#whatsapp}
+
+### 1. Set up the WhatsApp Cloud API
+
+Go to the [Meta Developer Portal](https://developers.facebook.com/), create an app, and enable the WhatsApp product. Configure a phone number for your business.
+
+### 2. Set environment variables
+
+```
+WHATSAPP_ACCESS_TOKEN=your-access-token
+WHATSAPP_VERIFY_TOKEN=your-verify-token
+WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
+```
+
+The verify token is a string you choose — Meta uses it during webhook verification. The access token and phone number ID come from the Meta Developer Portal.
+
+### 3. Configure the webhook
+
+In the Meta Developer Portal, set the webhook URL to:
+
+```text
+https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
+```
+
+Subscribe to the `messages` webhook field.
+
+## Configuration {#configuration}
+
+Integrations can be managed from the settings UI in the sidebar. Each platform shows its connection status and webhook URL. You can enable/disable individual integrations without removing environment variables.
+
+The webhook URLs follow a consistent pattern:
+
+```text
+/_agent-native/integrations/<platform>/webhook
+
+# Examples:
+/_agent-native/integrations/slack/webhook
+/_agent-native/integrations/telegram/webhook
+/_agent-native/integrations/whatsapp/webhook
+```
+
+## Thread continuity {#thread-continuity}
+
+Conversations from external platforms are mapped to internal threads. Each Slack DM, Telegram chat, or WhatsApp conversation becomes a persistent thread in the agent-native database. This means:
+
+- The agent retains context across messages in the same external conversation
+- External conversations appear in the web UI alongside web-originated threads, tagged with their source platform
+- You can continue a conversation that started in Slack from the web UI, or vice versa
+
+## Custom adapters {#custom-adapters}
+
+To add support for a new messaging platform, implement the `PlatformAdapter` interface:
+
+```ts
+import type { PlatformAdapter } from "@agent-native/core/server";
+
+const myAdapter: PlatformAdapter = {
+  platform: "discord",
+
+  // Verify the incoming webhook request is authentic
+  verifyRequest(request: Request): Promise<boolean> {
+    // Validate signature headers
+  },
+
+  // Extract the message text and thread context from the webhook payload
+  parseMessage(body: unknown): Promise<{
+    text: string;
+    threadId: string;
+    senderId: string;
+    metadata?: Record<string, unknown>;
+  }> {
+    // Parse platform-specific payload
+  },
+
+  // Send the agent's response back to the platform
+  sendResponse(threadId: string, text: string): Promise<void> {
+    // Call the platform's API to post the message
+  },
+};
+```
+
+Register your adapter in the integrations plugin config:
+
+```ts
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  adapters: [myAdapter],
+});
+```
+
+## Security {#security}
+
+Every incoming webhook is verified before processing:
+
+- **Slack** — HMAC-SHA256 signature verification using `SLACK_SIGNING_SECRET`. The `X-Slack-Signature` header is checked against the request body.
+- **Telegram** — requests are validated by checking the secret token set during webhook registration via the Telegram Bot API.
+- **WhatsApp** — Meta's webhook verification challenge (using `WHATSAPP_VERIFY_TOKEN`) and payload signature validation.
+
+All platform credentials (tokens, secrets) are stored as environment variables and never persisted in the database or source code. Use the settings UI or your deployment platform's env var management to configure them.

package/docs/content/key-concepts.md

@@ -0,0 +1,246 @@
+---
+title: "Key Concepts"
+description: "How agent-native apps work: the four-area checklist, SQL database, agent chat bridge, polling sync, actions, context awareness, and portability."
+---
+
+# Key Concepts
+
+How agent-native apps work under the hood — the principles, the architecture, and why they're built this way.
+
+## Why agent-native {#why-agent-native}
+
+Teams today have four options for AI-powered work, and none of them are ideal:
+
+1. **Chat apps** (Claude Projects, ChatGPT) — accessible but not built for structured workflows. No persistent UI, no dashboards, no team collaboration.
+2. **Raw agent interfaces** (Claude Code, Cursor) — powerful but inaccessible to non-devs. No guardrails, no onboarding, no structured UI.
+3. **Custom AI apps** — limited. The AI can't see what you see, can't react to what you click, and can't update the app itself. No conversation history, no rollback, no skills.
+4. **Existing SaaS** (Amplitude, HubSpot, Google Slides) — bolting AI onto architectures that weren't designed for it. You can feel the seams.
+
+Agent-native apps solve this by making the agent and the UI equal citizens of the same system. Think of it as Claude Code, but with buttons and visual interfaces. The agent can do anything the UI can do (via natural language), and the UI can trigger anything the agent can do (via buttons).
+
+See [What Is Agent-Native?](/docs/what-is-agent-native) for the full vision and philosophy.
+
+## The architecture {#the-architecture}
+
+Every agent-native app is three things working together:
+
+> **Agent** — Autonomous AI that reads data, writes data, runs actions, and modifies code. Customizable with skills and instructions.
+>
+> **Application** — Full React UI with dashboards, flows, and visualizations. Guided experiences your team can use.
+>
+> **Computer** — Database, browser, code execution. Agents work directly with SQL and tools — no MCPs needed.
+
+Every app includes an embedded agent panel with chat and optional CLI terminal. Locally, you run `pnpm dev` and the agent is right there. In the cloud, Builder.io provides a managed frame with collaboration, visual editing, and managed infrastructure for teams.
+
+Six rules govern the architecture:
+
+1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM
+2. **All AI goes through the agent** — no inline LLM calls
+3. **Actions for agent operations** — complex work runs as actions
+4. **Polling keeps the UI in sync** — database changes sync via lightweight polling
+5. **The agent can modify code** — the app evolves as you use it
+6. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
+
+## The four-area checklist {#four-area-checklist}
+
+Every new feature must update all four areas. Skipping any one breaks the agent-native contract.
+
+| Area             | Description                                                    |
+| ---------------- | -------------------------------------------------------------- |
+| **1. UI**        | Page, component, or dialog the user interacts with             |
+| **2. Action**    | Agent-callable action in actions/ for the same operation       |
+| **3. Skills**    | Update AGENTS.md and/or create a skill documenting the pattern |
+| **4. App-State** | Navigation state, view-screen data, and navigate commands      |
+
+A feature with only UI is invisible to the agent. A feature with only actions is invisible to the user. A feature without app-state means the agent is blind to what the user is doing.
+
+## Data in SQL {#data-in-sql}
+
+All application state lives in a SQL database via Drizzle ORM. The framework supports multiple databases — SQLite, Postgres (Neon, Supabase), Turso, Cloudflare D1. Users configure `DATABASE_URL` to choose their database.
+
+Core SQL stores are auto-created and available in every template:
+
+- `application_state` — ephemeral UI state (navigation, drafts, selections)
+- `settings` — persistent key-value config
+- `oauth_tokens` — OAuth credentials
+- `sessions` — auth sessions
+
+```bash
+// Drizzle schema for domain data
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+export const forms = sqliteTable("forms", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  schema: text("schema").notNull(), // JSON
+  ownerEmail: text("owner_email"),
+  createdAt: integer("created_at").notNull(),
+});
+
+// Core actions for quick database access
+pnpm action db-schema           # show all tables
+pnpm action db-query --sql "SELECT * FROM forms"
+pnpm action db-exec --sql "INSERT INTO forms ..."
+# Surgical find/replace on a large text column — sends a diff, not the whole value
+pnpm action db-patch --table documents --column content \
+  --where "id='doc-1'" --find "old heading" --replace "new heading"
+```
+
+## Agent chat bridge {#agent-chat-bridge}
+
+The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work — with full conversation history, skills, instructions, and the ability to iterate.
+
+```ts
+// In a React component — delegate AI work to the agent
+import { sendToAgentChat } from "@agent-native/core";
+
+sendToAgentChat({
+  message: "Generate a chart showing signups by source",
+  context: "Dashboard ID: main, date range: last 30 days",
+  submit: true,
+});
+```
+
+Why not call an LLM inline?
+
+- **AI is non-deterministic.** You need conversation flow to give feedback and iterate — not one-shot buttons.
+- **Context matters.** The agent has your full codebase, instructions, skills, and history. An inline call has none of that.
+- **The agent can do more.** It can run actions, browse the web, modify code, and chain multiple steps together.
+- **Headless execution.** Because everything goes through the agent, any app can be driven entirely from Slack, Telegram, or another agent via [A2A](/docs/a2a-protocol).
+
+## Actions system {#actions-system}
+
+When the agent needs to do something complex — call an API, process data, query the database — it runs an action. Actions are TypeScript files in `actions/` that export a default async function:
+
+```ts
+// actions/fetch-data.ts
+import { parseArgs } from "@agent-native/core";
+
+export default async function fetchData(args: string[]) {
+  const { source } = parseArgs(args);
+  const res = await fetch(`https://api.example.com/${source}`);
+  const data = await res.json();
+  console.log(JSON.stringify(data, null, 2));
+}
+```
+
+```bash
+# Agent runs actions via CLI
+pnpm action fetch-data --source=signups
+```
+
+This means anything the UI can do, the agent can do — and vice versa. The UI calls `POST /api/fetch-data`, the agent calls `pnpm action fetch-data`. Same logic, same results, different entry points.
+
+## Polling sync {#polling-sync}
+
+Database changes are synced to the UI via lightweight polling. When the agent writes to the database (application state, settings, or domain data), a version counter increments. The client `useDbSync()` hook (formerly `useFileWatcher`) polls `/_agent-native/poll` every 2 seconds and invalidates React Query caches when changes are detected.
+
+```ts
+// Client: invalidate caches on database changes
+import { useDbSync } from "@agent-native/core";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings", "forms"],
+});
+```
+
+The flow is:
+
+1. Agent runs an action that writes to the database
+2. Version counter increments
+3. `useDbSync` detects the new version on next poll
+4. React Query caches are invalidated
+5. Components re-fetch and render the new data
+
+This works in all deployment environments — including serverless and edge — because it uses the database, not in-memory state or file system watchers.
+
+## Frames {#frames}
+
+Agent-native apps include an embedded agent panel that provides the AI agent alongside the app UI. This is what makes the architecture work: the agent needs a computer (database, browser, code execution), and the app needs the agent for AI work.
+
+> **Embedded Agent Panel** — Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally. Free and open source.
+>
+> **Cloud** — Deploy to any cloud with real-time collaboration, visual editing, roles and permissions. Best for teams.
+
+## Context awareness {#context-awareness}
+
+The agent always knows what the user is looking at. The UI writes a `navigation` key to application-state on every route change. The agent reads it via the `view-screen` action before acting.
+
+See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
+
+## APIs & CLIs, not MCPs {#apis-and-clis}
+
+Agent-native apps can work with MCP servers, but the architecture leans heavily on something more standard: **regular APIs and CLIs accessed through code execution**. Agents are great at writing code that calls `fetch()` or runs a CLI command — no special protocol needed.
+
+- **No wrapper layer.** Call APIs directly with `fetch()` or use official SDKs.
+- **Any CLI works.** `ffmpeg`, `gh`, `aws`, `gcloud` — if it runs in a terminal, the agent can use it.
+- **Code is the protocol.** TypeScript actions are more expressive than any tool schema.
+- **MCP is additive.** Use MCP servers alongside actions if you want, but they're not required.
+
+## Agent modifies code {#agent-modifies-code}
+
+This is a feature, not a bug. The agent can safely edit the app's source code: components, routes, styles, actions.
+
+There's no shared codebase to break. You own the app, and the agent evolves it for you over time:
+
+1. Fork a template (e.g. the analytics template)
+2. Customize it by asking the agent
+3. "Add a new chart type for cohort analysis" — the agent builds it
+4. "Connect to our Stripe account" — the agent writes the integration
+5. Your app keeps improving without manual development
+
+## Database agnostic {#database-agnostic}
+
+The framework supports every Drizzle-supported database. Never write SQL that only works on one dialect.
+
+- **SQLite** — local dev fallback when `DATABASE_URL` is unset
+- **Neon Postgres** — common in both dev and production
+- **Turso** (libSQL) — edge-friendly SQLite-compatible
+- **Supabase Postgres**
+- **Cloudflare D1**
+- **Plain Postgres**
+
+Use the framework helpers for dialect-agnostic SQL:
+
+```ts
+import { getDbExec, isPostgres, intType } from "@agent-native/core/db/client";
+
+// getDbExec() auto-converts ? params to $1 for Postgres
+const client = getDbExec();
+await client.execute({
+  sql: "SELECT * FROM forms WHERE owner_email = ?",
+  args: [email],
+});
+
+// Branch when syntax differs
+const upsert = isPostgres()
+  ? "INSERT INTO settings (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = $2"
+  : "INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)";
+```
+
+## Hosting agnostic {#hosting-agnostic}
+
+The server runs on Nitro, which compiles to any deployment target:
+
+- Node.js — local dev, traditional servers
+- Cloudflare Workers/Pages
+- Netlify Functions/Edge
+- Vercel Serverless/Edge
+- Deno Deploy
+- AWS Lambda
+- Bun
+
+Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins. These don't exist in Workers/edge environments. Actions in `actions/` run in Node.js and can use Node APIs freely.
+
+Never assume a persistent server process. Serverless and edge environments are stateless — no in-memory caches, no long-lived connections. Use the SQL database for all state.
+
+## Deep dives {#deep-dives}
+
+For detailed guidance on specific patterns:
+
+- [What Is Agent-Native?](/docs/what-is-agent-native) — the vision and philosophy
+- [Context Awareness](/docs/context-awareness) — navigation state, view-screen, navigate commands
+- [Skills Guide](/docs/skills-guide) — framework skills, domain skills, creating custom skills
+- [A2A Protocol](/docs/a2a-protocol) — agent-to-agent communication
+- [Enterprise Workspace](/docs/enterprise-workspace) — host many apps in one monorepo with shared auth, skills, components, and credentials

package/docs/content/mcp-clients.md

@@ -0,0 +1,110 @@
+---
+title: "MCP Clients"
+description: "Connect your agent-native app to local MCP servers (claude-in-chrome, filesystem, playwright, etc) so the agent gains their tools."
+---
+
+# MCP Clients
+
+Agent-native apps can also act as MCP **clients** — connecting to locally installed MCP servers and exposing their tools to the agent chat. This is the symmetric counterpart to the [MCP Protocol](./mcp-protocol.md) (which makes your app an MCP server).
+
+With one config file, every agent-native app in your workspace gains access to tools provided by MCP servers on your machine: `claude-in-chrome` for browser automation, `@modelcontextprotocol/server-filesystem` for reading files, `@modelcontextprotocol/server-playwright` for browser testing, and anything else that speaks MCP.
+
+## Adding a local MCP server {#adding-a-server}
+
+Create `mcp.config.json` at your workspace root (or at an individual app root — workspace root wins when both exist):
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-playwright"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+On next app start you'll see:
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+The tools are registered in the agent's tool registry with the prefix `mcp__<server-id>__<tool-name>` so they can't collide with your template's actions.
+
+## Config precedence {#precedence}
+
+MCP configuration is resolved in this order, first match wins:
+
+1. **Workspace root `mcp.config.json`** — detected via `agent-native.workspaceCore` in `package.json`. Shared across every app in the workspace.
+2. **App-root `mcp.config.json`** — per-app override if you don't want an MCP server available in every app.
+3. **`MCP_SERVERS` env var** — JSON string with the same shape, for CI/production where a file doesn't make sense.
+
+## Production deploys: `MCP_SERVERS` {#mcp-servers-env}
+
+For production deploys set the full config shape (or the inner server map) as an environment variable:
+
+```bash
+MCP_SERVERS='{"servers":{"playwright":{"command":"npx","args":["-y","@modelcontextprotocol/server-playwright"]}}}'
+```
+
+MCP tools only activate in Node runtimes — Cloudflare Workers and other edge targets silently skip MCP and continue with the rest of the app working normally.
+
+## Auto-detect: `claude-in-chrome` {#autodetect}
+
+If you have **no** `mcp.config.json` and the `claude-in-chrome-mcp` binary is on `PATH` (or in the well-known install location `~/.claude-in-chrome/bin/claude-in-chrome-mcp`), agent-native auto-registers it as a default MCP server. Set `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` to opt out.
+
+This means users who've installed the claude-in-chrome extension get browser control across every agent-native app they open with no config changes.
+
+## Status route {#status-route}
+
+Every app exposes `GET /_agent-native/mcp/status` for tooling and onboarding:
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+Use this to build "claude-in-chrome detected — your agent can now drive Chrome" onboarding hints, or debug MCP connection problems.
+
+## Failure modes {#failures}
+
+Individual MCP server failures never take down the agent:
+
+- A misconfigured `command` → the server is skipped, its error appears in `/mcp/status` under `errors.<server-id>`, and every other server continues to work.
+- The MCP SDK is missing from `node_modules` → all MCP functionality is skipped with a warning; agent chat keeps working with zero MCP tools.
+- Running in an edge runtime → MCP client is a no-op.
+
+Agent-native will always boot; broken MCP configuration just means fewer tools.
+
+## Security {#security}
+
+MCP tools run on your machine with whatever permissions the spawned process has. Treat `mcp.config.json` like any other list of executables you're willing to let the agent drive. Tools from MCP servers appear in the agent's tool-use loop just like your template's own actions, so make sure you trust every server you configure.