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

package/docs/content/a2a-protocol.md

@@ -0,0 +1,223 @@
+---
+title: "A2A Protocol"
+description: "Agent-to-agent communication via JSON-RPC: discovery, messaging, streaming, and task management."
+---
+
+# A2A Protocol
+
+Agent-to-agent communication over HTTP. Agents discover each other, send messages, and receive structured results.
+
+## Overview {#overview}
+
+A2A (agent-to-agent) is a JSON-RPC protocol for inter-agent communication. A mail agent can ask an analytics agent to run a query. A calendar agent can search issues in a project management agent. Each agent exposes its capabilities via an agent card and accepts work via a standard JSON-RPC endpoint.
+
+Key concepts:
+
+- **Agent card** — public metadata at `/.well-known/agent-card.json` describing skills and capabilities
+- **JSON-RPC** — all communication goes through `POST /a2a` with standard JSON-RPC 2.0
+- **Tasks** — each message creates a task with a lifecycle (submitted, working, completed, failed, canceled)
+- **Bearer auth** — optional API key authentication via environment variable
+
+## Server setup {#server-setup}
+
+Call `mountA2A()` in a server plugin to expose the A2A endpoints:
+
+```ts
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  mountA2A(nitro.h3App, {
+    name: "Analytics Agent",
+    description: "Runs analytics queries and returns chart data",
+    skills: [
+      {
+        id: "run-query",
+        name: "Run Query",
+        description: "Execute a SQL query against the analytics database",
+        tags: ["analytics", "sql"],
+        examples: ["Show me signups by source this month"],
+      },
+    ],
+    apiKeyEnv: "A2A_API_KEY", // env var name for bearer token
+    streaming: true, // enable message/stream
+  });
+});
+```
+
+This mounts two endpoints: `GET /.well-known/agent-card.json` (public, no auth) and `POST /a2a` (authenticated JSON-RPC).
+
+## Agent card {#agent-card}
+
+The agent card is auto-generated from your config and served at `/.well-known/agent-card.json`. Other agents fetch it to discover your agent's skills.
+
+```json
+{
+  "name": "Analytics Agent",
+  "description": "Runs analytics queries and returns chart data",
+  "url": "https://analytics.example.com",
+  "version": "1.0.0",
+  "protocolVersion": "0.3",
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": false,
+    "stateTransitionHistory": true
+  },
+  "skills": [
+    {
+      "id": "run-query",
+      "name": "Run Query",
+      "description": "Execute a SQL query against the analytics database",
+      "tags": ["analytics", "sql"],
+      "examples": ["Show me signups by source this month"]
+    }
+  ],
+  "securitySchemes": {
+    "apiKey": { "type": "http", "scheme": "bearer" }
+  },
+  "security": [{ "apiKey": [] }]
+}
+```
+
+## JSON-RPC methods {#json-rpc-methods}
+
+All methods are called via `POST /a2a` with JSON-RPC 2.0 format:
+
+| Method           | Description                               | Key params            |
+| ---------------- | ----------------------------------------- | --------------------- |
+| `message/send`   | Send a message, get a completed task back | `message, contextId?` |
+| `message/stream` | Send a message, receive SSE task updates  | `message, contextId?` |
+| `tasks/get`      | Fetch a task by ID                        | `id`                  |
+| `tasks/cancel`   | Cancel a running task                     | `id`                  |
+
+Messages contain typed parts:
+
+```json
+{
+  "role": "user",
+  "parts": [
+    { "type": "text", "text": "Show signups by source" },
+    { "type": "data", "data": { "dateRange": "last-30d" } },
+    {
+      "type": "file",
+      "file": { "name": "report.csv", "mimeType": "text/csv", "bytes": "..." }
+    }
+  ]
+}
+```
+
+## Client {#client}
+
+The `A2AClient` class handles discovery, messaging, and streaming:
+
+```ts
+import { A2AClient } from "@agent-native/core/a2a";
+
+const client = new A2AClient("https://analytics.example.com", "my-api-key");
+
+// Discover agent capabilities
+const card = await client.getAgentCard();
+console.log(card.skills);
+
+// Send a message and get a completed task
+const task = await client.send({
+  role: "user",
+  parts: [{ type: "text", text: "Show signups by source this month" }],
+});
+console.log(task.status.state); // "completed"
+console.log(task.status.message); // agent's response
+
+// Stream responses for long-running work
+for await (const update of client.stream({
+  role: "user",
+  parts: [{ type: "text", text: "Generate a full quarterly report" }],
+})) {
+  console.log(update.status.state, update.status.message);
+}
+```
+
+## Convenience helper {#convenience-helper}
+
+For simple text-in/text-out calls, use `callAgent()`:
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// One-shot: send text, get text back
+const response = await callAgent(
+  "https://analytics.example.com",
+  "How many signups last week?",
+  { apiKey: process.env.ANALYTICS_API_KEY },
+);
+console.log(response); // "There were 1,247 signups last week..."
+```
+
+## Task lifecycle {#task-lifecycle}
+
+Each message creates a task that moves through these states:
+
+`submitted` → `working` → `completed` | `failed` | `canceled`
+
+| State            | Meaning                                        |
+| ---------------- | ---------------------------------------------- |
+| `submitted`      | Task created, queued for processing            |
+| `working`        | Handler is processing the message              |
+| `completed`      | Handler finished successfully                  |
+| `failed`         | Handler threw an error                         |
+| `canceled`       | Task was canceled via tasks/cancel             |
+| `input-required` | Handler needs more information from the caller |
+
+Tasks persist in the `a2a_tasks` SQL table and can be retrieved later via `tasks/get`.
+
+## Security {#security}
+
+Set `apiKeyEnv` in your config to the name of an environment variable containing the expected bearer token:
+
+```ts
+// Config
+mountA2A(app, {
+  // ...
+  apiKeyEnv: "A2A_API_KEY", // reads process.env.A2A_API_KEY
+});
+
+// Client calls with the matching key
+const client = new A2AClient(url, process.env.A2A_API_KEY);
+```
+
+The agent card endpoint is always public (no auth) so other agents can discover capabilities. The `/a2a` JSON-RPC endpoint requires a valid bearer token when `apiKeyEnv` is set. In dev mode (no env var configured), auth is skipped.
+
+## Agent mentions {#agent-mentions}
+
+You can `@`-mention agents directly in the chat composer. Connected agents use A2A: when you mention a connected agent, the server makes an A2A call to that agent and weaves the response into your conversation context.
+
+Custom workspace agents are different: they run locally inside the current app/runtime rather than over A2A.
+
+See [Agent Mentions](/docs/agent-mentions) for details on how mentions work, how to add agents, and how to create custom mention providers.
+
+## Messaging integrations {#messaging-integrations}
+
+Agents can also be reached from external messaging platforms like Slack, Telegram, and WhatsApp. Users send messages on those platforms and the agent responds in the same thread, using the same tools and actions as the web chat.
+
+See [Integrations](/docs/integrations) for setup details on each platform.
+
+## Example: cross-agent query {#example}
+
+A mail agent needs analytics data. The analytics agent exposes a "run-query" skill via A2A:
+
+```ts
+// In the mail agent's actions/get-analytics.ts
+import { callAgent } from "@agent-native/core/a2a";
+
+export default async function (args: string[]) {
+  const response = await callAgent(
+    "https://analytics.example.com",
+    "How many emails were sent last week by category?",
+    { apiKey: process.env.ANALYTICS_API_KEY },
+  );
+
+  console.log(response);
+  // The mail agent can now use this data in its response
+}
+```
+
+The analytics agent receives the message, runs the query via its handler, and returns the result. The mail agent's script gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.

package/docs/content/actions.md

@@ -0,0 +1,129 @@
+---
+title: "Actions"
+description: "Action dispatcher, parseArgs, standard actions, and utility functions for agent-callable operations."
+---
+
+# Actions
+
+`@agent-native/core` provides an action dispatcher and utilities for building agent-callable actions.
+
+## Action Dispatcher {#action-dispatcher}
+
+The action system lets you create actions that agents can invoke via `pnpm action <name>`. Each action is a TypeScript file that exports a default async function.
+
+```ts
+// actions/run.ts — dispatcher (one-time setup)
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+```ts
+// actions/hello.ts — example action
+import { parseArgs } from "@agent-native/core";
+
+export default async function hello(args: string[]) {
+  const { name } = parseArgs(args);
+  console.log(`Hello, ${name ?? "world"}!`);
+}
+```
+
+```bash
+# Run it
+pnpm action hello --name Steve
+```
+
+## parseArgs(args) {#parseargs}
+
+Parse CLI arguments in `--key value` or `--key=value` format:
+
+```ts
+import { parseArgs } from "@agent-native/core";
+
+const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
+// { name: "Steve", verbose: "true", count: "3" }
+```
+
+## Standard actions {#standard-actions}
+
+Every template should include these two actions for [context awareness](/docs/context-awareness):
+
+### view-screen {#view-screen}
+
+Reads the current navigation state, fetches contextual data, and returns a snapshot of what the user sees. The agent should always call this before acting.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const screen: Record<string, unknown> = { navigation };
+
+  if (navigation?.view === "inbox") {
+    const res = await fetch(
+      "http://localhost:3000/api/emails?label=" + navigation.label,
+    );
+    screen.emailList = await res.json();
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+```bash
+pnpm action view-screen
+```
+
+### navigate {#navigate}
+
+Writes a one-shot navigation command to application-state. The UI reads it, navigates, and deletes the entry.
+
+```ts
+// actions/navigate.ts
+import { parseArgs } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
+
+export default async function main(args: string[]) {
+  const parsed = parseArgs(args);
+  await writeAppState("navigate", parsed);
+  console.log("Navigate command written:", parsed);
+}
+```
+
+```bash
+pnpm action navigate --view inbox --threadId thread-123
+```
+
+## Shared Agent Chat {#shared-agent-chat}
+
+`@agent-native/core` provides an isomorphic chat bridge that works in both browser and Node.js:
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+// Auto-submit a message
+agentChat.submit("Generate a report for Q4");
+
+// Prefill without submitting
+agentChat.prefill("Draft an email to...", contextData);
+
+// Full control
+agentChat.send({
+  message: "Process this data",
+  context: JSON.stringify(data),
+  submit: true,
+});
+```
+
+In the browser, messages are sent via `window.postMessage()`. In Node.js (actions), they use the `BUILDER_PARENT_MESSAGE:` stdout format that the Electron host translates to postMessage.
+
+## Utility Functions {#utility-functions}
+
+| Function                | Returns   | Description                                        |
+| ----------------------- | --------- | -------------------------------------------------- |
+| `loadEnv(path?)`        | `void`    | Load .env from project root (or custom path)       |
+| `camelCaseArgs(args)`   | `Record`  | Convert kebab-case keys to camelCase               |
+| `isValidPath(p)`        | `boolean` | Validate relative path (no traversal, no absolute) |
+| `isValidProjectPath(p)` | `boolean` | Validate project slug (e.g. "my-project")          |
+| `ensureDir(dir)`        | `void`    | mkdir -p helper                                    |
+| `fail(message)`         | `never`   | Print error to stderr and exit(1)                  |

package/docs/content/agent-mentions.md

@@ -0,0 +1,171 @@
+---
+title: "Agent Mentions"
+description: "Tag custom agents, connected agents, and files in chat with @-mentions."
+---
+
+# Agent Mentions
+
+Type `@` in the chat composer to mention custom agents, connected agents, files, and resources.
+
+## Overview {#overview}
+
+The `@`-mention system connects the chat composer to the broader agent ecosystem. When you type `@`, a popover appears listing available custom agents, connected agents, codebase files, and resources.
+
+This is how you orchestrate multi-agent workflows from a single chat. Ask your local `@design` agent to critique a layout, `@analytics` to pull in the latest numbers from another app, and the main agent can incorporate both in one conversation.
+
+## Mentioning agents {#mentioning-agents}
+
+To mention an agent in the chat composer:
+
+1. Type `@` to open the mention popover
+2. Browse or search the list of available agents
+3. Select an agent — it appears as a tag in your message
+4. Send the message — the server resolves the mention and includes that agent's response in the conversation context
+
+There are two agent paths:
+
+- **Custom agents** — local workspace agent profiles in `agents/*.md`. These run inside the current app/runtime using the agent profile's instructions and optional model override.
+- **Connected agents** — remote A2A peers. These are called over the [A2A protocol](/docs/a2a-protocol).
+
+In both cases, your main agent sees the response and can reference or build on it.
+
+## How it works {#how-it-works}
+
+When a message containing an `@`-mention is sent, the following happens on the server:
+
+1. The server extracts mention references from the message
+2. For each mentioned agent:
+   - custom agents run locally with their profile instructions
+   - connected agents are called via A2A
+3. The agent's response is wrapped in an `<agent-response>` XML block and injected into the conversation context
+4. The main agent processes the enriched message, seeing both the user's text and the mentioned agent's response
+
+```text
+// What the main agent sees in its context:
+User: Draft an email with the latest signup numbers. @analytics
+
+<agent-response agent="analytics">
+Last week's signups: 1,247 total
+  - Organic: 623
+  - Paid: 412
+  - Referral: 212
+</agent-response>
+```
+
+The main agent can then use this data naturally in its response — for example, incorporating the numbers into an email draft.
+
+## Adding agents {#adding-agents}
+
+Agents become available for mentioning through several mechanisms:
+
+- **Custom workspace agents** — create agent profiles in the Workspace tab as `agents/*.md`
+- **Auto-discovery** — the framework automatically discovers connected agents running on known ports or configured URLs
+- **Remote manifests** — add connected-agent manifests as `agents/*.json`
+
+### Custom workspace agents
+
+Custom agents are Markdown resources:
+
+```markdown
+---
+name: Design
+description: >-
+  Reviews layouts, product UX, and visual direction.
+model: inherit
+tools: inherit
+delegate-default: false
+---
+
+# Role
+
+You are a focused design agent.
+```
+
+You can create them from the Workspace tab using:
+
+- `Create Agent` -> `Describe It`
+- `Create Agent` -> `Fill Form`
+
+### Connected-agent manifests
+
+Remote A2A agents still use JSON manifests:
+
+```json
+// agents/analytics.json
+{
+  "name": "Analytics Agent",
+  "url": "https://analytics.example.com",
+  "apiKey": "env:ANALYTICS_A2A_KEY",
+  "description": "Runs analytics queries and returns data",
+  "skills": ["run-query", "generate-chart"]
+}
+```
+
+## Custom mention providers {#custom-mention-providers}
+
+Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface:
+
+```ts
+import type { MentionProvider } from "@agent-native/core/server";
+
+const contactsProvider: MentionProvider = {
+  id: "contacts",
+  label: "Contacts",
+
+  // Search for mentionable items
+  async search(query: string) {
+    const contacts = await db.query.contacts.findMany({
+      where: like(contacts.name, `%${query}%`),
+      limit: 10,
+    });
+    return contacts.map((c) => ({
+      id: c.id,
+      label: c.name,
+      description: c.email,
+      type: "contact",
+    }));
+  },
+
+  // Resolve a mention into context for the agent
+  async resolve(id: string) {
+    const contact = await db.query.contacts.findFirst({
+      where: eq(contacts.id, id),
+    });
+    return {
+      type: "context",
+      text: `Contact: ${contact.name} (${contact.email})`,
+    };
+  },
+};
+```
+
+Register providers in the agent-chat plugin configuration:
+
+```ts
+// server/plugins/agent-chat.ts
+import { createAgentChatPlugin } from "@agent-native/core/server";
+
+export default createAgentChatPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  mentionProviders: [contactsProvider],
+});
+```
+
+Custom mention providers appear alongside the built-in agent and file providers in the mention popover.
+
+## Referencing files {#referencing-files}
+
+The `@` popover is not limited to agents. You can also reference:
+
+- **Codebase files** — type `@` and search for a filename. The file contents are included in the agent's context so it can read, analyze, or modify the file.
+- **Workspace resources** — reference files defined in the Workspace tab. These can be data files, configuration, or any other structured content.
+- **Skills** — type `/` to reference a skill. Skills provide structured instructions that guide how the agent approaches a task.
+
+All reference types follow the same pattern: select from the popover, and the referenced content is resolved and injected into the agent's context when the message is sent.
+
+## Sub-agent selection {#sub-agent-selection}
+
+The main agent can also use custom agents when spawning sub-agents with `spawn-task`.
+
+Pass the `agent` parameter to choose a profile from `agents/*.md`. That profile's instructions are added to the delegated run, and its `model` frontmatter can override the default model for that sub-agent.

package/docs/content/authentication.md

@@ -0,0 +1,155 @@
+---
+title: "Authentication"
+description: "Better Auth integration with email/password, social providers, organizations, and access tokens."
+---
+
+# Authentication
+
+Agent-native apps use [Better Auth](https://better-auth.com) for authentication with an account-first design. Users create an account on first visit and get real identity from day one.
+
+## Overview {#overview}
+
+Auth is configured automatically via `autoMountAuth(app)` in the auth server plugin. The behavior depends on your environment:
+
+- **Default:** Better Auth with email/password + social providers. Onboarding page shown on first visit.
+- **`AUTH_MODE=local`:** No auth. Solo local development with `local@localhost` identity.
+- **`ACCESS_TOKEN`:** Simple shared token for production.
+- **Custom:** Bring your own auth via `getSession` callback.
+
+## Better Auth (Default) {#better-auth}
+
+When no `ACCESS_TOKEN` or `AUTH_MODE=local` is set, Better Auth powers authentication. It provides:
+
+- Email/password registration and login
+- Social providers (Google, GitHub, and 35+ others)
+- Organizations with roles and invitations
+- JWT tokens for API and A2A access
+- Bearer token support for programmatic clients
+
+Better Auth routes are mounted at `/_agent-native/auth/ba/*`. The framework also provides backward-compatible endpoints:
+
+- `GET /_agent-native/auth/session` — get current session
+- `POST /_agent-native/auth/login` — email/password or token login
+- `POST /_agent-native/auth/register` — create account
+- `POST /_agent-native/auth/logout` — sign out
+
+## Development Mode {#dev-mode}
+
+In development (`NODE_ENV=development`), auth is automatically bypassed. If no other auth method succeeds (no account, no token, no local mode marker), `getSession()` returns `{ email: "local@localhost" }` so you can use the app immediately without any configuration.
+
+This means you can run any template app locally and start using it right away — no account creation, no environment variables needed.
+
+## Local Mode {#local-mode}
+
+For explicit no-auth in any environment (including production), set `AUTH_MODE=local` in your `.env` file. This returns `{ email: "local@localhost" }` for all requests, skipping all other auth checks.
+
+You can also enable local mode from the onboarding page by clicking "Use locally without an account". This writes a marker file that persists across server restarts.
+
+```bash
+# .env
+AUTH_MODE=local
+```
+
+To switch back to real auth, remove the line from `.env` (or clear the marker file by calling `POST /_agent-native/auth/exit-local-mode`).
+
+## Social Providers {#social-providers}
+
+Set environment variables to enable social login. Better Auth auto-detects them:
+
+```bash
+# Google OAuth
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# GitHub OAuth
+GITHUB_CLIENT_ID=your-client-id
+GITHUB_CLIENT_SECRET=your-client-secret
+```
+
+Templates that use `createGoogleAuthPlugin()` show a "Sign in with Google" page. The Google OAuth callback handles mobile deep linking for native apps automatically.
+
+## Organizations {#organizations}
+
+Better Auth's organization plugin is built into the framework. Every app supports:
+
+- Creating organizations
+- Inviting members with roles (`owner`, `admin`, `member`)
+- Switching active organization
+- Per-org data scoping via `org_id` columns
+
+The active organization flows automatically through the system: `session.orgId` → `AGENT_ORG_ID` → SQL scoping. See the [Security & Data Scoping](/docs/security) docs for details.
+
+## Access Tokens {#access-tokens}
+
+For simple deployments, set `ACCESS_TOKEN` (single) or `ACCESS_TOKENS` (comma-separated) as environment variables:
+
+```bash
+# Single token
+ACCESS_TOKEN=my-secret-token
+
+# Multiple tokens
+ACCESS_TOKENS=token1,token2,token3
+```
+
+When access tokens are configured, users see a token login page. Sessions are cookie-based with 30-day expiry.
+
+## Bring Your Own Auth {#byoa}
+
+Pass a custom `getSession` callback to use any auth provider (Clerk, Auth0, Firebase, etc.):
+
+```typescript
+// server/plugins/auth.ts
+import { createAuthPlugin } from "@agent-native/core/server";
+
+export default createAuthPlugin({
+  getSession: async (event) => {
+    // Your custom auth logic here
+    const session = await myAuthProvider.verify(event);
+    if (!session) return null;
+    return { email: session.email };
+  },
+  publicPaths: ["/api/webhooks"],
+});
+```
+
+## Session API {#session-api}
+
+The session object returned by `getSession(event)` has this shape:
+
+```typescript
+interface AuthSession {
+  email: string; // User's email (primary identifier)
+  userId?: string; // Better Auth user ID
+  token?: string; // Session token
+  orgId?: string; // Active organization ID
+  orgRole?: string; // Role in active org (owner/admin/member)
+}
+```
+
+On the client, use the `useSession()` hook:
+
+```typescript
+import { useSession } from "@agent-native/core/client";
+
+function MyComponent() {
+  const { session, isLoading } = useSession();
+  if (isLoading) return <p>Loading...</p>;
+  if (!session) return <p>Not signed in</p>;
+  return <p>Hello, {session.email}</p>;
+}
+```
+
+## Environment Variables {#environment-variables}
+
+| Variable               | Purpose                                                          |
+| ---------------------- | ---------------------------------------------------------------- |
+| `AUTH_MODE`            | Set to `local` to disable auth                                   |
+| `BETTER_AUTH_SECRET`   | Signing key for Better Auth (auto-generated if not set)          |
+| `GOOGLE_CLIENT_ID`     | Enable Google OAuth                                              |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth secret                                              |
+| `GITHUB_CLIENT_ID`     | Enable GitHub OAuth                                              |
+| `GITHUB_CLIENT_SECRET` | GitHub OAuth secret                                              |
+| `ACCESS_TOKEN`         | Simple shared token auth                                         |
+| `ACCESS_TOKENS`        | Comma-separated shared tokens                                    |
+| `AUTH_DISABLED`        | Set to `true` to skip auth (infrastructure-level auth)           |
+| `A2A_SECRET`           | Shared secret for JWT-signed A2A cross-app identity verification |