@agent-native/core 0.6.1 → 0.7.1

package/docs/content/file-uploads.md

@@ -0,0 +1,102 @@
+---
+title: "File Uploads"
+description: "Configure file upload storage — SQL fallback for dev, Builder.io or custom providers for production."
+---
+
+# File Uploads
+
+The framework provides a file upload abstraction that routes uploads through a configurable provider. Templates call `uploadFile()` and get back a URL — the storage backend is swappable without changing application code.
+
+## How It Works {#how-it-works}
+
+Upload requests go to `POST /_agent-native/file-upload`, which dispatches to the active provider. You can check which provider is configured at `GET /_agent-native/file-upload/status`.
+
+The provider resolution order is:
+
+1. **User-registered providers** — custom providers registered via `registerFileUploadProvider()`
+2. **Builder.io provider** — built-in, activates automatically when Builder.io is connected
+3. **SQL fallback** — stores files as base64 in the database (fine for dev, not for production)
+
+## Default: SQL Fallback {#sql-fallback}
+
+When no provider is configured, files are stored as base64 data in the SQL database via the resources system. This works out of the box for local development but is not recommended for production — large files bloat the database and there's no CDN.
+
+A one-time warning is logged when the fallback is used.
+
+## Builder.io Hosting {#builder-hosting}
+
+When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Files are served from a CDN with no configuration needed. This is the recommended production setup.
+
+## Custom Providers {#custom-providers}
+
+Register a custom provider in a server plugin to use any storage backend (S3, Cloudflare R2, GCS, etc.):
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## Upload API {#upload-api}
+
+The `FileUploadProvider` interface:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+Use `uploadFile()` from `@agent-native/core/file-upload` in actions or server code:
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

package/docs/content/frames.md

@@ -0,0 +1,47 @@
+---
+title: "Frames"
+description: "Embedded agent panel and cloud frame options for running AI agents alongside your app."
+---
+
+# Frames
+
+Agent-native apps run with an AI agent alongside the app UI. Locally, the agent panel is embedded directly in your app. In the cloud, Builder.io provides a managed frame with collaboration and visual editing.
+
+## Embedded Agent Panel {#embedded-agent}
+
+- Ships with `@agent-native/core` — no separate package needed
+- Agent panel embedded directly in your app with chat and optional CLI terminal
+- Supports multiple AI coding CLIs — switch between them from the settings panel
+- Toggle between production mode (app tools only) and development mode (full filesystem, shell, and database access)
+- Great for local development, self-hosted production, and OSS
+
+## Supported CLIs {#supported-clis}
+
+| CLI         | Command    | Key Flags                                           |
+| ----------- | ---------- | --------------------------------------------------- |
+| Claude Code | `claude`   | --dangerously-skip-permissions, --resume, --verbose |
+| Codex       | `codex`    | --full-auto, --quiet                                |
+| Gemini CLI  | `gemini`   | --sandbox                                           |
+| OpenCode    | `opencode` | —                                                   |
+| Builder.io  | `builder`  | —                                                   |
+
+Switch between CLIs at any time from the agent panel settings. The terminal restarts with the selected CLI.
+
+## [Builder.io Cloud](https://www.builder.io) {#cloud-frame}
+
+- Runs in the cloud
+- Real-time collaboration — multiple users can watch/interact simultaneously
+- Visual editing, roles and permissions
+- Parallel agent execution for faster iteration
+- Great for team use
+
+## How It Works {#how-it-works}
+
+The framework provides type-safe APIs so you never deal with raw messaging:
+
+1. **Agent chat** — use `sendToAgentChat()` to send messages to the agent
+2. **Generation state** — use `useAgentChatGenerating()` to track when the agent is running
+3. **File watching** — SSE endpoint keeps UI in sync when the agent modifies files
+4. **Action system** — `pnpm action <name>` dispatches to callable actions
+
+Your app code is identical regardless of how the agent is provided.

package/docs/content/getting-started.md

@@ -0,0 +1,104 @@
+---
+title: "Getting Started"
+description: "Pick a template, create your app, and start customizing it with AI."
+---
+
+# Getting Started
+
+The fastest way to get started is to pick a template and customize it. Templates are complete, production-ready apps — not starter kits. You get a working app in under a minute and start making it yours.
+
+## Create Your Workspace {#create-your-app}
+
+```bash
+npx @agent-native/core create my-platform
+```
+
+The CLI shows a multi-select picker — pick as many templates as you want (Mail + Calendar + Forms, for example) and they all get scaffolded into the same workspace sharing auth, brand, and agent config. Then boot them all:
+
+```bash
+cd my-platform
+pnpm install
+pnpm dev
+```
+
+That's it — you have every app running locally with an AI agent built in. Open the agent panel, ask it to do something, and watch it work.
+
+Want a single app with no monorepo? Pass `--standalone`:
+
+```bash
+npx @agent-native/core create my-app --standalone --template mail
+```
+
+Need to add more apps later? From inside the workspace:
+
+```bash
+agent-native add-app
+```
+
+From here, use your AI coding tool (Claude Code, Cursor, Windsurf, etc.) to customize it. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase. See [Enterprise Workspace](/docs/enterprise-workspace) for the full story on sharing auth, skills, components, and credentials across apps.
+
+## Templates {#templates}
+
+Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:
+
+| Template                          | Replaces                    |
+| --------------------------------- | --------------------------- |
+| [Mail](/templates/mail)           | Superhuman, Gmail           |
+| [Calendar](/templates/calendar)   | Google Calendar, Calendly   |
+| [Content](/templates/content)     | Notion, Google Docs         |
+| [Slides](/templates/slides)       | Google Slides, Pitch        |
+| [Video](/templates/video)         | video editing               |
+| [Analytics](/templates/analytics) | Amplitude, Mixpanel, Looker |
+
+Browse the [template gallery](/templates) for live demos and detailed feature lists.
+
+## Project Structure {#project-structure}
+
+Every agent-native app — whether from a template or from scratch — follows the same structure:
+
+```text
+my-app/
+  app/             # React frontend (routes, components, hooks)
+  server/          # Nitro API server (routes, plugins)
+  actions/         # Agent-callable actions
+  .agents/         # Agent instructions and skills
+```
+
+Templates add domain-specific code on top of this: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`.
+
+## Configuration {#configuration}
+
+Templates come pre-configured. If you're starting from scratch, here are the config files:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "@agent-native/core/vite";
+export default defineConfig();
+```
+
+```json
+// tsconfig.json
+{ "extends": "@agent-native/core/tsconfig.base.json" }
+```
+
+```ts
+// tailwind.config.ts
+import type { Config } from "tailwindcss";
+import preset from "@agent-native/core/tailwind";
+
+export default {
+  presets: [preset],
+  content: ["./app/**/*.{ts,tsx}"],
+} satisfies Config;
+```
+
+## Architecture Principles {#architecture-principles}
+
+These principles apply to all agent-native apps. Understanding them helps you customize templates or build from scratch:
+
+1. **Agent + UI are equal partners** — Everything the UI can do, the agent can do, and vice versa. They share the same database and always stay in sync. You don't think about "the agent" and "the app" separately — you think about them together.
+2. **Context-aware** — The agent always knows what you're looking at. If an email is open, it knows which one. If you select text and hit Cmd+I, it can act on just that selection.
+3. **Skills-driven** — Core functionalities have instructions so the agent doesn't explore from scratch every time. When you add a feature, you update all four areas: UI, actions, skills/instructions, and application state.
+4. **Inter-agent communication** — Agents can discover and call each other via the A2A protocol. Tag your analytics agent from the mail app to pull data into a draft.
+5. **Fully portable** — Any SQL database Drizzle supports, any hosting backend Nitro supports, any AI coding tool. These are non-negotiable.
+6. **Fork and customize** — Apps you clone and evolve. The agent can modify the app's own code — components, routes, styles, actions — so it gets better over time.

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.