@agent-native/core 0.2.7 → 0.3.1

package/package.json

@@ -1,125 +1,127 @@
-{
-  "name": "@agent-native/core",
-  "version": "0.2.7",
-  "type": "module",
-  "description": "Framework for agent-native application development — where AI agents and UI share state via files",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/BuilderIO/agent-native",
-    "directory": "packages/core"
-  },
-  "bin": {
-    "agent-native": "dist/cli/index.js"
-  },
-  "exports": {
-    ".": {
-      "browser": "./dist/index.browser.js",
-      "default": "./dist/index.js"
-    },
-    "./vite": "./dist/vite/index.js",
-    "./server": "./dist/server/index.js",
-    "./client": "./dist/client/index.js",
-    "./shared": "./dist/shared/index.js",
-    "./scripts": "./dist/scripts/index.js",
-    "./adapters/sync": "./dist/adapters/sync/index.js",
-    "./adapters/firestore": "./dist/adapters/firestore/index.js",
-    "./adapters/supabase": "./dist/adapters/supabase/index.js",
-    "./adapters/neon": "./dist/adapters/neon/index.js",
-    "./tailwind": "./dist/tailwind.preset.js",
-    "./tsconfig.base.json": "./tsconfig.base.json"
-  },
-  "files": [
-    "dist",
-    "tsconfig.base.json",
-    "src/templates"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest --run",
-    "prepack": "cp ../../README.md ./README.md",
-    "prepublishOnly": "npm run build",
-    "release": "npm version patch && npm publish --access public"
-  },
-  "dependencies": {
-    "chokidar": "^4.0.0",
-    "clsx": "^2.1.1",
-    "dotenv": "^17.2.1",
-    "minimatch": "^10.0.0",
-    "tailwind-merge": "^2.6.0"
-  },
-  "peerDependencies": {
-    "@supabase/supabase-js": ">=2",
-    "@neondatabase/serverless": ">=0.9",
-    "@tanstack/react-query": ">=5",
-    "@vitejs/plugin-react-swc": ">=4",
-    "autoprefixer": ">=10",
-    "cors": ">=2",
-    "express": ">=5",
-    "postcss": ">=8",
-    "react": ">=18",
-    "react-dom": ">=18",
-    "tailwindcss": ">=3",
-    "tailwindcss-animate": ">=1",
-    "typescript": ">=5",
-    "vite": ">=7"
-  },
-  "peerDependenciesMeta": {
-    "@tanstack/react-query": {
-      "optional": true
-    },
-    "tailwindcss": {
-      "optional": true
-    },
-    "tailwindcss-animate": {
-      "optional": true
-    },
-    "autoprefixer": {
-      "optional": true
-    },
-    "postcss": {
-      "optional": true
-    },
-    "cors": {
-      "optional": true
-    },
-    "express": {
-      "optional": true
-    },
-    "@vitejs/plugin-react-swc": {
-      "optional": true
-    },
-    "vite": {
-      "optional": true
-    },
-    "@supabase/supabase-js": {
-      "optional": true
-    },
-    "@neondatabase/serverless": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@tanstack/react-query": "^5.84.2",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.3",
-    "@types/node": "^24.2.1",
-    "@types/react": "^18.3.23",
-    "@vitejs/plugin-react-swc": "^4.0.0",
-    "autoprefixer": "^10.4.21",
-    "cors": "^2.8.5",
-    "express": "^5.1.0",
-    "@neondatabase/serverless": "^1.0.0",
-    "@supabase/supabase-js": "^2.49.0",
-    "firebase-admin": "^13.0.0",
-    "postcss": "^8.5.6",
-    "react": "^18.3.1",
-    "tailwindcss": "^3.4.17",
-    "tailwindcss-animate": "^1.0.7",
-    "typescript": "^5.9.2",
-    "vite": "^8.0.0",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "@agent-native/core",
+  "version": "0.3.1",
+  "type": "module",
+  "description": "Framework for agent-native application development — where AI agents and UI share state via files",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BuilderIO/agent-native",
+    "directory": "packages/core"
+  },
+  "bin": {
+    "agent-native": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "browser": "./dist/index.browser.js",
+      "default": "./dist/index.js"
+    },
+    "./vite": "./dist/vite/index.js",
+    "./server": "./dist/server/index.js",
+    "./client": "./dist/client/index.js",
+    "./shared": "./dist/shared/index.js",
+    "./scripts": "./dist/scripts/index.js",
+    "./adapters/sync": "./dist/adapters/sync/index.js",
+    "./adapters/firestore": "./dist/adapters/firestore/index.js",
+    "./adapters/supabase": "./dist/adapters/supabase/index.js",
+    "./adapters/neon": "./dist/adapters/neon/index.js",
+    "./adapters/cli": "./dist/adapters/cli/index.js",
+    "./a2a": "./dist/a2a/index.js",
+    "./tailwind": "./dist/tailwind.preset.js",
+    "./tsconfig.base.json": "./tsconfig.base.json"
+  },
+  "files": [
+    "dist",
+    "tsconfig.base.json",
+    "src/templates"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "prepack": "cp ../../README.md ./README.md",
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch && npm publish --access public"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.0",
+    "clsx": "^2.1.1",
+    "dotenv": "^17.2.1",
+    "minimatch": "^10.0.0",
+    "tailwind-merge": "^2.6.0"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": ">=2",
+    "@neondatabase/serverless": ">=0.9",
+    "@tanstack/react-query": ">=5",
+    "@vitejs/plugin-react-swc": ">=4",
+    "autoprefixer": ">=10",
+    "cors": ">=2",
+    "express": ">=5",
+    "postcss": ">=8",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "tailwindcss": ">=3",
+    "tailwindcss-animate": ">=1",
+    "typescript": ">=5",
+    "vite": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "tailwindcss": {
+      "optional": true
+    },
+    "tailwindcss-animate": {
+      "optional": true
+    },
+    "autoprefixer": {
+      "optional": true
+    },
+    "postcss": {
+      "optional": true
+    },
+    "cors": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "@vitejs/plugin-react-swc": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "@neondatabase/serverless": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.84.2",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.2.1",
+    "@types/react": "^18.3.23",
+    "@vitejs/plugin-react-swc": "^4.0.0",
+    "autoprefixer": "^10.4.21",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "@neondatabase/serverless": "^1.0.0",
+    "@supabase/supabase-js": "^2.49.0",
+    "firebase-admin": "^13.0.0",
+    "postcss": "^8.5.6",
+    "react": "^18.3.1",
+    "tailwindcss": "^3.4.17",
+    "tailwindcss-animate": "^1.0.7",
+    "typescript": "^5.9.2",
+    "vite": "^8.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/src/templates/default/.agents/skills/capture-learnings/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: capture-learnings
+description: >-
+  Capture and apply accumulated knowledge in learnings.md. Use when the user
+  corrects a mistake, when debugging reveals unexpected behavior, or when an
+  architectural decision should be recorded for future reference.
+user-invocable: false
+---
+
+# Capture Learnings
+
+This is background knowledge, not a slash command. Read `learnings.md` before starting significant work. Update it when you discover something worth remembering.
+
+## When to Capture
+
+Use judgment, not rules. Capture when:
+
+- **Surprising behavior** — Something didn't work as expected and you figured out why
+- **Repeated friction** — You hit the same issue twice; write it down so there's no third time
+- **Architectural decisions** — Why something is done a certain way (the "why" isn't in the code)
+- **API/library quirks** — Undocumented behavior, version-specific gotchas
+- **Performance insights** — What's slow and what fixed it
+
+Don't capture:
+
+- Things that are obvious from reading the code
+- Standard language/framework behavior
+- Temporary debugging notes
+
+## Format
+
+Add entries to `learnings.md` at the project root. Match the existing format — typically a heading per topic with a brief explanation:
+
+```markdown
+## [Topic]
+
+[What you learned and why it matters. Keep it to 2-3 sentences.]
+```
+
+## Graduation
+
+When a learning is referenced repeatedly, it's outgrowing `learnings.md`. Propose adding it to the relevant skill or creating a new skill via `create-skill`.
+
+- Updating `learnings.md` is a Tier 1 modification (data — auto-apply)
+- Updating a SKILL.md based on learnings is Tier 2 (source — verify after)
+
+## Related Skills
+
+- **self-modifying-code** — Learnings.md updates are Tier 1; skill updates are Tier 2
+- **create-skill** — When a learning graduates, create a skill from it

package/src/templates/default/.agents/skills/create-skill/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: create-skill
+description: >-
+  How to create new skills for an agent-native app. Use when adding a new
+  skill, documenting a pattern the agent should follow, or creating reusable
+  guidance for the agent.
+---
+
+# Create a Skill
+
+## When to Use
+
+Create a new skill when:
+
+- There's a pattern the agent should follow repeatedly
+- A workflow needs step-by-step guidance
+- You want to scaffold files from a template
+
+Don't create a skill when:
+
+- The guidance already exists in another skill (extend it instead)
+- You're documenting something the agent already knows (e.g., how to write TypeScript)
+- The guidance is a one-off — put it in `AGENTS.md` or `learnings.md` instead
+
+## 5-Question Interview
+
+Before writing the skill, answer these:
+
+1. **What should this skill enable?** — The core purpose in one sentence.
+2. **Which agent-native rule does it serve?** — Rule 1 (files), Rule 2 (delegate), Rule 3 (scripts), Rule 4 (SSE), Rule 5 (self-modify), or "utility."
+3. **When should it trigger?** — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering.
+4. **What type of skill?** — Pattern, Workflow, or Generator (see templates below).
+5. **Does it need supporting files?** — References (read-only context) or none. Keep it minimal.
+
+## Skill Types and Templates
+
+### Pattern (architectural rule)
+
+For documenting how things should be done:
+
+```markdown
+---
+name: my-pattern
+description: >-
+  [Under 40 words. When should this trigger?]
+---
+
+# [Pattern Name]
+
+## Rule
+
+[One sentence: what must be true]
+
+## Why
+
+[Why this rule exists]
+
+## How
+
+[How to follow it, with code examples]
+
+## Don't
+
+[Common violations]
+
+## Related Skills
+
+[Which skills compose with this one]
+```
+
+### Workflow (step-by-step)
+
+For multi-step implementation tasks:
+
+```markdown
+---
+name: my-workflow
+description: >-
+  [Under 40 words. When should this trigger?]
+---
+
+# [Workflow Name]
+
+## Prerequisites
+
+[What must be in place first]
+
+## Steps
+
+[Numbered steps with code examples]
+
+## Verification
+
+[How to confirm it worked]
+
+## Troubleshooting
+
+[Common issues and fixes]
+
+## Related Skills
+```
+
+### Generator (scaffolding)
+
+For creating files from templates:
+
+```markdown
+---
+name: my-generator
+description: >-
+  [Under 40 words. When should this trigger?]
+---
+
+# [Generator Name]
+
+## Usage
+
+[How to invoke — what args/inputs are needed]
+
+## What Gets Created
+
+[List of files and their purpose]
+
+## Template
+
+[The template content with placeholders]
+
+## After Generation
+
+[What to do next — wire up SSE, add routes, etc.]
+
+## Related Skills
+```
+
+## Naming Conventions
+
+- Hyphen-case only: `[a-z0-9-]`, max 64 characters
+- Pattern skills: descriptive names (`files-as-database`, `delegate-to-agent`)
+- Workflow/generator skills: verb-noun (`create-script`, `capture-learnings`)
+
+## Tips
+
+- **Keep descriptions under 40 words** — They're loaded into context on every conversation.
+- **Keep SKILL.md under 500 lines** — Move detailed content to `references/` files.
+- **Use standard markdown headings** — No XML tags or custom formats.
+
+## Anti-Patterns
+
+- **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`
+- **Vague descriptions** — "Helps with development" won't trigger. Be specific about _when_.
+- **Pure documentation** — Skills should guide action, not just explain concepts
+
+## File Structure
+
+```
+.agents/skills/my-skill/
+├── SKILL.md              # Main skill (required)
+└── references/           # Optional supporting context
+    └── detailed-guide.md
+```
+
+## Related Skills
+
+- **capture-learnings** — When a learning graduates to reusable guidance, create a skill
+- **self-modifying-code** — The agent can create new skills (Tier 2 modification)

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

@@ -0,0 +1,90 @@
+---
+name: delegate-to-agent
+description: >-
+  How to delegate all AI work to the agent chat. Use when delegating AI work
+  from UI or scripts to the agent, when tempted to add inline LLM calls, or
+  when sending messages to the agent from application code.
+---
+
+# Delegate All AI to the Agent
+
+## Rule
+
+The UI and server never call an LLM directly. All AI work is delegated to the agent through the chat bridge.
+
+## Why
+
+The agent is the single AI interface. It has context about the full project, can read/write any file, and can run scripts. Inline LLM calls bypass this — they create a shadow AI that doesn't know what the agent knows and can't coordinate with it.
+
+## How
+
+**From the UI (client):**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+
+sendToAgentChat({
+  message: "Generate a summary of this document",
+  context: documentContent, // optional hidden context (not shown in chat UI)
+  submit: true, // auto-submit to the agent
+});
+```
+
+**From scripts (Node):**
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+agentChat.submit("Process the uploaded images and create thumbnails");
+```
+
+**From the UI, detecting when agent is done:**
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core";
+
+function MyComponent() {
+  const isGenerating = useAgentChatGenerating();
+  // Show loading state while agent is working
+}
+```
+
+## `submit` vs Prefill
+
+The `submit` option controls whether the message is sent automatically or placed in the chat input for user review:
+
+| `submit` value | Behavior                                | Use when                                                                            |
+| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `true`         | Auto-submits to the agent immediately   | Routine operations the user has already approved                                    |
+| `false`        | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                          |
+
+```ts
+// Auto-submit: routine operation
+sendToAgentChat({ message: "Update the project summary", submit: true });
+
+// Prefill: let user review before sending
+sendToAgentChat({
+  message: "Delete all projects older than 30 days",
+  submit: false,
+});
+```
+
+## Don't
+
+- Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
+- Don't `import OpenAI from "openai"` in client or server code
+- Don't make direct API calls to any LLM provider
+- Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
+- Don't build "AI features" that bypass the agent chat
+
+## Exception
+
+Scripts may call external APIs (image generation, search, etc.) — but the AI reasoning and orchestration still goes through the agent. A script is a tool the agent uses, not a replacement for the agent.
+
+## Related Skills
+
+- **scripts** — The agent invokes scripts via `pnpm script <name>` to perform complex operations
+- **self-modifying-code** — The agent operates through the chat bridge to make code changes
+- **files-as-database** — The agent writes results to data files after processing requests
+- **sse-file-watcher** — The UI updates automatically when the agent writes files

package/src/templates/default/.agents/skills/files-as-database/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: files-as-database
+description: >-
+  How to store and manage application state as JSON/markdown files in data/.
+  Use when adding data models, creating file-based state, deciding where to
+  store data, or reading/writing application data files.
+---
+
+# Files as Database
+
+## Rule
+
+All application state must be stored as files. There is no traditional database in an agent-native app.
+
+## Why
+
+Files are the shared interface between the AI agent and the UI. The agent reads and writes files directly on the filesystem. The UI reads files via API routes. SSE streams file changes back to the UI in real-time. This only works if files are the single source of truth.
+
+## How
+
+- Store data as JSON or markdown files in `data/` (or a project-specific subdirectory).
+- API routes in `server/index.ts` read files with `fs.readFile` and return them.
+- The agent modifies files directly — no API calls needed from the agent side.
+- `createFileWatcher("./data")` watches for changes and streams them via SSE.
+- `useFileWatcher()` on the client invalidates React Query caches when files change.
+
+## Don't
+
+- Don't add a database (SQLite, Postgres, MongoDB, etc.)
+- Don't store app state in localStorage, sessionStorage, or cookies
+- Don't keep state only in memory (server variables, global stores)
+- Don't use Redis or any external state store
+- Don't interpolate user input directly into file paths (see Security below)
+
+## Example
+
+```ts
+import fs from "fs";
+
+// Writing state (agent or script)
+fs.writeFileSync(
+  "data/projects/my-project.json",
+  JSON.stringify(project, null, 2),
+);
+
+// Reading state (server route) — note the path sanitization
+app.get("/api/projects/:id", (req, res) => {
+  const id = req.params.id.replace(/[^a-zA-Z0-9_-]/g, "");
+  const data = fs.readFileSync(`data/projects/${id}.json`, "utf-8");
+  res.json(JSON.parse(data));
+});
+```
+
+## Creating a New Data Model
+
+When adding a new data entity (e.g., projects, tasks, settings):
+
+1. **Define the type** in `shared/` so both client and server import it
+2. **Create the data directory** — `data/<model>/<id>.json` (one file per item) or `data/<model>.json` (single collection)
+3. **Add API routes** in `server/` that read/write the files (sanitize IDs from params)
+4. **Wire SSE invalidation** — Add the query key to `useFileWatcher()` so the UI refreshes on changes
+
+## Judgment Criteria
+
+| Question                             | Single file       | Directory of files           |
+| ------------------------------------ | ----------------- | ---------------------------- |
+| Are items independently addressable? | No — use one file | Yes — one file per item      |
+| Will there be >50 items?             | Probably fine     | Definitely split             |
+| Do items need individual URLs?       | No                | Yes                          |
+| Do items change independently?       | No                | Yes — avoids write conflicts |
+
+## Scaling Guidance
+
+| File Count | Recommendation                                                        |
+| ---------- | --------------------------------------------------------------------- |
+| Under 50   | Read-all with `readdirSync` + `readFileSync` is fine                  |
+| 50–200     | Add an index file (`data/<model>/_index.json`) with IDs and summaries |
+| 200+       | Partition into subdirectories                                         |
+
+For list endpoints serving many files, use `fs.promises.readFile` instead of `readFileSync` to avoid blocking the event loop.
+
+## Security
+
+- **Path sanitization** — Always sanitize IDs from request params before constructing file paths. Use `id.replace(/[^a-zA-Z0-9_-]/g, "")` or the core utility `isValidPath()`. Without this, `../../.env` as an ID reads your environment file.
+- **Validate before writing** — Check data shape before writing files, especially for user-submitted data. A malformed write can break all subsequent reads.
+
+## Related Skills
+
+- **sse-file-watcher** — Set up real-time sync so the UI updates when data files change
+- **scripts** — Create scripts that read/write data files for complex operations
+- **self-modifying-code** — The agent writes data files as Tier 1 (auto-apply) modifications