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

package/docs/content/mcp-protocol.md

@@ -0,0 +1,168 @@
+---
+title: "MCP Protocol"
+description: "Expose your agent-native app as a remote MCP server so Claude Code, Cursor, and other AI tools can call your app's actions directly."
+---
+
+# MCP Protocol
+
+Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server. This lets external AI tools like Claude Code, Cursor, and Windsurf discover and call your app's actions directly — no extra code needed.
+
+## Overview {#overview}
+
+MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible client can connect and use your app's tools.
+
+Key concepts:
+
+- **Auto-mounted** — every app gets `/_agent-native/mcp` for free, no setup required
+- **Streamable HTTP** — uses the modern MCP transport over standard HTTP (POST + SSE)
+- **Same actions** — the exact same action registry that powers agent chat and A2A
+- **`ask-agent` tool** — a meta-tool that delegates to the full agent loop for complex tasks
+- **Bearer auth** — uses `ACCESS_TOKEN` or `A2A_SECRET` for authentication
+
+## MCP vs A2A {#mcp-vs-a2a}
+
+Both protocols are auto-mounted. Use whichever fits your use case:
+
+|                    | MCP                                   | A2A                                          |
+| ------------------ | ------------------------------------- | -------------------------------------------- |
+| **Best for**       | External tools calling your app       | Agent-to-agent communication                 |
+| **Protocol**       | MCP Streamable HTTP                   | JSON-RPC 2.0                                 |
+| **Tool discovery** | `tools/list`                          | Agent card at `/.well-known/agent-card.json` |
+| **Endpoint**       | `/_agent-native/mcp`                  | `/_agent-native/a2a`                         |
+| **Supported by**   | Claude Code, Cursor, Windsurf, Cowork | Other agent-native apps                      |
+| **Execution**      | Direct tool calls (no extra LLM)      | Full agent loop (LLM reasoning)              |
+
+You can also use the `ask-agent` MCP tool to get the best of both worlds — call it from Claude Code and let your app's agent reason through complex tasks.
+
+## Connecting from Claude Code {#claude-code}
+
+Add your app as a remote MCP server in Claude Code's config:
+
+```jsonc
+// ~/.claude/mcp_servers.json
+{
+  "mail": {
+    "type": "url",
+    "url": "https://mail.example.com/_agent-native/mcp",
+    "headers": {
+      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
+    },
+  },
+}
+```
+
+Then in Claude Code, you can use your app's tools naturally:
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## Connecting from other MCP clients {#other-clients}
+
+Any MCP client that supports Streamable HTTP transport can connect. The endpoint is:
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+The server supports the standard MCP handshake: `initialize` → `initialized` → `tools/list` → `tools/call`.
+
+## Tools {#tools}
+
+All actions registered in your app are exposed as MCP tools. The mapping is direct:
+
+| Action property    | MCP tool property |
+| ------------------ | ----------------- |
+| `tool.description` | `description`     |
+| `tool.parameters`  | `inputSchema`     |
+| Action name        | Tool name         |
+
+### The `ask-agent` tool {#ask-agent}
+
+In addition to individual action tools, every MCP server includes an `ask-agent` meta-tool. This sends a natural-language message to the app's AI agent and returns the response.
+
+Use `ask-agent` for complex tasks that benefit from the agent's reasoning and context:
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+The agent runs the same loop as the interactive chat — it can call multiple tools, reason about context, and produce a thoughtful response.
+
+## Authentication {#authentication}
+
+The MCP endpoint uses the same auth as the rest of the app:
+
+| Env var         | How it works                                                |
+| --------------- | ----------------------------------------------------------- |
+| `ACCESS_TOKEN`  | Bearer token — client sends `Authorization: Bearer <token>` |
+| `ACCESS_TOKENS` | Comma-separated list of valid tokens                        |
+| `A2A_SECRET`    | JWT-based auth — tokens are verified cryptographically      |
+| _(none set)_    | No auth required (dev mode)                                 |
+
+In production, set `ACCESS_TOKEN` or `A2A_SECRET` to secure the endpoint. In development (no auth env vars configured), all requests are allowed.
+
+## Custom MCP setup {#custom-setup}
+
+The MCP server is auto-mounted by the agent-chat plugin. For most apps, no configuration is needed. If you need custom behavior, you can mount it manually in a server plugin:
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro.h3App, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+  });
+});
+```
+
+## Example: analytics from Claude Code {#example}
+
+You have a deployed analytics app at `analytics.example.com`. From Claude Code:
+
+```jsonc
+// ~/.claude/mcp_servers.json
+{
+  "analytics": {
+    "type": "url",
+    "url": "https://analytics.example.com/_agent-native/mcp",
+    "headers": { "Authorization": "Bearer sk-analytics-token" },
+  },
+}
+```
+
+Now in Claude Code:
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+For more complex analysis:
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```

package/docs/content/onboarding.md

@@ -0,0 +1,107 @@
+# Onboarding
+
+The framework-level onboarding system gives every template a shared setup
+experience in the agent chat sidebar. Users see a checklist of setup steps,
+each with one or more ways to complete it — paste an API key, connect
+Builder, or ask the agent to do it for them.
+
+The system is **auto-mounted**. Templates don't need to wire anything to get
+the three built-in steps (LLM, database, auth). To add app-specific steps
+(Gmail, Slack, Notion, etc.), call `registerOnboardingStep()` from a server
+plugin.
+
+## Auto-mounted routes
+
+All routes live under `/_agent-native/onboarding/`:
+
+| Route                                               | Purpose                           |
+| --------------------------------------------------- | --------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | List steps with completion status |
+| `POST /_agent-native/onboarding/steps/:id/complete` | Mark step complete (override)     |
+| `POST /_agent-native/onboarding/dismiss`            | Dismiss the onboarding banner     |
+| `POST /_agent-native/onboarding/reopen`             | Clear dismissal (re-show panel)   |
+| `GET /_agent-native/onboarding/dismissed`           | Read dismissal + allComplete flag |
+
+## Adding a step from a template
+
+```ts
+// server/plugins/my-onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "gmail",
+    order: 100,
+    title: "Connect Gmail",
+    description: "Grant read/send access so the agent can work with email.",
+    methods: [
+      {
+        id: "oauth",
+        kind: "link",
+        primary: true,
+        label: "Sign in with Google",
+        payload: {
+          url: "/_agent-native/google/auth-url?scope=mail",
+          external: false,
+        },
+      },
+      {
+        id: "delegate",
+        kind: "agent-task",
+        label: "Let the agent set it up",
+        badge: "beta",
+        payload: {
+          prompt: "Walk me through connecting Gmail. Set env vars as needed.",
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GMAIL_REFRESH_TOKEN,
+  });
+});
+```
+
+## Method kinds
+
+| Kind               | Payload                   | Use for                                   |
+| ------------------ | ------------------------- | ----------------------------------------- |
+| `link`             | `{ url, external? }`      | Send user to an OAuth flow or docs page   |
+| `form`             | `{ fields, writeScope? }` | Collect env vars (keys, secrets, URLs)    |
+| `builder-cli-auth` | `{ scope: "browser" }`    | Connect Builder (unlocks shared infra)    |
+| `agent-task`       | `{ prompt }`              | Send a prompt to the agent chat to handle |
+
+The `primary: true` flag marks a method as the big CTA for its step.
+
+## Built-in steps
+
+| ID         | Required | Description                                   |
+| ---------- | -------- | --------------------------------------------- |
+| `llm`      | yes      | ANTHROPIC_API_KEY or Builder connection       |
+| `database` | no       | SQLite default or a DATABASE_URL for Postgres |
+| `auth`     | no       | Local dev mode, Google OAuth, or access token |
+
+Any of these can be overridden by re-registering with the same `id` after the
+defaults load.
+
+## Client usage
+
+The panel is already inside `<AgentPanel>`. To build a custom layout:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```

package/docs/content/real-time-collaboration.md

@@ -0,0 +1,185 @@
+---
+title: "Real-Time Collaboration"
+description: "Multi-user collaborative editing with Yjs CRDT, live cursors, and AI agent real-time edits."
+---
+
+# Real-Time Collaboration
+
+Multi-user collaborative editing where the AI agent and human users are equal participants — like Google Docs, but with an AI collaborator.
+
+## Overview {#overview}
+
+The framework provides a Yjs-based collaborative editing system in `@agent-native/core/collab`. Multiple users can edit the same document simultaneously with live cursor positions, and the AI agent can make surgical edits that appear in real-time without disrupting the user's cursor, selection, or undo history.
+
+This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-free merging), **TipTap** (rich text editor), and **polling-based sync** (works in all deployment environments including serverless and edge).
+
+## How it works {#how-it-works}
+
+The collaboration system has three layers:
+
+- **Yjs Y.Doc** — stores the document as a `Y.XmlFragment` (ProseMirror node tree). This is the CRDT that enables conflict-free merging of concurrent edits.
+- **TipTap Collaboration extension** — binds the editor to the Y.XmlFragment via `ySyncPlugin`. Remote changes are applied as minimal ProseMirror transactions that preserve cursor position.
+- **Polling sync** — clients poll `/_agent-native/poll` every 2 seconds for Yjs updates. Awareness state (cursor positions, user info) is synced via a separate `/_agent-native/collab/:docId/awareness` endpoint.
+
+The Yjs state is persisted in a `_collab_docs` SQL table as base64-encoded binary, compatible with both SQLite and Postgres.
+
+## Agent + human collaboration {#agent-human-collab}
+
+The agent and human users are equal participants in collaborative editing. The key insight is that both produce Yjs operations that merge cleanly:
+
+- **Human edits** flow through TipTap → ySyncPlugin → Y.XmlFragment → server via HTTP
+- **Agent edits** flow through the `edit-document` action → server search-replace endpoint → Y.XmlFragment mutation → poll update → all clients
+
+The agent's `edit-document` action uses surgical search-and-replace on Y.XmlText nodes within the Y.XmlFragment tree. This produces the smallest possible Yjs update — only the changed text is modified, not the entire document. The result: the user sees the agent's change appear in their editor without losing their place.
+
+```bash
+# Agent makes a surgical edit — user sees it appear live
+pnpm action edit-document --id doc123 --find "Big Projects" --replace "Proyectos Grandes"
+
+# The action:
+# 1. Updates SQL content column (for search/API compat)
+# 2. Calls POST /_agent-native/collab/doc123/search-replace
+# 3. Server walks Y.XmlFragment, finds text, modifies Y.XmlText node
+# 4. Minimal Yjs update emitted via poll system
+# 5. Client receives update → ySyncPlugin applies targeted PM transaction
+# 6. User's cursor stays in place ✓
+```
+
+## Enabling collaboration {#enabling-collab}
+
+Templates opt into collaboration with five steps:
+
+### 1. Install dependencies
+
+```bash
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core
+```
+
+### 2. Add Vite optimizeDeps
+
+Prevents Vite from re-bundling TipTap in incompatible ways during dev:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [reactRouter()],
+  optimizeDeps: {
+    include: [
+      "yjs",
+      "y-protocols/awareness",
+      "@tiptap/core",
+      "@tiptap/extension-collaboration",
+      "@tiptap/extension-collaboration-caret",
+      "@tiptap/y-tiptap",
+    ],
+  },
+});
+```
+
+### 3. Add the collab server plugin
+
+```typescript
+// server/plugins/collab.ts
+import { createCollabPlugin } from "@agent-native/core/server";
+
+export default createCollabPlugin({
+  table: "documents",
+  contentColumn: "content",
+  idColumn: "id",
+  autoSeed: false, // Client-side seeding on first load
+});
+```
+
+### 4. Use the client hook
+
+```typescript
+import { useCollaborativeDoc, generateTabId } from "@agent-native/core/client";
+
+const TAB_ID = generateTabId();
+
+const { ydoc, awareness, isLoading, activeUsers } = useCollaborativeDoc({
+  docId: documentId,
+  requestSource: TAB_ID,
+  user: { name: "Steve", email: "steve@example.com", color: "#60a5fa" },
+});
+```
+
+### 5. Add TipTap extensions
+
+```typescript
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCaret from "@tiptap/extension-collaboration-caret";
+import { Awareness } from "y-protocols/awareness";
+
+// Create awareness for cursor sync
+const awareness = new Awareness(ydoc);
+awareness.setLocalStateField("user", { name, color });
+
+const editor = useEditor({
+  extensions: [
+    StarterKit.configure({ history: false }), // Yjs handles undo
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCaret.configure({
+      provider: { awareness },
+      user: { name, color },
+    }),
+  ],
+  content: initialContent,
+});
+```
+
+## Live cursors & presence {#live-cursors}
+
+The `CollaborationCaret` extension renders colored cursor lines with user name labels for each connected user. The `useCollaborativeDoc` hook provides an `activeUsers` array that can be used to render a presence bar with user avatars.
+
+User identity is derived from the session email. The framework provides `emailToColor()` and `emailToName()` helpers to generate consistent cursor colors and display names from email addresses.
+
+## Comments {#comments}
+
+Templates can add a comments system with threaded discussions on documents. The content template includes a full implementation with:
+
+- `document_comments` SQL table (threads, replies, resolved status)
+- CRUD API routes at `/api/comments`
+- Comments sidebar with threaded view and reply UI
+- Resolve/unresolve threads
+- **Send to AI** button — sends the comment thread context to the agent chat via `sendToAgentChat()`
+- Agent actions: `list-comments`, `add-comment`
+- Notion comment sync: `sync-notion-comments` action for bidirectional pull/push
+
+## Collab routes {#collab-routes}
+
+All collab routes are auto-mounted under `/_agent-native/collab/` by the collab plugin:
+
+| Route                         | Purpose                                  |
+| ----------------------------- | ---------------------------------------- |
+| `GET /:docId/state`           | Fetch full Y.Doc state (base64)          |
+| `POST /:docId/update`         | Apply client Yjs update                  |
+| `POST /:docId/text`           | Apply full text replacement (diff-based) |
+| `POST /:docId/search-replace` | Surgical find/replace in Y.XmlFragment   |
+| `POST /:docId/awareness`      | Sync cursor/presence state               |
+| `GET /:docId/users`           | List active users on a document          |
+
+## Agent edit action {#edit-document}
+
+The `edit-document` action is the primary way agents make changes to documents in collaborative mode:
+
+```bash
+# Single edit
+pnpm action edit-document --id doc123 --find "old text" --replace "new text"
+
+# Batch edits
+pnpm action edit-document --id doc123 --edits '[{"find":"old","replace":"new"}]'
+
+# Delete text
+pnpm action edit-document --id doc123 --find "delete me" --replace ""
+```
+
+When collab state exists for the document, the action calls the server's `search-replace` endpoint via HTTP (not the collab module directly, since actions run in a separate process). The server walks the Y.XmlFragment tree, finds the text in Y.XmlText nodes, and applies minimal delete/insert operations. The resulting Yjs update is broadcast to all connected clients via the poll system.
+
+## Common pitfalls {#pitfalls}
+
+- **TipTap version mismatch** — All `@tiptap/*` packages must be the same version. The Collaboration extension requires `editor.utils` which was added in v3.22.2. Add `@tiptap/core` as an explicit dependency.
+- **Empty editor on first load** — The Collaboration extension does NOT auto-seed from the `content` prop. Seed manually with `editor.commands.setContent()` when the Y.XmlFragment is empty.
+- **Data loss from empty saves** — Guard against saving empty content in the `onUpdate` handler when the editor is in collab mode but hasn't been seeded yet.
+- **Vite dep optimization** — Always add Yjs-related packages to `optimizeDeps.include` to prevent Vite from re-bundling TipTap in incompatible ways.
+- **Separate process for actions** — Actions run via `pnpm action` in a new Node.js process. Use the server's HTTP endpoints (not the collab module directly) so updates reach the poll system.