@agent-native/core 0.6.1 → 0.7.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 |

package/docs/content/cli-adapters.md

@@ -0,0 +1,244 @@
+---
+title: "CLI Adapters"
+description: "Connect any CLI tool to your agent-native app with a standard adapter interface for discovery and execution."
+---
+
+# CLI Adapters
+
+Give your agent structured access to any CLI tool — with discovery, execution, and consistent output handling.
+
+## Overview {#overview}
+
+Agents are great at running CLI commands. But without structure, every script reinvents how to invoke a CLI, check if it's installed, and parse its output.
+
+CLI adapters solve this with a small interface — similar to file sync adapters but for command-line tools. Each adapter wraps a single CLI (`gh`, `ffmpeg`, `stripe`, `aws`) and provides:
+
+- **Discovery** — the agent can list what CLIs are available and what they do
+- **Availability checks** — is the CLI installed?
+- **Consistent execution** — stdout, stderr, and exit code in a standard format
+
+## The interface {#the-interface}
+
+Every CLI adapter implements `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+## ShellCliAdapter {#shell-adapter}
+
+For most CLIs, you don't need a custom class. `ShellCliAdapter` wraps any CLI binary with sensible defaults:
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+});
+
+const stripe = new ShellCliAdapter({
+  command: "stripe",
+  description: "Stripe CLI — manage payments, webhooks, and customers",
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+### Options {#shell-adapter-options}
+
+| Option        | Type   | Description                                         |
+| ------------- | ------ | --------------------------------------------------- |
+| `command`     | string | Binary name or path (required)                      |
+| `description` | string | What the CLI does — shown to the agent (required)   |
+| `name`        | string | Display name (defaults to `command`)                |
+| `env`         | Record | Extra environment variables merged with process.env |
+| `cwd`         | string | Working directory (defaults to process.cwd())       |
+| `timeoutMs`   | number | Execution timeout (default: 30000)                  |
+
+## Registry {#registry}
+
+The `CliRegistry` collects adapters so the agent can discover what's available at runtime:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "ffmpeg",
+    description: "Audio/video processing and transcoding",
+  }),
+);
+
+// List all registered CLIs
+cliRegistry.list();
+// → [{ name: "gh", ... }, { name: "ffmpeg", ... }]
+
+// List only installed CLIs
+await cliRegistry.listAvailable();
+// → [{ name: "gh", ... }]  (if ffmpeg isn't installed)
+
+// Get a full summary for agent discovery
+await cliRegistry.describe();
+// → [{ name: "gh", description: "...", available: true },
+//    { name: "ffmpeg", description: "...", available: false }]
+
+// Execute a command
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+console.log(result?.stdout);
+```
+
+## Custom adapters {#custom-adapter}
+
+When you need more than `ShellCliAdapter` provides — custom auth, output parsing, or pre/post processing — implement `CliAdapter` directly:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+import { execFile } from "node:child_process";
+
+export class DockerAdapter implements CliAdapter {
+  name = "docker";
+  description =
+    "Docker container management — build, run, and manage containers";
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      const result = await this.execute([
+        "info",
+        "--format",
+        "{{.ServerVersion}}",
+      ]);
+      return result.exitCode === 0;
+    } catch {
+      return false;
+    }
+  }
+
+  async execute(args: string[]): Promise<CliResult> {
+    return new Promise((resolve) => {
+      execFile(
+        "docker",
+        args,
+        {
+          timeout: 60_000,
+          maxBuffer: 10 * 1024 * 1024,
+          encoding: "utf-8",
+        },
+        (error, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            exitCode: (error as any)?.code ?? 0,
+          });
+        },
+      );
+    });
+  }
+}
+```
+
+## Server route {#server-route}
+
+Expose the registry to the UI via an API route so actions and components can discover and invoke CLIs:
+
+```ts
+// server/index.ts
+import { createServer } from "@agent-native/core";
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const app = createServer();
+const cliRegistry = new CliRegistry();
+
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI",
+  }),
+);
+
+// Discovery endpoint — agent can query this
+app.get("/api/cli", async (_req, res) => {
+  const tools = await cliRegistry.describe();
+  res.json(tools);
+});
+
+// Execution endpoint
+app.post("/api/cli/:name", async (req, res) => {
+  const adapter = cliRegistry.get(req.params.name);
+  if (!adapter) return res.status(404).json({ error: "CLI not found" });
+
+  const { args } = req.body;
+  const result = await adapter.execute(args ?? []);
+  res.json(result);
+});
+```
+
+## Using from actions {#from-scripts}
+
+Actions can use CLI adapters directly for structured access:
+
+```ts
+// actions/list-prs.ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI",
+});
+
+export default async function listPrs() {
+  if (!(await gh.isAvailable())) {
+    console.error("GitHub CLI not installed. Run: brew install gh");
+    process.exit(1);
+  }
+
+  const result = await gh.execute([
+    "pr",
+    "list",
+    "--json",
+    "title,url,state",
+    "--limit",
+    "10",
+  ]);
+
+  if (result.exitCode !== 0) {
+    console.error(result.stderr);
+    process.exit(1);
+  }
+
+  const prs = JSON.parse(result.stdout);
+  const fs = await import("node:fs/promises");
+  await fs.writeFile("data/prs.json", JSON.stringify(prs, null, 2));
+  console.log(`Fetched ${prs.length} PRs`);
+}
+```
+
+Or skip the adapter entirely and call the CLI directly in a script — adapters are useful when you want discovery, availability checks, and consistent error handling, but they're not required. Use whichever approach fits.