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

package/src/templates/default/.agents/skills/actions/SKILL.md

@@ -40,24 +40,30 @@ export default async function myAction(args: string[]) {
 }
 ```
 
-### Using `defineAction` (recommended for new actions)
+### Using `defineAction` with Zod schema (recommended for new actions)
 
 ```ts
+import { z } from "zod";
 import { defineAction } from "@agent-native/core";
 
 export default defineAction({
   description: "Process some data",
-  parameters: {
-    input: { type: "string", description: "Input file path" },
-    output: { type: "string", description: "Output file path" },
-  },
+  schema: z.object({
+    input: z.string().describe("Input file path"),
+    output: z.string().optional().describe("Output file path"),
+  }),
   run: async (args) => {
+    // args is fully typed: { input: string; output?: string }
     // do work
     return "Done";
   },
 });
 ```
 
+The `schema` field accepts a Zod schema (or any Standard Schema-compatible library). It provides runtime validation with clear error messages, TypeScript type inference for `run()` args, and auto-generated JSON Schema for the agent's tool definition. `zod` is a dependency of all templates.
+
+The legacy `parameters` field (plain JSON Schema object) still works as a fallback.
+
 ## How to Run
 
 ```bash
@@ -78,7 +84,8 @@ This is the canonical approach for new apps. Action names must be lowercase with
 ## Guidelines
 
 - **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
-- **Use `parseArgs()`** for structured argument parsing. It converts `--key value` pairs to a `Record<string, string>`.
+- **Always use `defineAction` with a Zod `schema:`** for input validation. The framework validates automatically and returns clear error messages for invalid input. This prevents malicious or malformed input from reaching your code. The legacy `parseArgs()` format has no runtime validation — use it only for internal/dev scripts, not user-facing actions.
+- **Never construct SQL with string concatenation** — use the `db-exec`/`db-query` tools which parameterize queries automatically (`?` placeholders). Drizzle ORM queries are always safe.
 - **Use `loadEnv()`** if the action needs environment variables (API keys, etc.).
 - **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
 - **Write results to the database.** The agent and UI will pick them up via db sync polling.
@@ -131,6 +138,6 @@ export default async function transform(args: string[]) {
 
 ## Related Skills
 
-- **files-as-database** -- Actions read/write data files in `data/`
+- **storing-data** -- Actions read/write data via SQL
 - **delegate-to-agent** -- The agent invokes actions via `pnpm action <name>`
 - **real-time-sync** -- Database writes from actions trigger poll events to update the UI

package/src/templates/default/.agents/skills/agent-engines/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: agent-engines
+description: >-
+  How to inspect and configure the AI engine (model provider) powering the
+  agent. Use when the user asks to switch models, check which engine is active,
+  test a new provider, or register a custom engine.
+---
+
+# Agent Engines
+
+## Overview
+
+The framework supports pluggable AI engines beneath the agent loop. The **Anthropic engine** is the default and best-in-class path (Claude models). Additional engines can be added via the Vercel AI SDK (OpenAI, Google Gemini, Groq, Mistral, Cohere, Ollama).
+
+## Available Tools
+
+| Tool | Purpose |
+|---|---|
+| `list-agent-engines` | List all registered engines, their capabilities, and the current selection |
+| `set-agent-engine` | Set the active engine and model (persisted in settings) |
+| `test-agent-engine` | Send a trivial prompt to verify the engine works (connectivity + API key) |
+
+## Checking the Current Engine
+
+```
+list-agent-engines
+```
+
+Returns the registry of all engines (name, label, capabilities, supported models) plus the currently active engine and model.
+
+## Switching Engines
+
+```
+set-agent-engine --engine "ai-sdk:openai" --model "gpt-4o"
+```
+
+Changes take effect on the next conversation. The setting is persisted via the settings store (`agent-engine` key).
+
+Resolution order (highest priority first):
+1. Explicit `engine` option passed to `createAgentChatPlugin()` in the server plugin
+2. Settings store (`agent-engine` key)
+3. `AGENT_ENGINE` environment variable
+4. Default: `"anthropic"` (requires `ANTHROPIC_API_KEY`)
+
+## Testing a New Engine
+
+Before switching, verify the engine is working:
+
+```
+test-agent-engine --engine "ai-sdk:openai" --model "gpt-4o"
+```
+
+Returns `{ ok, latencyMs, response, capabilities }`. If `ok: false`, the error message explains what's wrong (missing API key, package not installed, etc.).
+
+## Built-in Engines
+
+| Engine Name | Provider | Requires |
+|---|---|---|
+| `anthropic` | Anthropic Claude SDK | `ANTHROPIC_API_KEY` |
+| `ai-sdk:anthropic` | Claude via Vercel AI SDK | `ANTHROPIC_API_KEY` |
+| `ai-sdk:openai` | OpenAI via Vercel AI SDK | `OPENAI_API_KEY` |
+| `ai-sdk:google` | Google Gemini via Vercel AI SDK | `GOOGLE_GENERATIVE_AI_API_KEY` |
+| `ai-sdk:groq` | Groq LPU via Vercel AI SDK | `GROQ_API_KEY` |
+| `ai-sdk:mistral` | Mistral via Vercel AI SDK | `MISTRAL_API_KEY` |
+| `ai-sdk:cohere` | Cohere via Vercel AI SDK | `COHERE_API_KEY` |
+| `ai-sdk:ollama` | Local Ollama via Vercel AI SDK | None (local) |
+
+## Engine Capabilities
+
+Each engine advertises its capabilities:
+
+| Capability | Anthropic | AI SDK: Anthropic | AI SDK: OpenAI | AI SDK: Google |
+|---|---|---|---|---|
+| `thinking` | ✓ | ✓ | ✗ | ✓ |
+| `promptCaching` | ✓ | ✓ | ✗ | ✗ |
+| `vision` | ✓ | ✓ | ✓ | ✓ |
+| `computerUse` | ✓ | ✗ | ✗ | ✗ |
+| `parallelToolCalls` | ✓ | ✓ | ✓ | ✓ |
+
+## Anthropic-Exclusive Features
+
+When using the `anthropic` engine (or `ai-sdk:anthropic`):
+
+- **Prompt caching** is applied automatically to the system prompt — cutting latency and cost on repeated turns.
+- **Extended thinking** can be enabled via `providerOptions.anthropic.thinking` — the agent reasons longer before responding.
+
+These features are silently ignored when a non-Anthropic engine is active (capability-gated, no breakage).
+
+## Registering a Custom Engine
+
+Register custom engines in a server plugin at startup:
+
+```ts
+// server/plugins/my-engine.ts
+import { registerAgentEngine } from "@agent-native/core/server";
+
+registerAgentEngine({
+  name: "my-engine",
+  label: "My Custom Engine",
+  description: "...",
+  capabilities: {
+    thinking: false,
+    promptCaching: false,
+    vision: false,
+    computerUse: false,
+    parallelToolCalls: true,
+  },
+  defaultModel: "my-model-v1",
+  supportedModels: ["my-model-v1", "my-model-v2"],
+  requiredEnvVars: ["MY_ENGINE_API_KEY"],
+  create: (config) => new MyEngine(config),
+});
+```
+
+After registering, the engine appears in `list-agent-engines` output and can be selected via `set-agent-engine`.
+
+## Env Vars Reference
+
+| Variable | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` | Required for `anthropic` and `ai-sdk:anthropic` engines |
+| `OPENAI_API_KEY` | Required for `ai-sdk:openai` |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Required for `ai-sdk:google` |
+| `GROQ_API_KEY` | Required for `ai-sdk:groq` |
+| `MISTRAL_API_KEY` | Required for `ai-sdk:mistral` |
+| `COHERE_API_KEY` | Required for `ai-sdk:cohere` |
+| `AGENT_ENGINE` | Default engine name (overridden by settings store) |

package/src/templates/default/.agents/skills/real-time-collab/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: real-time-collab
+description: >-
+  How to enable multi-user collaborative editing with Yjs CRDT, TipTap
+  Collaboration extension, live cursors, and agent-driven edits.
+---
+
+# Real-Time Collaboration
+
+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.
+
+## Architecture
+
+```
+User A (TipTap + Collaboration ext)  ←→  Y.XmlFragment  ←→  Server (_collab_docs table)
+User B (TipTap + Collaboration ext)  ←→  Y.XmlFragment  ←→       ↑
+Agent (edit-document action)         ←→  search-replace endpoint ─┘
+```
+
+- **Yjs Y.Doc** stores the document as a `Y.XmlFragment` (ProseMirror node tree)
+- **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment via `ySyncPlugin`
+- **CollaborationCaret extension** renders remote users' cursors with names and colors
+- **Polling** (every 2s) syncs Y.Doc updates and awareness state between clients and server
+- **SQL `_collab_docs` table** persists Yjs state (base64-encoded binary)
+
+## Enabling Collaboration in a Template
+
+### 1. Install dependencies
+
+```bash
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap --filter your-template
+```
+
+### 2. Add Vite optimizeDeps
+
+In `vite.config.ts`:
+```ts
+export default defineConfig({
+  plugins: [reactRouter()],
+  optimizeDeps: {
+    include: [
+      "yjs",
+      "y-protocols/awareness",
+      "@tiptap/extension-collaboration",
+      "@tiptap/extension-collaboration-caret",
+      "@tiptap/y-tiptap",
+    ],
+  },
+});
+```
+
+This prevents Vite from re-bundling TipTap in incompatible ways during dev.
+
+### 3. Add the collab server plugin
+
+Create `server/plugins/collab.ts`:
+```ts
+import { createCollabPlugin } from "@agent-native/core/server";
+export default createCollabPlugin({
+  table: "your_table",
+  contentColumn: "content",
+  idColumn: "id",
+  autoSeed: false, // Client-side seeding on first load
+});
+```
+
+This mounts routes under `/_agent-native/collab/`:
+- `GET /:docId/state` — fetch Y.Doc state
+- `POST /:docId/update` — apply client update
+- `POST /:docId/text` — apply full text (diff-based)
+- `POST /:docId/search-replace` — surgical text find/replace in Y.XmlFragment
+- `POST /:docId/awareness` — sync cursor/presence state
+
+### 4. Use the `useCollaborativeDoc` hook
+
+```ts
+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" },
+});
+```
+
+The hook:
+- Creates a stable `Y.Doc` per docId (never changes identity)
+- Fetches server state and applies it
+- Sends local updates to server
+- Polls for remote updates (every 2s)
+- Tracks active users via awareness
+
+### 5. Add Collaboration extension to TipTap
+
+```ts
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCaret from "@tiptap/extension-collaboration-caret";
+import { Awareness } from "y-protocols/awareness";
+
+// Create awareness locally (must use same y-protocols as the caret extension)
+const awareness = new Awareness(ydoc);
+awareness.setLocalStateField("user", { name, color });
+
+const editor = useEditor({
+  extensions: [
+    StarterKit.configure({ history: false }), // Disable history — Yjs handles undo
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCaret.configure({
+      provider: { awareness },
+      user: { name, color },
+    }),
+    // ... other extensions
+  ],
+  content: initialContent, // Seeds Y.XmlFragment on first load
+});
+```
+
+**Important:** Disable `history` in StarterKit when using Collaboration — Yjs handles undo/redo.
+
+### 6. Seed the Y.XmlFragment
+
+The Collaboration extension does NOT auto-seed from the `content` prop. You must seed manually:
+
+```ts
+useEffect(() => {
+  if (!editor || !ydoc || !content) return;
+  const fragment = ydoc.getXmlFragment("default");
+  if (fragment.length === 0) {
+    editor.commands.setContent(parseContent(content));
+  }
+}, [editor, ydoc, content]);
+```
+
+**Critical:** Guard against saving empty content back to SQL when the editor is in collab mode but hasn't been seeded yet:
+
+```ts
+onUpdate: ({ editor }) => {
+  const md = editor.storage.markdown.getMarkdown();
+  if (!md.trim() && ydoc) return; // Don't save empty during seeding
+  onChange(md);
+}
+```
+
+## Agent Edits via `edit-document`
+
+The `edit-document` action uses search-and-replace:
+```bash
+pnpm action edit-document --id <docId> --find "old text" --replace "new text"
+```
+
+When collab state exists, the action calls the server's `search-replace` endpoint which:
+1. Walks the Y.XmlFragment tree
+2. Finds the text in Y.XmlText nodes
+3. Applies minimal delete/insert operations
+4. Emits a Yjs update via the poll system
+5. Client receives the update → ySyncPlugin applies a targeted ProseMirror transaction → cursor preserved
+
+**Important:** Actions run in a separate process, so they must use the HTTP endpoint (not the collab module directly) to emit updates to the server's poll system.
+
+## Key Modules
+
+| Module | Path | Purpose |
+|--------|------|---------|
+| `@agent-native/core/collab` | `packages/core/src/collab/` | Server-side Yjs management |
+| `useCollaborativeDoc` | `packages/core/src/collab/client.ts` | Client hook |
+| `createCollabPlugin` | `packages/core/src/server/collab-plugin.ts` | Route mounting |
+| `searchAndReplace` | `packages/core/src/collab/ydoc-manager.ts` | Y.XmlFragment text mutation |
+
+## Common Pitfalls
+
+1. **TipTap version mismatch** — All `@tiptap/*` packages must be the same version. The Collaboration extension requires `editor.utils` which was added in v3.22.2.
+
+2. **Empty editor on first load** — The Collaboration extension uses Y.XmlFragment as the source of truth. If the fragment is empty, the editor shows empty. Seed manually (see above).
+
+3. **Data loss from empty saves** — The `onUpdate` handler fires when the editor initializes with an empty Y.XmlFragment. If this empty content is saved to SQL, it overwrites the real content. Always guard against saving empty content in collab mode.
+
+4. **Stale content on document switch** — Use `key={documentId}` on the editor component to force a full remount when switching documents. This ensures the Y.Doc, seeding, and editor state are all fresh.
+
+5. **Separate process for actions** — Actions run via `pnpm action` in a new Node.js process. The in-memory EventEmitter in the action process doesn't reach the dev server's poll system. Use HTTP endpoints for collab operations from actions.
+
+6. **Vite dep optimization** — Adding Yjs-related packages to a template changes Vite's dependency bundling, which can break TipTap's React integration. Always add them to `optimizeDeps.include`.

package/src/templates/default/.agents/skills/security/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: security
+description: >-
+  Secure coding guide for agent-native apps. Covers input validation, SQL
+  injection prevention, XSS, secrets management, auth patterns, data scoping,
+  and A2A security. Read this when generating any code that handles user data.
+---
+
+# Security
+
+The framework provides strong security primitives. Use them — don't reinvent security.
+
+## Input Validation
+
+**Always use `defineAction` with a Zod `schema:`** for every action that accepts user input. The framework validates automatically and returns clear error messages.
+
+```ts
+// SECURE — framework validates before run() is called
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200),
+    content: z.string().optional(),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — { title: string; content?: string }
+  },
+});
+```
+
+The legacy `parameters:` format (plain JSON Schema) has **no runtime validation** — the agent receives whatever the caller sends. Do not use it for new code.
+
+Actions without a `schema:` are unvalidated. This is acceptable for internal/dev scripts but never for user-facing operations.
+
+## SQL Injection Prevention
+
+The framework's `db-query` and `db-exec` tools use **parameterized queries** (`?` placeholders). The database driver handles escaping — user input never touches the SQL string.
+
+```ts
+// WRONG — SQL injection vulnerability
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`)
+await exec(`SELECT * FROM notes WHERE title LIKE '%${search}%'`)
+
+// RIGHT — parameterized queries (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] })
+await exec({ sql: "SELECT * FROM notes WHERE title LIKE ?", args: [`%${search}%`] })
+```
+
+**Drizzle ORM is always safe** — it generates parameterized queries automatically:
+
+```ts
+const notes = await db.select().from(notesTable).where(eq(notesTable.title, title));
+```
+
+**When is SQL injection a risk?**
+- Only when writing raw SQL with string concatenation in server routes or actions
+- Never when using `db-query`/`db-exec` with `args` arrays
+- Never when using Drizzle ORM
+
+## XSS Prevention
+
+React auto-escapes all JSX expressions by default. Trust it.
+
+```tsx
+// SAFE — React escapes the output
+<p>{userInput}</p>
+<span>{comment.text}</span>
+
+// DANGEROUS — bypasses React's escaping
+<div dangerouslySetInnerHTML={{ __html: userInput }} />  // NEVER with user content
+element.innerHTML = userInput;                             // NEVER
+eval(userInput);                                           // NEVER
+document.write(userInput);                                 // NEVER
+new Function(userInput);                                   // NEVER
+```
+
+**For rich text:** Use TipTap (framework dependency) with the Collaboration extension. TipTap sanitizes content through its schema — only allowed node types render.
+
+**For markdown:** Use `react-markdown` (already used in the framework). It parses markdown to React elements without `dangerouslySetInnerHTML`.
+
+**For HTML from external sources:** If you absolutely must render external HTML, use a sanitization library like `dompurify`. But prefer structured data (markdown, TipTap JSON) over raw HTML.
+
+## Secrets Management
+
+| Secret type | Where to store | Why |
+|-------------|---------------|-----|
+| API keys (OpenAI, Stripe, etc.) | `.env` file (gitignored) | Never committed, server-side only |
+| OAuth tokens (Google, GitHub) | `oauth_tokens` store | Per-user, per-provider, server-side |
+| App configuration | `settings` store | OK for non-secret config (themes, preferences) |
+| Session tokens | Framework handles | Automatic via Better Auth |
+
+**Rules:**
+- Never store secrets in `settings`, `application_state`, or source code
+- Never return secrets in action responses — they may appear in agent chat or client UI
+- Never log secrets (tokens, keys, passwords)
+- Never commit `.env` files — they're gitignored by default
+- Access env vars via `process.env` in actions/server code, never send them to the client
+
+## Auth Patterns
+
+### Use `defineAction` (recommended)
+
+Actions defined with `defineAction` are automatically protected by the auth guard. Unauthenticated requests get a 401 response. This is the safest pattern.
+
+```ts
+// Auto-protected — auth guard runs before this code
+export default defineAction({
+  description: "Delete a note",
+  schema: z.object({ id: z.string() }),
+  run: async (args) => {
+    // Only authenticated users reach here
+  },
+});
+```
+
+### Custom `/api/` routes (use sparingly)
+
+If you must create custom routes (file uploads, streaming, webhooks), always check auth:
+
+```ts
+// server/routes/api/upload.ts
+import { getSession } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event);
+  if (!session?.email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+  // ... handle upload with session.email
+});
+```
+
+### CSRF Protection
+
+The framework uses `SameSite=lax` cookies with `httpOnly` flag. This prevents most CSRF attacks. Additional rules:
+- State-changing actions should use POST (the default for `defineAction`)
+- GET actions (`http: { method: "GET" }`) should be read-only
+- Never perform writes in response to GET requests
+
+## Data Scoping
+
+In production, the framework enforces data isolation at the SQL level. Agents and users can only see and modify data they own. This is automatic — you don't write WHERE clauses yourself.
+
+### Per-User Scoping (`owner_email`)
+
+Every table with user-specific data **must** have an `owner_email` text column.
+
+```ts
+import { table, text, integer } from "@agent-native/core/db/schema";
+
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  owner_email: text("owner_email").notNull(), // REQUIRED for user data
+});
+```
+
+**What happens automatically:**
+- `db-query` creates temporary views with `WHERE owner_email = <current user>`
+- `db-exec` INSERT statements get `owner_email` auto-injected
+- `db-exec` UPDATE/DELETE statements are scoped to the current user's rows
+- The current user comes from `AGENT_USER_EMAIL` (set from the auth session)
+
+### Per-Org Scoping (`org_id`)
+
+For multi-user apps where teams share data, add an `org_id` column:
+
+```ts
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  owner_email: text("owner_email").notNull(),
+  org_id: text("org_id").notNull(),
+});
+```
+
+When both columns are present, queries are scoped by **both**: `WHERE owner_email = ? AND org_id = ?`.
+
+### Validation
+
+Run `pnpm action db-check-scoping` to verify all tables have proper ownership columns. Use `--require-org` for multi-org apps.
+
+## A2A Security
+
+### Cross-App Identity
+
+When apps call each other via A2A, they need to verify identity. Set the same `A2A_SECRET` on all apps that need to trust each other:
+
+```bash
+A2A_SECRET=your-shared-secret-at-least-32-chars
+```
+
+**How it works:**
+1. App A signs a JWT with `A2A_SECRET` containing `sub: "steve@builder.io"`
+2. App B receives the call, verifies the JWT signature
+3. App B sets `AGENT_USER_EMAIL` from the verified `sub` claim
+4. Data scoping applies — App B only shows steve's data
+
+Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev, not production).
+
+## Rules for Agents
+
+1. **Every new table with user data must have `owner_email`.** No exceptions.
+2. **Always use `defineAction` with a Zod `schema:`** for input validation on user-facing actions.
+3. **Never concatenate user input into SQL** — use parameterized queries or Drizzle ORM.
+4. **Never use `dangerouslySetInnerHTML`** or `innerHTML` with user-controlled content.
+5. **Never store secrets outside `.env` or `oauth_tokens`** — no settings, no source code, no responses.
+6. **Never bypass scoping** — don't raw-query tables without going through `db-query`/`db-exec`.
+7. **Never create unprotected routes that modify data** — use `defineAction` or check `getSession()`.
+8. **Don't hardcode emails** — use `AGENT_USER_EMAIL` environment variable.
+9. **Don't expose user data in application state** — it's per-session, not per-user. Use SQL tables with `owner_email`.