@agent-native/core 0.4.5 → 0.6.1

package/dist/templates/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/dist/templates/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/dist/templates/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/dist/templates/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 (`storing-data`, `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 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
+
+## 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/dist/templates/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 the database, 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 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/dist/templates/templates/default/.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: frontend-design
+description: >-
+  Create distinctive, production-grade frontend interfaces with high design
+  quality. Use when building web components, pages, artifacts, posters, or
+  applications (websites, landing pages, dashboards, React components,
+  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
+  creative, polished UI that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+---
+
+# Frontend Design
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+## Anti-Patterns to Avoid
+
+NEVER use generic AI-generated aesthetics like:
+- Overused font families (Inter, Roboto, Arial, system fonts)
+- Clichéd color schemes (particularly purple gradients on white backgrounds)
+- Predictable layouts and component patterns
+- Cookie-cutter design that lacks context-specific character
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+## Implementation Notes
+
+**Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+In the agent-native framework context:
+- Agent-native apps use React 18, Vite, TailwindCSS, and shadcn/ui
+- Custom styles go in component CSS or Tailwind classes — never inline styles
+- For complex visual effects, use a `<style>` tag in the component or a dedicated CSS file
+- Fonts can be loaded from Google Fonts via `@import` in a CSS file or `<link>` in `index.html`
+- Animation libraries: prefer CSS transitions and keyframes; use Framer Motion for complex sequences
+- All new UI components should be placed in `app/components/`
+
+## Related Skills
+
+- **self-modifying-code** — The agent can edit source code to apply design changes
+- **storing-data** — Design configuration can be stored in the settings table for agent-editable theming