@agent-native/core 0.14.8 → 0.15.0

package/dist/templates/workspace-core/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: context-awareness
+description: >-
+  How the agent knows what the user is looking at. Use when exposing UI state to
+  the agent, implementing view-screen or navigate scripts, wiring navigation
+  state, or debugging agent context issues.
+---
+
+# Context Awareness
+
+## Rule
+
+The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.
+
+## Why
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
+
+## The Three Patterns
+
+### 1. Navigation State (`navigation` key)
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on and what item is selected.
+
+**UI side** — the `use-navigation-state.ts` hook:
+
+```ts
+// app/hooks/use-navigation-state.ts
+import { useEffect, useCallback } from "react";
+import { useLocation } from "react-router";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+export function useNavigationState() {
+  const location = useLocation();
+
+  // Sync route to app-state on every navigation
+  useEffect(() => {
+    const state = deriveNavigationState(location.pathname);
+    fetch("/_agent-native/application-state/navigation", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+
+  // ... also listen for navigate commands (pattern 3)
+}
+```
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- Filter state — active search, label, or category filters
+- Any selection — focused item, selected text range, active tab
+
+### 2. The `view-screen` Script
+
+Every template should have a `view-screen` script. It reads navigation state, fetches the relevant data from the API, and returns a snapshot of what the user sees. This is the agent's eyes.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const screen: Record<string, unknown> = { navigation };
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const emails = await fetchEmailList(navigation.label);
+    screen.emailList = emails;
+  }
+  if (navigation?.threadId) {
+    const thread = await fetchThread(navigation.threadId);
+    screen.thread = thread;
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+**Navigation state is auto-injected into every user message as a `<current-screen>` block**, so the agent always has basic context without calling any tool. The `view-screen` action is still useful when you need a richer snapshot (e.g., fetching the full email thread or form data for the current view).
+
+### 3. The `navigate` Script
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+**Agent side:**
+
+```ts
+import { writeAppState } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
+```
+
+**UI side** — the hook polls for the command:
+
+```ts
+const { data: navCommand } = useQuery({
+  queryKey: ["navigate-command"],
+  queryFn: async () => {
+    const res = await fetch("/_agent-native/application-state/navigate");
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (data) {
+      // Delete the one-shot command after reading
+      fetch("/_agent-native/application-state/navigate", { method: "DELETE" });
+      return data;
+    }
+    return null;
+  },
+  staleTime: 2_000,
+});
+
+useEffect(() => {
+  if (navCommand) {
+    router.navigate(buildPath(navCommand));
+  }
+}, [navCommand]);
+```
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings"],
+  ignoreSource: TAB_ID,  // ignore events from this tab's own writes
+});
+```
+
+The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When polling, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
+
+## Gold-Standard Example: Mail Template
+
+The mail template demonstrates all three patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "search": "budget", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- Fetches email list matching current view/search/label filters
+- Fetches thread messages if a thread is open
+- Returns everything as a single JSON snapshot
+
+**navigate command:**
+- `{ "view": "starred" }` — switch to starred view
+- `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+
+## Do
+
+- Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
+- Include all relevant selection state in the `navigation` key (view, item IDs, filters)
+- Update `view-screen` when adding new features — it should return data for every view
+- Use the one-shot `navigate` command pattern for agent-initiated navigation
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — always check navigation state
+- Don't hardcode navigation paths in scripts — read the current state and branch
+- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- Don't store fetched data in navigation state — it holds IDs and filters only. The `view-screen` script fetches the actual data.
+
+## Related Skills
+
+- **adding-a-feature** — Context awareness is area 4 of the four-area checklist
+- **real-time-sync** — How polling and `useDbSync` deliver app-state changes to the UI
+- **scripts** — How to create the `view-screen` and `navigate` scripts
+- **storing-data** — Application-state is one of the core SQL stores

package/dist/templates/workspace-core/.agents/skills/create-skill/SKILL.md

@@ -0,0 +1,168 @@
+---
+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 (data in SQL), Rule 2 (delegate to agent), Rule 3 (scripts), Rule 4 (polling sync), Rule 5 (self-modify), Rule 6 (app-state in SQL), or "utility."
+3. **When should it trigger?** — Describe the situations in natural language. Be slightly pushy — over-triggering is better than under-triggering.
+4. **Does it involve context awareness?** — Does the agent need to know what the user is looking at to use this skill? If yes, the skill should reference the `navigation` app-state key and the `view-screen` script pattern. See the **context-awareness** skill.
+5. **What type of skill?** — Pattern, Workflow, or Generator (see templates below).
+6. **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/workspace-core/.agents/skills/delegate-to-agent/SKILL.md

@@ -0,0 +1,163 @@
+---
+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 a user asks for agent behavior or
+  LLM-powered features, 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,
+});
+```
+
+## Capture user input first when generating from a prompt
+
+Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
+
+**Bad** — auto-submits a placeholder message; the user never said what they wanted:
+
+```tsx
+<Button
+  onClick={() =>
+    sendToAgentChat({ message: "make a design", submit: true })
+  }
+>
+  New Design
+</Button>
+```
+
+**Good** — Popover anchored to the button captures the prompt, then submits it:
+
+```tsx
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>New Design</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-96">
+    <Textarea
+      autoFocus
+      value={prompt}
+      onChange={(e) => setPrompt(e.target.value)}
+      placeholder="What do you want to design?"
+    />
+    <Button
+      onClick={() => {
+        sendToAgentChat({ message: prompt, submit: true });
+        setOpen(false);
+        setPrompt("");
+      }}
+    >
+      Create
+    </Button>
+  </PopoverContent>
+</Popover>
+```
+
+**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
+
+**Auto-submit without input is fine when intent is unambiguous:**
+
+- "Try to fix" on a tool error — submits the error details with a clear fix instruction
+- "Retry the last operation" after a transient failure
+- Single-purpose buttons where there is nothing meaningful for the user to add
+
+If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
+
+## 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
+- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
+
+## 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.
+
+## When to Use A2A Instead
+
+`sendToAgentChat()` delegates work to the **local** agent — the one running alongside your app. When the work should go to a **different** agent entirely (e.g., asking an analytics agent for data, or a calendar agent for availability), use the A2A (agent-to-agent) protocol instead.
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// Call a different agent — not the local agent chat
+const stats = await callAgent(
+  "https://analytics.example.com",
+  "What were last week's signups?",
+  { apiKey: process.env.ANALYTICS_A2A_KEY },
+);
+```
+
+See the **a2a-protocol** skill for the full pattern.
+
+## Related Skills
+
+- **a2a-protocol** — When the work goes to a different agent, not the local one
+- **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 data