@agent-native/core 0.4.5 → 0.6.1

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

@@ -0,0 +1,142 @@
+---
+name: actions
+description: >-
+  How to create and run agent-callable actions in actions/. Use when creating
+  a new action, adding an API integration, implementing a complex agent
+  operation, or running pnpm action commands.
+---
+
+# Agent Actions
+
+## Rule
+
+Complex operations the agent needs to perform are implemented as actions in `actions/`. The agent runs them via `pnpm action <name>`.
+
+## Why
+
+Actions give the agent callable tools with structured input/output. They keep the agent's chat context clean (no massive code blocks), they're reusable, and they can be tested independently.
+
+## How to Create an Action
+
+Create `actions/my-action.ts`:
+
+```ts
+import fs from "fs";
+import { parseArgs, loadEnv, fail, agentChat } from "@agent-native/core";
+
+export default async function myAction(args: string[]) {
+  loadEnv();
+
+  const parsed = parseArgs(args);
+  const input = parsed.input;
+  if (!input) fail("--input is required");
+
+  const outputPath = parsed.output ?? "data/result.json";
+  const raw = fs.readFileSync(input, "utf-8");
+  const data = JSON.parse(raw) as unknown;
+
+  fs.writeFileSync(outputPath, JSON.stringify(data, null, 2));
+  agentChat.submit(`Processed ${input}, result saved to ${outputPath}`);
+}
+```
+
+### 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",
+  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
+pnpm action my-action --input data/source.json --output data/result.json
+```
+
+## Action Dispatcher
+
+The default template uses core's `runScript()` in `actions/run.ts`:
+
+```ts
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+This is the canonical approach for new apps. Action names must be lowercase with hyphens only (e.g., `my-action`).
+
+## 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>`.
+- **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.
+- **Use `agentChat.submit()`** to report results or errors back to the agent chat.
+- **Import from `@agent-native/core`** -- Don't redefine `parseArgs()` or other utilities locally.
+
+## Common Patterns
+
+**API integration action** (e.g., image generation):
+
+```ts
+import fs from "fs";
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function generateImage(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  const prompt = parsed.prompt;
+  if (!prompt) fail("--prompt is required");
+
+  const outputPath = parsed.output ?? "data/generated-image.png";
+  const imageUrl = await callImageAPI(prompt);
+  const buffer = await fetch(imageUrl).then((r) => r.arrayBuffer());
+  fs.writeFileSync(outputPath, Buffer.from(buffer));
+}
+```
+
+**Data processing action:**
+
+```ts
+import fs from "fs";
+import { parseArgs, fail } from "@agent-native/core";
+
+export default async function transform(args: string[]) {
+  const parsed = parseArgs(args);
+  const source = parsed.source;
+  if (!source) fail("--source is required");
+
+  const data = JSON.parse(fs.readFileSync(source, "utf-8")) as unknown[];
+  const result = data.map(transformItem);
+  fs.writeFileSync(source, JSON.stringify(result, null, 2));
+}
+```
+
+## Troubleshooting
+
+- **Action not found** -- Check that the filename matches the command name exactly. `pnpm action foo-bar` looks for `actions/foo-bar.ts`.
+- **Args not parsing** -- Ensure args use `--key value` or `--key=value` format. Boolean flags use `--flag` (sets value to `"true"`).
+- **Action runs but UI doesn't update** -- Make sure results are written to the database so db sync polling picks them up.
+
+## Related Skills
+
+- **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/create-skill/SKILL.md

@@ -148,7 +148,7 @@ description: >-
 
 - **Inline LLM calls** — Skills must not call LLMs directly (violates Rule 2)
 - **Database patterns** — Skills must not introduce databases (violates Rule 1)
-- **Ignoring SSE** — If a skill creates data files, mention wiring up `useFileWatcher`
+- **Ignoring db sync** — If a skill creates data, mention wiring up `useDbSync`
 - **Vague descriptions** — "Helps with development" won't trigger. Be specific about _when_.
 - **Pure documentation** — Skills should guide action, not just explain concepts
 

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

@@ -84,7 +84,7 @@ Scripts may call external APIs (image generation, search, etc.) — but the AI r
 
 ## Related Skills
 
-- **scripts** — The agent invokes scripts via `pnpm script <name>` to perform complex operations
+- **scripts** — The agent invokes scripts via `pnpm action <name>` to perform complex operations
 - **self-modifying-code** — The agent operates through the chat bridge to make code changes
 - **storing-data** — The agent writes results to the database after processing requests
 - **real-time-sync** — The UI updates automatically when the agent writes to the database

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/real-time-sync/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: real-time-sync
+description: >-
+  How to keep the UI in sync with agent changes via polling. Use when wiring
+  query invalidation for new data models, debugging UI not updating, or
+  understanding jitter prevention.
+---
+
+# Real-Time Sync (Polling)
+
+## Rule
+
+The UI stays in sync with agent/script changes through database polling. When the agent writes to the database, the UI detects the change and updates automatically — no manual refresh needed.
+
+## Why
+
+The agent modifies data in SQL, but the UI runs in the browser. Polling bridges this gap: every database write increments a version counter, the `useDbSync()` hook polls for version changes, and React Query invalidates the relevant caches. This is what makes database writes feel real-time.
+
+## How It Works
+
+1. **Server** increments a version counter on every database write. The `/_agent-native/poll` endpoint returns the current version and any events since the last poll.
+
+2. **Client** polls for changes and invalidates React Query caches:
+
+   ```ts
+   import { useDbSync } from "@agent-native/core";
+   useDbSync({ queryClient, queryKeys: ["items", "settings"] });
+   ```
+
+3. When the agent writes to the database, the version increments, polling detects it, and React Query refetches the affected queries.
+
+## Don't
+
+- Don't create manual polling loops — `useDbSync()` handles it (polls every 2 seconds by default)
+- Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+
+## Query Key Mapping
+
+By default, `useDbSync` invalidates all listed query keys on every change. For apps with multiple data models, this causes unnecessary refetches. Use event-based filtering via the `onEvent` callback:
+
+```ts
+useDbSync({
+  queryClient,
+  queryKeys: [], // don't auto-invalidate everything
+  onEvent: (data) => {
+    if (data.source === "settings") {
+      queryClient.invalidateQueries({ queryKey: ["settings"] });
+    } else if (data.source === "app-state") {
+      queryClient.invalidateQueries({ queryKey: ["navigate-command"] });
+    } else {
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+    }
+  },
+});
+```
+
+To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
+
+```ts
+useQuery({
+  queryKey: ["items"],
+  queryFn: fetchItems,
+  staleTime: 2000, // don't refetch within 2 seconds
+});
+```
+
+## Troubleshooting
+
+| Symptom                            | Check                                                                                                          |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Are the `queryKeys` matching your `useQuery` keys?       |
+| Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
+| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries and use event-based filtering.                        |
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`, `deleteAppState`), the write is automatically tagged with `requestSource: "agent"`. This prevents the UI from overwriting active user edits when it receives the change event.
+
+### How it works
+
+1. **Agent writes** are tagged: the script helpers in `@agent-native/core/application-state` pass `{ requestSource: "agent" }` to the store.
+2. **UI writes** are tagged: templates send a per-tab ID via the `X-Request-Source` header on PUT/DELETE requests to application-state endpoints.
+3. **Polling filters**: `useDbSync()` accepts an `ignoreSource` option. The UI passes its own tab ID so it ignores events from its own writes — but still picks up events from agents, other tabs, and scripts.
+
+### Template setup
+
+```ts
+// app/lib/tab-id.ts
+export const TAB_ID = `tab-${Math.random().toString(36).slice(2, 8)}`;
+
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings"],
+  ignoreSource: TAB_ID,
+});
+```
+
+The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Source` header when writing navigation state, so the tab that wrote the state does not refetch it.
+
+### Why this matters
+
+Without jitter prevention, a cycle occurs: the UI writes state, polling detects the change, the UI refetches and re-renders, potentially overwriting what the user is actively editing. With `ignoreSource`, the UI only reacts to changes from other sources (agent scripts, other browser tabs, other users).
+
+## Related Skills
+
+- **storing-data** — Application-state and settings are the data stores that sync via polling
+- **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
+- **scripts** — Script outputs written to the database trigger poll events
+- **self-modifying-code** — Agent code edits trigger poll events; rapid edits can cause event storms