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

package/docs/content/resources.md

@@ -0,0 +1,277 @@
+---
+title: "Workspace Resources"
+description: "SQL-backed workspace files for notes, skills, custom agents, scheduled tasks, and instructions."
+---
+
+# Workspace Resources
+
+The **Workspace** tab is where you and the agent share persistent files — notes, instructions, skills, custom agents, and scheduled jobs. Files live in the database (not the filesystem), so they persist across sessions, work in serverless/edge deploys, and can be edited from both the UI and the agent.
+
+## TL;DR {#tldr}
+
+- Open the **Workspace** tab in the agent sidebar.
+- Create files with the `+` menu. Upload with the upload button. Edit inline (visual or code view).
+- **Personal** is just you. **Shared** is your team/org.
+- The agent can read, write, and rename any of these files as part of a conversation.
+- Special files the agent always reads: `AGENTS.md` (team rules) and `learnings.md` (per-user).
+
+## What goes in here? {#what-goes-in-here}
+
+| File / path               | What it's for                                                                                 |
+| ------------------------- | --------------------------------------------------------------------------------------------- |
+| `AGENTS.md` (Shared)      | Team instructions the agent reads every turn — tone, rules, domain context, skill references. |
+| `learnings.md` (Personal) | Corrections and preferences the agent records per user so it doesn't repeat mistakes.         |
+| `skills/<name>.md`        | Focused domain guidance the agent pulls in on demand (invoked with `/` slash commands).       |
+| `agents/<name>.md`        | Custom sub-agent profiles the agent can delegate to (invoked with `@` mentions).              |
+| `agents/<name>.json`      | A2A manifests for connected remote agents.                                                    |
+| `jobs/<name>.md`          | Scheduled tasks that run on a cron (see the recurring-jobs docs).                             |
+| Anything else             | Notes, prompts, config, dataset snippets — any text file.                                     |
+
+## Overview {#overview}
+
+Every agent-native app has a built-in resource system. Resources are SQL-backed files that persist across sessions and deployments. Unlike code files, resources live in the database — not the filesystem — so they work in serverless environments, edge runtimes, and production deploys without any filesystem dependency.
+
+Resources have two scopes:
+
+- **Personal** — scoped to a single user (their email). Good for preferences, notes, and per-user context.
+- **Shared** — visible to all users. Good for team instructions, skills, and shared config.
+
+## Workspace Panel {#workspace-panel}
+
+The agent panel includes a **Workspace** tab alongside Chat and CLI. This panel lets users browse, create, edit, and delete workspace resources. It displays a tree view of all resources organized by folder path.
+
+Resources can be any text file — Markdown, JSON, YAML, plain text. The panel includes an inline editor for viewing and modifying resource content directly.
+
+The `+` menu in Workspace supports typed creation flows for:
+
+- **Files** — arbitrary resources
+- **Skills** — reusable instruction files under `skills/`
+- **Agents** — custom sub-agent profiles under `agents/*.md`
+- **Scheduled Tasks** — recurring jobs under `jobs/`
+
+Workspace resources come in two scopes:
+
+- **Personal** — visible only to the current user
+- **Shared** — visible across the team/org
+
+Click the `?` icon in the Workspace toolbar to jump back to these docs at any time.
+
+## Getting Started: a 1-minute walkthrough {#getting-started}
+
+Change how the agent behaves, in 60 seconds.
+
+1. Open the **Workspace** tab → **Shared** → `AGENTS.md` (create it with `+` → **File** if missing).
+2. Add one rule, e.g.:
+
+   ```markdown
+   ## Tone
+
+   Be concise. Lead with the answer.
+   ```
+
+3. Save, switch to **Chat**, ask anything — the agent follows the new rule immediately.
+
+**Next steps, when you want them:**
+
+- **Skills** (`+` → **Skill**) — focused how-to files invoked in chat with `/skill-name`.
+- **Agents** (`+` → **Agent**) — reusable sub-agent personas invoked with `@agent-name`.
+- **Scheduled Tasks** (`+` → **Scheduled Task**) — prompts that run on a cron.
+- **learnings.md** — your Personal file the agent auto-updates whenever you correct it.
+
+## How the Agent Uses Resources {#how-the-agent-uses-resources}
+
+The agent has built-in tools for managing resources: `resource-list`, `resource-read`, `resource-write`, and `resource-delete`. These are available in both dev and production modes.
+
+At the start of every conversation, the agent automatically reads:
+
+### AGENTS.md {#agents-md}
+
+A shared resource seeded by default. It contains custom instructions, preferences, and skill references. Edit this to change how the agent behaves for all users — tone, rules, domain context, and which skills to use.
+
+```text
+# Agent Instructions
+
+## Tone
+Be concise. Lead with the answer.
+
+## Code style
+- Use TypeScript, never JavaScript
+- Prefer named exports
+
+## Skills
+| Skill | Path | Description |
+|-------|------|-------------|
+| data-analysis | `skills/data-analysis.md` | BigQuery and data workflows |
+```
+
+### learnings.md {#learnings-md}
+
+A personal resource where the agent records corrections, preferences, and patterns it learns from each user. When the agent makes a mistake and the user corrects it, the agent updates `learnings.md` so it doesn't repeat the error.
+
+## Skills {#skills}
+
+Skills are Markdown resource files that give the agent deep domain knowledge for specific tasks. They live under the `skills/` path prefix in resources (e.g. `skills/data-analysis.md`, `skills/code-review.md`).
+
+When the agent encounters a task that matches a skill, it reads the skill file and follows its guidance. Skills referenced in `AGENTS.md` are discovered automatically.
+
+### Creating Skills {#creating-skills}
+
+There are two ways to add skills:
+
+1. **Via Workspace tab** — Create a new resource with a path like `skills/my-skill.md`. This works in both dev and production.
+2. **Via code (dev only)** — Add a Markdown file to `.agents/skills/` in your project. These are available when the app runs in dev mode.
+
+## Custom Agents {#custom-agents}
+
+Custom agents are reusable local sub-agent profiles stored as Markdown resources under `agents/*.md`.
+
+Use them when you want a focused delegate with its own:
+
+- name
+- description
+- model preference
+- instruction set
+
+Unlike skills, custom agents are not passive guidance. They are operational personas the main agent can invoke through `@` mentions or by selecting them during sub-agent spawning.
+
+### Agent format {#agent-format}
+
+Custom agents use YAML frontmatter plus Markdown instructions:
+
+```markdown
+---
+name: Design
+description: >-
+  Reviews layouts, interaction patterns, and product UX decisions.
+model: inherit
+tools: inherit
+delegate-default: false
+---
+
+# Role
+
+You are a focused design agent.
+
+## Responsibilities
+
+- Review layouts and interaction flows
+- Suggest stronger visual direction
+- Be concise and opinionated
+```
+
+Recommended conventions:
+
+- Store custom agents at `agents/<slug>.md`
+- Use `model: inherit` unless the profile clearly needs a different model
+- Keep `tools: inherit` for now; the field is reserved for future tool policies
+
+### Remote agents vs custom agents {#remote-vs-custom-agents}
+
+There are two agent types in Workspace:
+
+- **Custom agents** — local profiles in `agents/*.md`, executed inside the current app/runtime
+- **Connected agents** — remote A2A peers described by manifests in `agents/*.json`
+
+Use custom agents for delegation within one app. Use connected agents when you need to call another app over A2A.
+
+### Skill Format {#skill-format}
+
+Skills are Markdown files with optional YAML frontmatter for metadata:
+
+````text
+---
+name: data-analysis
+description: BigQuery queries, data transforms, and visualization
+---
+
+# Data Analysis
+
+## When to use
+Use this skill when the user asks about data, queries, or analytics.
+
+## Rules
+- Always validate SQL before executing
+- Prefer CTEs over subqueries
+- Include LIMIT on exploratory queries
+
+## Patterns
+```sql
+-- Standard BigQuery date filter
+WHERE DATE(created_at) BETWEEN @start_date AND @end_date
+````
+
+````
+
+## @ Tagging {#at-tagging}
+
+Type `@` in the chat input to reference workspace items. A dropdown appears at the cursor showing matching agents and files. Use arrow keys to navigate and Enter to select. The selected item appears as an inline chip in the input.
+
+When you send a message:
+
+- **Files/resources** are passed as references the agent can read
+- **Custom agents** run locally with their profile instructions
+- **Connected agents** are called over A2A
+
+What shows up depends on the mode:
+
+- **Dev mode** — Codebase files, workspace resources, custom agents, and connected agents
+- **Production mode** — Workspace resources, custom agents, and connected agents
+
+## / Slash Commands {#slash-commands}
+
+Type `/` at the start of a line to invoke a skill. A dropdown shows available skills with their names and descriptions. Selecting a skill adds it as an inline chip, and its content is included as context when the message is sent.
+
+What shows up depends on the mode:
+
+- **Dev mode** — Skills from `.agents/skills/` (codebase) and skills from resources
+- **Production mode** — Skills from resources only
+
+If no skills are configured, the dropdown shows a hint with a link to these docs.
+
+## Dev vs Production Mode {#dev-vs-prod}
+
+The resource system works identically in both modes. The difference is what additional sources are available for `@` tagging and `/` commands:
+
+| Feature | Dev Mode | Production |
+|---------|----------|------------|
+| @ tagging | Codebase files + workspace resources + custom agents + connected agents | Workspace resources + custom agents + connected agents |
+| / slash commands | .agents/skills/ + resource skills | Resource skills only |
+| Agent file access | Filesystem + resources | Resources only |
+| Workspace panel | Full access | Full access |
+| AGENTS.md / learnings.md | Available | Available |
+
+## Resource API {#resource-api}
+
+Resources can be managed from server code, actions, or the REST API.
+
+### Server API {#server-api}
+
+REST endpoints mounted automatically:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/_agent-native/resources?scope=all` | List resources |
+| `GET` | `/_agent-native/resources/tree?scope=all` | Get folder tree |
+| `POST` | `/_agent-native/resources` | Create a resource |
+| `GET` | `/_agent-native/resources/:id` | Get resource with content |
+| `PUT` | `/_agent-native/resources/:id` | Update a resource |
+| `DELETE` | `/_agent-native/resources/:id` | Delete a resource |
+| `POST` | `/_agent-native/resources/upload` | Upload a file as resource |
+
+### Action API {#script-api}
+
+The agent uses these built-in actions. You can also call them from your own actions:
+
+```bash
+# List all resources
+pnpm action resource-list --scope all
+
+# Read a resource
+pnpm action resource-read --path "skills/my-skill.md"
+
+# Write a resource
+pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."
+
+# Delete a resource
+pnpm action resource-delete --path "notes/old.md"
+````

package/docs/content/security.md

@@ -0,0 +1,158 @@
+---
+title: "Security"
+description: "Security model for agent-native apps: input validation, SQL injection prevention, XSS, data scoping, secrets management, and auth patterns."
+---
+
+# Security
+
+Agent-native apps are designed to be secure by default. The framework provides automatic protections at multiple layers — you get SQL-level data isolation, parameterized queries, input validation, and authentication out of the box.
+
+## Security by Design {#secure-by-design}
+
+The framework architecture prevents common vulnerabilities when you use the standard patterns:
+
+| Vulnerability   | Framework Protection                                            |
+| --------------- | --------------------------------------------------------------- |
+| SQL injection   | Parameterized queries in `db-query`/`db-exec` and Drizzle ORM   |
+| XSS             | React auto-escapes JSX; TipTap sanitizes rich text              |
+| Data leaks      | SQL-level scoping via temporary views (`owner_email`, `org_id`) |
+| Auth bypass     | Auth guard auto-protects all `defineAction` endpoints           |
+| Input injection | Zod schema validation in `defineAction`                         |
+| CSRF            | `SameSite=lax` + `httpOnly` cookies                             |
+| Secret exposure | `.env` files gitignored; OAuth tokens in dedicated store        |
+
+## Input Validation {#input-validation}
+
+Use `defineAction` with a Zod `schema:` for every action. The framework validates input automatically before your code runs:
+
+```typescript
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200).describe("Note title"),
+    content: z.string().optional().describe("Note body"),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — invalid input never reaches here
+  },
+});
+```
+
+Invalid input returns clear error messages (400 for HTTP, structured error for agent calls). The legacy `parameters:` format provides no runtime validation.
+
+## SQL Injection Prevention {#sql-injection}
+
+The framework's `db-query` and `db-exec` tools use parameterized queries. User input is passed as arguments, never interpolated into the SQL string:
+
+```typescript
+// SAFE — parameterized query (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] });
+
+// SAFE — Drizzle ORM (always generates parameterized queries)
+await db.insert(notes).values({ title, ownerEmail: email });
+
+// DANGEROUS — string concatenation (never do this)
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`);
+```
+
+## XSS Prevention {#xss}
+
+React auto-escapes all JSX expressions. Additional guidelines:
+
+- Never use `dangerouslySetInnerHTML` with user-controlled content
+- Never use `innerHTML`, `eval()`, or `document.write()`
+- For rich text editing, use TipTap (framework dependency) — it sanitizes through its schema
+- For rendering markdown, use `react-markdown` — it converts to React elements safely
+
+## Data Scoping {#data-scoping}
+
+In production, the framework automatically restricts agent SQL queries to the current user's data. This is enforced at the SQL level — agents cannot bypass it.
+
+### Per-User Scoping (`owner_email`)
+
+Every table with user-specific data **must** have an `owner_email` text column:
+
+```typescript
+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
+});
+```
+
+The framework creates temporary SQL views that filter queries automatically:
+
+```sql
+CREATE TEMPORARY VIEW "notes" AS
+  SELECT * FROM main."notes"
+  WHERE "owner_email" = 'alice@example.com';
+```
+
+INSERT statements get `owner_email` auto-injected when the column isn't already present.
+
+### Per-Org Scoping (`org_id`)
+
+For multi-user apps where teams share data, add an `org_id` column. When both columns are present, queries are scoped by both: `WHERE owner_email = ? AND org_id = ?`.
+
+### Validation
+
+```bash
+pnpm action db-check-scoping           # Check all tables have owner_email
+pnpm action db-check-scoping --require-org  # Also require org_id
+```
+
+## Secrets Management {#secrets}
+
+| Secret type                     | Where to store                               |
+| ------------------------------- | -------------------------------------------- |
+| API keys (OpenAI, Stripe, etc.) | `.env` file (gitignored, server-side only)   |
+| OAuth tokens (Google, GitHub)   | `oauth_tokens` store via `saveOAuthTokens()` |
+| Session tokens                  | Automatic (Better Auth handles this)         |
+
+Never store secrets in `settings`, `application_state`, source code, or action responses.
+
+## Authentication {#auth}
+
+Auth is automatic. See the [Authentication](/docs/authentication) docs for the full setup.
+
+**Key points for security:**
+
+- `defineAction` endpoints are auto-protected by the auth guard
+- Custom `/api/` routes must call `getSession(event)` and check the result
+- State-changing operations should use POST (the default for actions)
+- `SameSite=lax` + `httpOnly` cookies prevent most CSRF attacks
+
+## A2A Identity Verification {#a2a-identity}
+
+When apps call each other via the A2A protocol, they verify identity using JWT tokens signed with a shared secret:
+
+```bash
+A2A_SECRET=your-shared-secret-at-least-32-chars
+```
+
+1. App A signs a JWT containing `sub: "steve@example.com"`
+2. App B verifies the JWT signature with the same secret
+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).
+
+## Production Checklist {#production-checklist}
+
+- [ ] Every user-facing table has `owner_email`
+- [ ] Multi-user tables also have `org_id`
+- [ ] All actions use `defineAction` with Zod `schema:`
+- [ ] No `dangerouslySetInnerHTML` with user content
+- [ ] No string-concatenated SQL
+- [ ] API keys are in `.env` only (not in source code or settings)
+- [ ] `BETTER_AUTH_SECRET` is set to a random 32+ character string
+- [ ] `A2A_SECRET` is set on all apps that call each other
+- [ ] `AUTH_MODE` is **not** set to `local`
+- [ ] `pnpm action db-check-scoping` passes
+- [ ] Tested with two user accounts to verify data isolation

package/docs/content/server.md

@@ -0,0 +1,200 @@
+---
+title: "Server"
+description: "Nitro server layer with file-based routing, server plugins, SSE handlers, and production agent configuration."
+---
+
+# Server
+
+Agent-native apps use [Nitro](https://nitro.build) for the server layer. Nitro is included automatically via the `defineConfig()` Vite plugin — you get file-based API routing, server plugins, and deploy-anywhere presets out of the box.
+
+## File-Based Routing {#file-based-routing}
+
+API routes live in `server/routes/`. Nitro auto-discovers them based on file name and path:
+
+```text
+server/routes/
+  api/
+    hello.get.ts          → GET  /api/hello
+    items/
+      index.get.ts        → GET  /api/items
+      index.post.ts       → POST /api/items
+      [id].get.ts         → GET  /api/items/:id
+      [id].delete.ts      → DELETE /api/items/:id
+      [id]/
+        archive.patch.ts  → PATCH /api/items/:id/archive
+```
+
+Each route file exports a default `defineEventHandler`:
+
+```ts
+// server/routes/api/items/index.get.ts
+import { defineEventHandler } from "h3";
+import fs from "fs/promises";
+
+export default defineEventHandler(async () => {
+  const files = await fs.readdir("./data/items");
+  const items = await Promise.all(
+    files
+      .filter((f) => f.endsWith(".json"))
+      .map(async (f) =>
+        JSON.parse(await fs.readFile(`./data/items/${f}`, "utf-8")),
+      ),
+  );
+  return items;
+});
+```
+
+### Route naming conventions {#route-naming-conventions}
+
+| File name pattern  | HTTP method | Example path               |
+| ------------------ | ----------- | -------------------------- |
+| `index.get.ts`     | GET         | `/api/items`               |
+| `index.post.ts`    | POST        | `/api/items`               |
+| `[id].get.ts`      | GET         | `/api/items/:id`           |
+| `[id].patch.ts`    | PATCH       | `/api/items/:id`           |
+| `[id].delete.ts`   | DELETE      | `/api/items/:id`           |
+| `[...slug].get.ts` | GET         | `/api/items/* (catch-all)` |
+
+### Accessing route parameters {#accessing-route-parameters}
+
+```ts
+import { defineEventHandler, getRouterParam, readBody, getQuery } from "h3";
+
+// GET /api/items/:id
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, "id");
+  const { filter } = getQuery(event);
+  // ...
+});
+```
+
+## Server Plugins {#server-plugins}
+
+Cross-cutting concerns — file watchers, file sync, scheduled jobs, auth — go in `server/plugins/`. Nitro runs these at startup before serving requests:
+
+```ts
+// server/plugins/file-sync.ts
+import { defineNitroPlugin } from "@agent-native/core";
+import { createFileSync } from "@agent-native/core/adapters/sync";
+
+export default defineNitroPlugin(async () => {
+  const result = await createFileSync({ contentRoot: "./data" });
+  if (result.status === "error") {
+    console.warn(`[app] File sync failed: ${result.reason}`);
+  }
+});
+```
+
+## Shared State Between Plugins and Routes {#shared-state}
+
+Use a shared module in `server/lib/` to pass state from plugins to route handlers:
+
+```ts
+// server/lib/watcher.ts
+import { createFileWatcher } from "@agent-native/core";
+import type { SSEHandlerOptions } from "@agent-native/core";
+
+export const watcher = createFileWatcher("./data");
+export const sseExtraEmitters: NonNullable<SSEHandlerOptions["extraEmitters"]> =
+  [];
+
+export let syncResult: any = { status: "disabled" };
+export function setSyncResult(result: any) {
+  syncResult = result;
+  if (result.status === "ready" && result.sseEmitter) {
+    sseExtraEmitters.push(result.sseEmitter);
+  }
+}
+```
+
+The plugin populates the state at startup; route handlers read it at request time.
+
+## createFileWatcher(dir, options?) {#createfilewatcher}
+
+Creates a chokidar file watcher for real-time file change detection:
+
+```ts
+import { createFileWatcher } from "@agent-native/core";
+
+const watcher = createFileWatcher("./data");
+// watcher emits "all" events: (eventName, filePath)
+```
+
+### Options {#filewatcher-options}
+
+| Option        | Type    | Description                                       |
+| ------------- | ------- | ------------------------------------------------- |
+| `ignored`     | any     | Glob patterns or regex to ignore                  |
+| `emitInitial` | boolean | Emit events for initial file scan. Default: false |
+
+## createSSEHandler(watcher, options?) {#createssehandler}
+
+Creates an H3 event handler that streams file changes as Server-Sent Events:
+
+```ts
+// server/routes/_agent-native/events.get.ts
+import { createSSEHandler } from "@agent-native/core";
+import { watcher, sseExtraEmitters } from "../../lib/watcher.js";
+
+export default createSSEHandler(watcher, {
+  extraEmitters: sseExtraEmitters,
+  contentRoot: "./data",
+});
+```
+
+Each SSE message is JSON: `{ "type": "change", "path": "data/file.json" }`
+
+### Options {#ssehandler-options}
+
+| Option        | Type                        | Description                                       |
+| ------------- | --------------------------- | ------------------------------------------------- |
+| extraEmitters | `Array<{ emitter, event }>` | Additional EventEmitters to stream                |
+| contentRoot   | string                      | Root directory used to relativize paths in events |
+
+## createServer(options?) {#createserver}
+
+Optional helper that creates a pre-configured H3 app with CORS middleware and a health-check route. Returns `{ app, router }`. Useful for programmatic route registration when file-based routing doesn't fit:
+
+```ts
+import { createServer } from "@agent-native/core";
+import { defineEventHandler } from "h3";
+
+const { app, router } = createServer();
+router.get("/api/items", defineEventHandler(listItems));
+```
+
+## mountAuthMiddleware(app, accessToken) {#mountauthmiddleware}
+
+Mounts session-cookie authentication onto an H3 app. Serves a login page for unauthenticated browser requests and returns 401 for unauthenticated API requests.
+
+```ts
+import { mountAuthMiddleware } from "@agent-native/core";
+
+mountAuthMiddleware(app, process.env.ACCESS_TOKEN!);
+```
+
+Adds two routes automatically: `POST /api/auth/login` and `POST /api/auth/logout`.
+
+## createProductionAgentHandler(options) {#createproductionagenthandler}
+
+Creates an H3 SSE handler at `POST /_agent-native/agent-chat` that runs an agentic tool loop using Claude. Each script's `run()` function is registered as a tool the agent can invoke.
+
+```ts
+import { createProductionAgentHandler } from "@agent-native/core";
+import { scripts } from "./scripts/registry.js";
+import { readFileSync } from "fs";
+
+const agent = createProductionAgentHandler({
+  scripts,
+  systemPrompt: readFileSync("agents/system-prompt.md", "utf-8"),
+});
+```
+
+### Options {#agent-handler-options}
+
+| Option         | Type                          | Description                                       |
+| -------------- | ----------------------------- | ------------------------------------------------- |
+| `scripts`      | `Record<string, ScriptEntry>` | Map of script name → { tool, run } entries        |
+| `systemPrompt` | string                        | System prompt for the embedded agent              |
+| `apiKey`       | string                        | Anthropic API key. Default: ANTHROPIC_API_KEY env |
+| `model`        | string                        | Model to use. Default: claude-sonnet-4-6          |