@agent-native/core 0.21.0 → 0.22.1

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

@@ -1,70 +1,141 @@
 ---
 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.
+  How to create and run agent actions. Actions are the single source of truth
+  for app operations — the agent calls them as tools, the frontend calls them
+  as HTTP endpoints. Use when creating a new action, adding an API integration,
+  or wiring up frontend data fetching.
 ---
 
 # Agent Actions
 
 ## Rule
 
-Complex operations the agent needs to perform are implemented as actions in `actions/`. The agent runs them via `pnpm action <name>`.
+Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, and the framework auto-exposes them as HTTP endpoints at `/_agent-native/actions/:name`. The frontend calls those endpoints using React Query hooks. No duplicate `/api/` routes needed.
 
 ## 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.
+Actions give the agent callable tools with structured input/output, AND they give the frontend type-safe HTTP endpoints automatically. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
 
 ## How to Create an Action
 
-Create `actions/my-action.ts`:
+Use `defineAction` with a Zod schema (required for new actions):
 
 ```ts
-import fs from "fs";
-import { parseArgs, loadEnv, fail, agentChat } from "@agent-native/core";
+// actions/list-meals.ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+import { getDb } from "../server/db/index.js";
+import { meals } from "../server/db/schema.js";
 
-export default async function myAction(args: string[]) {
-  loadEnv();
+export default defineAction({
+  description: "List all meals",
+  schema: z.object({
+    date: z.string().describe("Filter by date (YYYY-MM-DD)"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    // args is fully typed: { date: string }
+    const db = getDb();
+    const rows = await db.select().from(meals);
+    return rows; // Return objects/arrays, NOT JSON.stringify()
+  },
+});
+```
 
-  const parsed = parseArgs(args);
-  const input = parsed.input;
-  if (!input) fail("--input is required");
+The `schema` field accepts a Zod schema (or any Standard Schema-compatible library). It provides runtime validation with clear error messages (400 for HTTP, error result for agent), full TypeScript type inference for `run()` args, and auto-generated JSON Schema for the agent's tool definition. `zod` is a dependency of all templates.
+
+Tips:
+- Use `.describe()` for parameter descriptions
+- Use `.optional()` for optional params
+- Use `z.coerce.number()` / `z.coerce.boolean()` for params that arrive as strings from HTTP
+- Use `z.enum(["draft", "published"])` for constrained values
+
+The legacy `parameters` field (plain JSON Schema object) still works as a fallback but does not provide runtime validation or type inference.
+
+### The `http` Option
+
+Controls how the action is exposed as an HTTP endpoint:
+
+| Value                     | Behavior                                                    | Use for                          |
+| ------------------------- | ----------------------------------------------------------- | -------------------------------- |
+| _(omitted)_               | Auto-exposed as `POST /_agent-native/actions/:name`         | Write operations (default)       |
+| `{ method: "GET" }`       | Auto-exposed as `GET /_agent-native/actions/:name`          | Read-only queries                |
+| `{ method: "PUT" }`       | Auto-exposed as `PUT /_agent-native/actions/:name`          | Update operations                |
+| `{ method: "DELETE" }`    | Auto-exposed as `DELETE /_agent-native/actions/:name`       | Delete operations                |
+| `{ method: "GET", path: "custom" }` | Auto-exposed as `GET /_agent-native/actions/custom` | Custom route path                |
+| `false`                   | Agent-only, never exposed as HTTP                           | `navigate`, `view-screen`, internal actions |
+
+### Screen Refresh (automatic)
+
+The framework auto-refreshes the UI after any successful mutating action. On completion of a non-`GET` action, the framework emits a change event with `source: "action"` that the client's `useDbSync` picks up and uses to invalidate `["action"]` React Query keys — so `list-*` / `get-*` hooks refetch without a full page reload. In-process calls emit directly; dev-mode `pnpm action ...` calls also write a durable marker so the web server sees child-process action changes.
+
+Rules:
+
+- `http: { method: "GET" }` → read-only, does NOT trigger a refresh (inferred automatically).
+- Any other action (default `POST`, `PUT`, `DELETE`, or `http: false`) → treated as mutating, triggers a refresh on success.
+- To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
+- To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
+
+Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
+
+### Return Values
 
-  const outputPath = parsed.output ?? "data/result.json";
-  const raw = fs.readFileSync(input, "utf-8");
-  const data = JSON.parse(raw) as unknown;
+Actions should return **structured data** (objects, arrays) — not `JSON.stringify()`. The framework serializes the response automatically. If you return a string, the framework tries to parse it as JSON for a clean response.
 
-  fs.writeFileSync(outputPath, JSON.stringify(data, null, 2));
-  agentChat.submit(`Processed ${input}, result saved to ${outputPath}`);
+```ts
+// Good — return structured data
+run: async (args) => {
+  const events = await fetchEvents(args.from, args.to);
+  return events;
+}
+
+// Bad — don't stringify
+run: async (args) => {
+  const events = await fetchEvents(args.from, args.to);
+  return JSON.stringify(events, null, 2);
 }
 ```
 
-### Using `defineAction` with Zod schema (recommended for new actions)
+## Frontend Hooks
+
+The frontend calls action endpoints using React Query hooks from `@agent-native/core/client`:
+
+### `useActionQuery` — for GET actions
 
 ```ts
-import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { useActionQuery } from "@agent-native/core/client";
+
+function MealList() {
+  // Types are auto-inferred from the action's schema + return type — no manual generic needed
+  const { data: meals } = useActionQuery("list-meals", {
+    date: "2025-01-01",
+  });
+  return <ul>{meals?.map((m) => <li key={m.id}>{m.name}</li>)}</ul>;
+}
+```
 
-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";
-  },
-});
+### `useActionMutation` — for POST/PUT/DELETE actions
+
+```ts
+import { useActionMutation } from "@agent-native/core/client";
+
+function AddMealButton() {
+  // Types are auto-inferred — no manual generic needed
+  const { mutate } = useActionMutation("log-meal");
+  return (
+    <button onClick={() => mutate({ name: "Salad", calories: 350 })}>
+      Log Meal
+    </button>
+  );
+}
 ```
 
-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.
+**Do NOT use manual type generics** like `useActionQuery<Meal[]>(...)`. Types are inferred automatically from `.generated/action-types.d.ts`, which is auto-generated by a Vite plugin.
 
-The legacy `parameters` field (plain JSON Schema object) still works as a fallback.
+Mutations automatically invalidate all `["action"]` query keys on success, so GET queries refetch.
 
-## How to Run
+## How to Run (Agent)
 
 ```bash
 pnpm action my-action --input data/source.json --output data/result.json
@@ -81,63 +152,113 @@ runScript();
 
 This is the canonical approach for new apps. Action names must be lowercase with hyphens only (e.g., `my-action`).
 
+## When You Still Need Custom `/api/` Routes
+
+Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+
+- **File uploads** — actions receive JSON params, not multipart form data
+- **Streaming responses** — SSE or chunked responses that need direct H3 control
+- **Webhooks** — external services POST to a specific URL
+- **OAuth callbacks** — redirect-based flows that need specific URL patterns
+
+If it's a standard CRUD operation or data query, use an action instead.
+
+## Legacy Pattern (bare export)
+
+Older actions use a bare async function export with `parseArgs`:
+
+```ts
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function myAction(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  // ...
+}
+```
+
+This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all new actions.
+
 ## Guidelines
 
 - **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
-- **Always use `defineAction` with a Zod `schema:`** for input validation. The framework validates automatically and returns clear error messages for invalid input. This prevents malicious or malformed input from reaching your code. The legacy `parseArgs()` format has no runtime validation — use it only for internal/dev scripts, not user-facing actions.
-- **Never construct SQL with string concatenation** — use the `db-exec`/`db-query` tools which parameterize queries automatically (`?` placeholders). Drizzle ORM queries are always safe.
+- **Return structured data.** Return objects/arrays, not `JSON.stringify()`.
+- **Use `http: { method: "GET" }`** for read-only actions. Default is POST.
+- **Use `http: false`** for agent-only actions (`navigate`, `view-screen`).
 - **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.
+- **Import from `@agent-native/core`** — Don't redefine `parseArgs()` or other utilities locally.
 
 ## Common Patterns
 
-**API integration action** (e.g., image generation):
+**Read action (GET):**
 
 ```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");
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
 
-  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));
-}
+export default defineAction({
+  description: "List calendar events",
+  schema: z.object({
+    from: z.string().describe("Start date"),
+    to: z.string().describe("End date"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return await fetchEvents(args.from, args.to);
+  },
+});
 ```
 
-**Data processing action:**
+**Write action (POST, default):**
 
 ```ts
-import fs from "fs";
-import { parseArgs, fail } from "@agent-native/core";
+import { z } from "zod";
+import { defineAction } 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");
+export default defineAction({
+  description: "Log a meal",
+  schema: z.object({
+    name: z.string().describe("Meal name"),
+    calories: z.coerce.number().describe("Calorie count"),
+  }),
+  run: async (args) => {
+    // args.calories is a number — z.coerce.number() handles string-to-number conversion from HTTP
+    const meal = await insertMeal(args);
+    return meal;
+  },
+});
+```
 
-  const data = JSON.parse(fs.readFileSync(source, "utf-8")) as unknown[];
-  const result = data.map(transformItem);
-  fs.writeFileSync(source, JSON.stringify(result, null, 2));
-}
+**Agent-only action:**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Navigate the UI to a view",
+  schema: z.object({
+    view: z.string().describe("Target view"),
+  }),
+  http: false,
+  run: async (args) => {
+    await writeAppState("navigate", { command: "go", view: args.view });
+    return "Navigated";
+  },
+});
 ```
 
 ## 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.
+- **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"`).
+- **Frontend getting 405** — The action's `http.method` doesn't match the hook. Use `useActionQuery` for GET actions, `useActionMutation` for POST/PUT/DELETE.
+- **Frontend getting undefined** — Make sure the action returns structured data, not `JSON.stringify()`.
 
 ## 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
+- **storing-data** — Actions read/write data in 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
+- **adding-a-feature** — Actions are area 2 of the four-area checklist

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

@@ -1,71 +1,87 @@
 ---
 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.
+  How to keep the UI in sync with agent changes via SSE plus polling fallback.
+  Use when wiring query invalidation for new data models, debugging UI not
+  updating, or understanding jitter prevention.
 ---
 
-# Real-Time Sync (Polling)
+# Real-Time Sync
 
 ## 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.
+The UI stays in sync with agent/script changes through `useDbSync()`. In-process writes stream over `/_agent-native/events` first; `/_agent-native/poll` remains the cross-process/serverless fallback. 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.
+The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same-process writes immediately; polling bridges anything SSE cannot see, such as another serverless invocation, cron job, or external script. Every visible write increments a version counter, `useDbSync()` receives the change, and React Query invalidates the relevant caches. This is what makes database writes feel real-time without relying on aggressive polling.
 
 ## 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.
+1. **Server** increments a version counter on every database write. In-process events stream through the authenticated `/_agent-native/events` endpoint.
 
-2. **Client** polls for changes and updates per-source counters:
+2. **Client** listens for SSE/poll events and updates per-source change counters:
 
    ```ts
    import { useDbSync } from "@agent-native/core";
    useDbSync({ queryClient });
    ```
 
-3. **Templates fold a per-source counter into the relevant query key.** When the source advances, only the dependent query refetches:
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+
+3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
    ```ts
    import { useChangeVersion } from "@agent-native/core/client";
+   import { useQuery } from "@tanstack/react-query";
 
-   const v = useChangeVersion("items"); // or "settings", "dashboards", "action", etc.
-   const { data } = useQuery({
-     queryKey: ["items", v],
-     queryFn: fetchItems,
-     placeholderData: (prev) => prev,
+   const v = useChangeVersion("dashboards");
+   const dashboard = useQuery({
+     queryKey: ["dashboard", id, v],
+     queryFn: () => fetchDashboard(id),
+     placeholderData: (prev) => prev, // no flicker on refetch
    });
    ```
 
-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.
+   When the agent writes (`update-dashboard` action → server emits `source: "dashboards"`), the counter advances, the queryKey changes, and React Query refetches that one query. The old data stays on screen during the refetch thanks to `placeholderData`.
+
+   For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
+
+3. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds. If SSE is disabled or unavailable, polling continues at the normal cadence.
+
+4. When the agent writes to the database, the version increments, SSE/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 manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
 
-## Tuning refetch behavior
+## Which sources to depend on
 
-`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:
+Common sources you'll fold into query keys:
+
+| Source            | Bumped by                                                                   |
+| ----------------- | --------------------------------------------------------------------------- |
+| `action`          | The agent runner after every successful mutating action tool call           |
+| `app-state`       | Writes to `application_state` (navigation, selections, ephemeral UI state)  |
+| `settings`        | Writes to the `settings` table                                              |
+| `dashboards`      | Dashboard CRUD via `upsertDashboard` / `archiveDashboard` etc.              |
+| `analyses`        | Analysis CRUD                                                               |
+| `extensions`      | Extension CRUD                                                              |
+| `collab`          | Yjs collaborative-doc updates                                               |
+| `screen-refresh`  | Explicit `refresh-screen` agent tool call                                   |
+
+If a query reads data the agent can mutate via more than one path, depend on multiple sources with `useChangeVersions`:
 
 ```ts
-useDbSync({
-  queryClient,
-  onEvent: (data) => {
-    if (data.source === "settings") {
-      // Force a refetch even when not actively observed
-      queryClient.invalidateQueries({
-        queryKey: ["settings"],
-        refetchType: "all",
-      });
-    }
-  },
-});
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({ queryKey: ["dashboard", id, v], ... });
 ```
 
+`useChangeVersions` returns a single integer that advances whenever any of the listed sources advance.
+
+## Tuning refetch behavior
+
 To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
 
 ```ts
@@ -78,11 +94,12 @@ useQuery({
 
 ## Troubleshooting
 
-| 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.                          |
+| 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?                                                    |
+| SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
+| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
 
 ## Jitter Prevention
 
@@ -92,7 +109,7 @@ When the agent writes to application-state via script helpers (`writeAppState`,
 
 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.
+3. **Sync 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
 
@@ -113,11 +130,44 @@ The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Sou
 
 ### 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).
+Without jitter prevention, a cycle occurs: the UI writes state, sync 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).
+
+## Action Routes and Polling
+
+Action routes (`/_agent-native/actions/:name`) work with the same sync system. When a POST/PUT/DELETE action writes to the database, the version counter increments and `useDbSync` picks up the change. Frontend mutations via `useActionMutation` automatically invalidate `["action"]` query keys on success, triggering refetches of `useActionQuery` hooks.
+
+For custom apps, the best out-of-the-box path is:
+
+1. Put read actions in `actions/` with `defineAction({ http: { method: "GET" } })`.
+2. Put write actions in `actions/` with the default POST/PUT/DELETE behavior.
+3. Call reads from React with `useActionQuery` and writes with `useActionMutation`.
+
+This avoids duplicate `/api/*` JSON CRUD routes and makes agent-created records show up automatically. Raw `useQuery` can still work, but it should include `useChangeVersions(["action", "<domain-source>"])` in the query key for targeted refreshes.
+
+### Auto-emit on mutating actions
+
+The framework emits a poll event with `source: "action"` whenever any non-read-only action runs to completion — whether called via HTTP (`/_agent-native/actions/:name`) or as an agent tool call. Read-only actions (`http: { method: "GET" }` or explicit `readOnly: true`) are skipped.
+
+This means UIs don't need the agent to remember to call `refresh-screen` after every mutation. A listener like this (used in the `macros` template) will refresh after any mutating agent call:
+
+```ts
+useDbSync({
+  queryClient,
+  queryKeys: [],
+  ignoreSource: TAB_ID,
+  onEvent: (data) => {
+    if (data.requestSource === TAB_ID) return;
+    // Invalidate all useActionQuery caches so list-*, get-*, etc. refetch
+    queryClient.invalidateQueries({ queryKey: ["action"] });
+  },
+});
+```
+
+`refresh-screen` remains available for unusual cases — e.g. the agent mutated data via a path the framework can't see (external system the app mirrors), or the agent wants to pass a `scope` hint for narrower invalidation.
 
 ## 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
+- **actions** — Action routes auto-expose actions as HTTP endpoints; database writes trigger poll events
 - **self-modifying-code** — Agent code edits trigger poll events; rapid edits can cause event storms

package/src/templates/default/AGENTS.md

@@ -2,14 +2,14 @@
 
 This app follows the agent-native core philosophy: the agent and UI are equal partners. Everything the UI can do, the agent can do via actions. The agent always knows what you're looking at via application state. See the root AGENTS.md for full framework documentation.
 
-This is an **@agent-native/core** application -- the AI agent and UI share state through a SQL database, with polling for real-time sync.
+This is an **@agent-native/core** application -- the AI agent and UI share state through a SQL database, with SSE for in-process live sync and polling as the cross-process/serverless fallback.
 
 ### Core Principles
 
 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. **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.
+4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. 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
@@ -112,7 +112,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 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.
+4. **Wire UI for auto-refresh** — use `useActionQuery` / `useActionMutation` for normal CRUD. If a raw `useQuery` is unavoidable, fold `useChangeVersions([<source>, "action"])` into its key 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/src/templates/default/actions/hello.ts

@@ -1,20 +1,13 @@
-/**
- * Example script — callable via `pnpm action hello`
- *
- * Scripts export a default async function that receives CLI args.
- */
-
-import { parseArgs } from "@agent-native/core";
-import { agentChat } from "@agent-native/core";
-
-export default async function hello(args: string[]) {
-  const parsed = parseArgs(args);
-  const name = parsed.name ?? "world";
-
-  console.log(`Hello, ${name}!`);
-
-  // Example: send a message to agent chat (works in Electron context)
-  if (parsed["send-chat"] === "true") {
-    agentChat.submit(`Hello from the script system! Name: ${name}`);
-  }
-}
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return a friendly greeting.",
+  schema: z.object({
+    name: z.string().default("world").describe("Name to greet"),
+  }),
+  http: { method: "GET" },
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});