@agent-native/core 0.14.8 → 0.15.1

package/dist/templates/default/.agents/skills/real-time-sync/SKILL.md

@@ -20,35 +20,47 @@ The agent modifies data in SQL, but the UI runs in the browser. Polling bridges
 
 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:
+2. **Client** polls for changes and updates per-source counters:
 
    ```ts
    import { useDbSync } from "@agent-native/core";
-   useDbSync({ queryClient, queryKeys: ["items", "settings"] });
+   useDbSync({ queryClient });
    ```
 
-3. When the agent writes to the database, the version increments, polling detects it, and React Query refetches the affected queries.
+3. **Templates fold a per-source counter into the relevant query key.** When the source advances, only the dependent query refetches:
+
+   ```ts
+   import { useChangeVersion } from "@agent-native/core/client";
+
+   const v = useChangeVersion("items"); // or "settings", "dashboards", "action", etc.
+   const { data } = useQuery({
+     queryKey: ["items", v],
+     queryFn: fetchItems,
+     placeholderData: (prev) => prev,
+   });
+   ```
+
+4. When the agent writes to the database, the server emits a `recordChange({ source, ... })` event. `useDbSync` bumps the matching counter; any query with that counter in its key refetches; everything else stays untouched.
 
 ## 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
+## Tuning refetch behavior
 
-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:
+`useDbSync` invalidates every active query on any non-own change event. The `onEvent` callback still fires with each change event, so templates can layer surgical extras on top — for example, invalidating an inactive query that wouldn't otherwise refetch:
 
 ```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"] });
+      // Force a refetch even when not actively observed
+      queryClient.invalidateQueries({
+        queryKey: ["settings"],
+        refetchType: "all",
+      });
     }
   },
 });
@@ -66,11 +78,11 @@ useQuery({
 
 ## 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.                        |
+| Symptom                            | Check                                                                                                    |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?  |
+| 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 to debounce refetches.                          |
 
 ## Jitter Prevention
 
@@ -93,7 +105,6 @@ import { TAB_ID } from "@/lib/tab-id";
 
 useDbSync({
   queryClient,
-  queryKeys: ["app-state", "settings"],
   ignoreSource: TAB_ID,
 });
 ```

package/dist/templates/default/.agents/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: shadcn-ui
+description: >-
+  Use when adding, updating, debugging, styling, or composing shadcn/ui
+  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
+  any project with a components.json file.
+source: https://ui.shadcn.com/docs/skills
+---
+
+# shadcn/ui
+
+This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
+
+## First Steps
+
+1. Work from the app root that owns `components.json`.
+2. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
+3. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
+4. Check `app/components/ui/` or the resolved `ui` path before importing a component.
+5. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+
+## Adding Or Updating Components
+
+- Add missing primitives with `pnpm dlx shadcn@latest add <component>` from the app root.
+- Before overwriting an existing component, use `pnpm dlx shadcn@latest add <component> --dry-run` and `--diff` to inspect the change.
+- After adding registry code, read the generated files. Fix import aliases, icon imports, missing subcomponents, and composition issues before using the component.
+- Do not fetch raw component files manually from GitHub when the shadcn CLI can resolve the registry item.
+- If a user asks to add a third-party block but does not name a registry, ask which registry to use instead of guessing.
+
+## Component Composition
+
+- Use existing primitives before custom markup: `Alert` for callouts, `Badge` for small status labels, `Separator` for dividers, `Skeleton` for placeholders, `Table` for tabular data, and `Card` for framed content.
+- Use full card anatomy when appropriate: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`.
+- Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
+- Put items inside their group components: `SelectItem` in `SelectGroup`, `DropdownMenuItem` in `DropdownMenuGroup`, `CommandItem` in `CommandGroup`, and equivalent menu groups.
+- `TabsTrigger` belongs inside `TabsList`.
+- `Avatar` always needs `AvatarFallback`.
+- Buttons do not have magic loading props. Compose loading with `disabled`, `Spinner`, and clear text.
+
+## Forms And Inputs
+
+- Use the app's shadcn form primitives instead of raw div stacks.
+- If `Field`, `FieldGroup`, `FieldSet`, or `InputGroup` are installed or worth adding, use them for form layout, grouped fields, and input add-ons.
+- Do not place buttons inside inputs with absolute positioning. Use `InputGroup` and `InputGroupAddon` when available.
+- Use `ToggleGroup` for small option sets, `RadioGroup` for one-of-many choices, `Checkbox` for multi-select, `Switch` for settings toggles, `Select` or `Combobox` for predefined choices, and `Slider` or numeric input for numeric values.
+- Validation must be accessible: pair visual invalid states with `aria-invalid`, and connect descriptions/errors to controls.
+
+## Styling And Theming
+
+- Use semantic tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, `text-destructive`) instead of raw colors for reusable app UI.
+- Prefer built-in variants and sizes before custom classes.
+- Use `className` mostly for layout and spacing; avoid overriding component colors and typography unless the component is intentionally being extended.
+- Use `gap-*` instead of `space-x-*` / `space-y-*`.
+- Use `size-*` when width and height are equal.
+- Use `truncate` for single-line clipping.
+- Use `cn()` for conditional classes.
+- Do not add manual `z-index` to overlay primitives unless you are fixing a verified stacking bug.
+- Add custom colors as CSS variables in the existing Tailwind CSS file reported by shadcn info. For Tailwind v4, register variables with `@theme inline`.
+
+## Icons
+
+- Agent-native apps use `@tabler/icons-react`. Do not add `lucide-react` because a registry example used it.
+- If registry code imports a different icon package, replace those imports with Tabler equivalents before finishing.
+- Let shadcn components size icons through their CSS. Avoid manual icon sizing inside buttons, menus, alerts, and sidebars unless the local component API requires it.
+
+## Base-Specific APIs
+
+Check the project context before using trigger composition APIs:
+
+- Radix-based components use `asChild` for custom triggers.
+- Base UI components may use `render` and sometimes `nativeButton={false}`.
+
+Do not wrap triggers in extra divs just to place a Button or Link inside them.
+
+## Related Skills
+
+- **frontend-design** — Product UX, visual direction, responsive polish, and verification
+- **actions** — Data fetching and mutation patterns for agent-native apps
+- **security** — User data, forms, external input, and action safety

package/dist/templates/default/AGENTS.md

@@ -9,7 +9,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 1. **Shared SQL database** -- All app state lives in SQL (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
 2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
 3. **Actions for agent operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`.
-4. **Polling for real-time sync** -- Database writes trigger version counter increments that the UI polls to stay in sync.
+4. **Polling for real-time sync** -- Database writes trigger version counter increments that the UI polls to stay in sync. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` (auto-covered) or fold `useChangeVersions([<source>, "action"])` into raw `useQuery` keys. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.
 
 ### Authentication
@@ -90,28 +90,31 @@ You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at t
 
 Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
-| Skill                 | When to read                                                    |
-| --------------------- | --------------------------------------------------------------- |
-| `storing-data`        | Before storing or reading any app state                         |
-| `delegate-to-agent`   | Before adding LLM calls or AI delegation                        |
-| `actions`             | Before creating or modifying actions                            |
-| `real-time-sync`      | Before wiring up real-time UI sync                              |
-| `self-modifying-code` | Before editing source, components, or styles                    |
-| `capture-learnings`   | Before recording user preferences or corrections                |
-| `frontend-design`     | Before building or restyling any UI component, page, or layout  |
-| `agent-engines`       | Before switching LLM providers or registering a custom engine   |
-| `notifications`       | Before surfacing alerts/progress to the user or adding channels |
-| `progress`            | Before running any task that takes more than a few seconds      |
+| Skill                 | When to read                                                                      |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `adding-a-feature`    | **Read first when adding ANY new feature** — the four-area parity checklist       |
+| `real-time-sync`      | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
+| `storing-data`        | Before storing or reading any app state                                           |
+| `delegate-to-agent`   | Before adding LLM calls or AI delegation                                          |
+| `actions`             | Before creating or modifying actions                                              |
+| `self-modifying-code` | Before editing source, components, or styles                                      |
+| `capture-learnings`   | Before recording user preferences or corrections                                  |
+| `frontend-design`     | Before building or restyling any UI component, page, or layout                    |
+| `shadcn-ui`           | Before adding, updating, or debugging shadcn/ui components                        |
+| `agent-engines`       | Before switching LLM providers or registering a custom engine                     |
+| `notifications`       | Before surfacing alerts/progress to the user or adding channels                   |
+| `progress`            | Before running any task that takes more than a few seconds                        |
 
 ## When Adding Features
 
-As you build out this app, follow this checklist for each new feature:
+**Read the `adding-a-feature` skill first** — it has the full four-area checklist (UI / Action / Skills / App-State). Quick summary:
 
-1. **Add navigation state entries** -- extend `app/hooks/use-navigation-state.ts` to track new routes
-2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
-3. **Create domain actions** -- add scripts for CRUD operations on new data models
-4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
-5. **Update this AGENTS.md** -- add the new actions, state keys, and common tasks
+1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes
+2. **Enhance view-screen** — make the view-screen script return relevant context for the new view
+3. **Create domain actions** — add actions in `actions/` for CRUD operations on new data models
+4. **Wire UI for auto-refresh** — use `useActionQuery` (auto-covered) OR fold `useChangeVersions([<source>, "action"])` into raw `useQuery` keys with `placeholderData`. When the agent mutates this data, the UI must reflect the change without a manual refresh. See `real-time-sync` skill.
+5. **Create domain skills** — add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
+6. **Update this AGENTS.md** — add the new actions, state keys, and common tasks
 
 ---
 

package/dist/templates/default/actions/navigate.ts

@@ -35,6 +35,9 @@ export async function run(args: Record<string, string>): Promise<string> {
   const nav: Record<string, string> = {};
   if (args.view) nav.view = args.view;
   if (args.path) nav.path = args.path;
+  // Unique-per-write token so the UI's `use-navigation-state` hook can dedup
+  // race-driven re-reads of the same command.
+  nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   await writeAppState("navigate", nav);
   return `Navigating to ${args.view || args.path}`;
 }

package/dist/templates/default/app/hooks/use-navigation-state.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useLocation, useNavigate } from "react-router";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import {
@@ -10,6 +10,10 @@ import {
 export interface NavigationState {
   view: string;
   path?: string;
+  /** Optional unique-per-write token. Used by the UI to dedup the same
+   * command being re-read when the fire-and-forget DELETE below loses its
+   * race against the next polling refetch. */
+  _writeId?: string;
 }
 
 export function useNavigationState() {
@@ -31,7 +35,11 @@ export function useNavigationState() {
     }).catch(() => {});
   }, [location.pathname]);
 
-  const { data: navCommand } = useQuery({
+  // Default React Query structuralSharing reuses the previous reference when
+  // the JSON is unchanged, so repeated invalidations driven by `useDbSync`
+  // (which fire on every relevant app-state event) don't re-fire the
+  // useEffect with a brand-new object containing the same command.
+  const { data: navCommand } = useQuery<NavigationState | null>({
     queryKey: ["navigate-command"],
     queryFn: async () => {
       const res = await fetch(
@@ -39,19 +47,35 @@ export function useNavigationState() {
       );
       if (!res.ok) return null;
       const data = await res.json();
-      return data ? { ...data, _ts: Date.now() } : null;
+      return data ?? null;
     },
     refetchInterval: 2_000,
-    structuralSharing: false,
   });
 
+  const lastProcessedDedupKeyRef = useRef<string | null>(null);
+
   useEffect(() => {
     if (!navCommand) return;
+    const cmd = navCommand;
+    const dedupKey =
+      cmd._writeId ?? JSON.stringify({ view: cmd.view, path: cmd.path });
+    if (lastProcessedDedupKeyRef.current === dedupKey) {
+      // Same command we already handled — the consume-DELETE races against
+      // the next polling refetch, so when it loses the same command can show
+      // up again. Re-fire DELETE and bail rather than navigate again.
+      fetch(agentNativePath("/_agent-native/application-state/navigate"), {
+        method: "DELETE",
+        headers: { "X-Agent-Native-CSRF": "1" },
+      }).catch(() => {});
+      qc.setQueryData(["navigate-command"], null);
+      return;
+    }
+    lastProcessedDedupKeyRef.current = dedupKey;
+
     fetch(agentNativePath("/_agent-native/application-state/navigate"), {
       method: "DELETE",
       headers: { "X-Agent-Native-CSRF": "1" },
     }).catch(() => {});
-    const cmd = navCommand as NavigationState;
 
     const path = routerPath(cmd.path || pathFromView(cmd.view));
     navigate(path);

package/dist/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: a2a-protocol
+description: >-
+  How agents call other agents via the A2A (agent-to-agent) JSON-RPC protocol.
+  Use when enabling inter-agent communication, exposing agent skills to other
+  agents, or calling external agents from scripts.
+---
+
+# A2A Protocol (Agent-to-Agent)
+
+## Rule
+
+Agents can call other agents using the A2A protocol. This is a JSON-RPC-based protocol for agent discovery and communication. Use it when work should go to a different agent entirely — not the local agent chat.
+
+## Why
+
+Agent-native apps don't exist in isolation. A mail agent might need analytics data. A calendar agent might need to search issues. A2A lets agents discover each other, send messages, and receive structured results — all over HTTP with bearer token auth.
+
+## How to Enable A2A (Server Side)
+
+Add `mountA2A()` to a server plugin:
+
+```ts
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  const app = nitro.h3App;
+
+  mountA2A(app, {
+    name: "Analytics Agent",
+    description: "Queries analytics data across providers",
+    version: "1.0.0",
+    skills: [
+      {
+        id: "query-data",
+        name: "Query Data",
+        description: "Run analytics queries across connected data sources",
+        tags: ["analytics", "data"],
+        examples: ["What were last week's signups?", "Show conversion rates"],
+      },
+    ],
+    apiKeyEnv: "A2A_API_KEY", // env var holding the bearer token
+    streaming: true,          // enable message/stream method
+  });
+});
+```
+
+This mounts the agent-native A2A endpoints:
+
+- `GET /.well-known/agent-card.json` — public agent discovery (no auth required)
+- `POST /_agent-native/a2a` — primary JSON-RPC endpoint (bearer token auth required)
+
+The client may fall back to `POST /a2a` for external or legacy peers that only
+expose that simple path. New agent-native apps should document and call the
+`/_agent-native/a2a` endpoint.
+
+## The Config Object
+
+```ts
+interface A2AConfig {
+  name: string;           // agent display name
+  description: string;    // what this agent does
+  version?: string;       // semver version (default: "1.0.0")
+  skills: AgentSkill[];   // capabilities this agent exposes
+  handler?: A2AHandler;   // custom message handler
+  apiKeyEnv?: string;     // env var name for bearer token auth
+  streaming?: boolean;    // enable streaming responses
+}
+
+interface AgentSkill {
+  id: string;             // unique skill identifier
+  name: string;           // human-readable name
+  description: string;    // what this skill does
+  tags?: string[];        // categorization tags
+  examples?: string[];    // example prompts
+}
+```
+
+## Agent Card
+
+The agent card is auto-generated at `GET /.well-known/agent-card.json`. Other agents fetch this to discover what skills are available:
+
+```json
+{
+  "name": "Analytics Agent",
+  "description": "Queries analytics data across providers",
+  "url": "https://analytics.example.com",
+  "version": "1.0.0",
+  "protocolVersion": "0.3",
+  "capabilities": { "streaming": true },
+  "skills": [
+    {
+      "id": "query-data",
+      "name": "Query Data",
+      "description": "Run analytics queries across connected data sources"
+    }
+  ]
+}
+```
+
+## Calling Another Agent
+
+### Simple: `callAgent()` (text in, text out)
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+const answer = await callAgent(
+  "https://analytics.example.com",
+  "What were last week's signups?",
+  { apiKey: process.env.ANALYTICS_A2A_KEY },
+);
+// answer is a plain string
+```
+
+### Advanced: `A2AClient` (full control)
+
+```ts
+import { A2AClient } from "@agent-native/core/a2a";
+
+const client = new A2AClient(
+  "https://analytics.example.com",
+  process.env.ANALYTICS_A2A_KEY,
+);
+
+// Discover agent capabilities
+const card = await client.getAgentCard();
+
+// Send a message and get a task back
+const task = await client.send({
+  role: "user",
+  parts: [{ type: "text", text: "What were last week's signups?" }],
+});
+// task.status.state === "completed"
+// task.status.message.parts[0].text === "Last week: 1,247 signups..."
+
+// Stream responses
+for await (const update of client.stream({
+  role: "user",
+  parts: [{ type: "text", text: "Detailed breakdown by day" }],
+})) {
+  console.log(update.status.state, update.status.message);
+}
+```
+
+## JSON-RPC Methods
+
+| Method           | Purpose                          | Auth required |
+| ---------------- | -------------------------------- | ------------- |
+| `message/send`   | Send a message, get a task back  | Yes           |
+| `message/stream` | Send a message, stream responses | Yes           |
+| `tasks/get`      | Get task status by ID            | Yes           |
+| `tasks/cancel`   | Cancel a running task            | Yes           |
+
+## Task Lifecycle
+
+Tasks go through these states:
+
+```
+submitted → working → completed
+                    → failed
+                    → canceled
+                    → input-required
+```
+
+- **submitted** — message received, not yet processing
+- **working** — agent is processing the request
+- **completed** — agent finished, result in `status.message`
+- **failed** — agent encountered an error
+- **canceled** — task was canceled via `tasks/cancel`
+- **input-required** — agent needs more information from the caller
+
+## Security
+
+A2A uses bearer token auth. The server reads the token from the environment variable specified by `apiKeyEnv`:
+
+- Set `A2A_API_KEY=my-secret-token` in the server's environment
+- Callers pass it as `Authorization: Bearer my-secret-token`
+- The agent card endpoint (`/.well-known/agent-card.json`) is public — no auth needed for discovery
+
+## Message Parts
+
+Messages contain typed parts:
+
+| Part type | Fields                              | Use for                    |
+| --------- | ----------------------------------- | -------------------------- |
+| `text`    | `{ type: "text", text: "..." }`     | Natural language messages  |
+| `file`    | `{ type: "file", file: { ... } }`   | Files (bytes or URI)       |
+| `data`    | `{ type: "data", data: { ... } }`   | Structured JSON data       |
+
+## Example: Cross-Agent Workflow
+
+A mail agent calls an analytics agent to include data in an email draft:
+
+```ts
+// actions/draft-with-analytics.ts
+import { callAgent } from "@agent-native/core/a2a";
+import { writeAppState } from "@agent-native/core/application-state";
+
+export default async function (args: string[]) {
+  // Ask the analytics agent for data
+  const stats = await callAgent(
+    process.env.ANALYTICS_AGENT_URL!,
+    "Summarize last week's key metrics in 3 bullet points",
+    { apiKey: process.env.ANALYTICS_A2A_KEY },
+  );
+
+  // Create a draft with the analytics data
+  await writeAppState("compose-analytics-report", {
+    id: "analytics-report",
+    to: "team@example.com",
+    subject: "Weekly Analytics Summary",
+    body: `Hi team,\n\nHere are last week's numbers:\n\n${stats}\n\nBest`,
+    mode: "compose",
+  });
+}
+```
+
+## All Types
+
+All types are exported from `@agent-native/core/a2a`:
+
+```ts
+import type {
+  A2AConfig,
+  A2AHandler,
+  A2AHandlerContext,
+  A2AHandlerResult,
+  AgentCard,
+  AgentSkill,
+  AgentCapabilities,
+  Task,
+  TaskState,
+  TaskStatus,
+  Message,
+  Part,
+  TextPart,
+  FilePart,
+  DataPart,
+  Artifact,
+  JsonRpcRequest,
+  JsonRpcResponse,
+} from "@agent-native/core/a2a";
+```
+
+## Related Skills
+
+- **delegate-to-agent** — For work the local agent handles. Use A2A when the work goes to a different agent.
+- **scripts** — A2A calls typically happen in scripts
+- **storing-data** — Results from A2A calls are stored in SQL like any other data