@agent-native/core 0.21.0 → 0.22.1

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

@@ -1,56 +1,24 @@
-/**
- * Navigate the UI to a view.
- *
- * Writes a navigate command to application state which the UI reads and auto-deletes.
- *
- * Usage:
- *   pnpm action navigate --view=home
- *   pnpm action navigate --path=/some/route
- *
- * Options:
- *   --view   View name to navigate to
- *   --path   URL path to navigate to
- */
-
-import { parseArgs } from "@agent-native/core";
+import { defineAction } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
-import type { ScriptTool } from "@agent-native/core";
+import { z } from "zod";
 
-export const tool: ScriptTool = {
+export default defineAction({
   description:
     "Navigate the UI to a specific view or path. Writes a navigate command to application state which the UI reads and auto-deletes.",
-  parameters: {
-    type: "object",
-    properties: {
-      view: { type: "string", description: "View name to navigate to" },
-      path: { type: "string", description: "URL path to navigate to" },
-    },
+  schema: z.object({
+    view: z.string().optional().describe("View name to navigate to"),
+    path: z.string().optional().describe("URL path to navigate to"),
+  }),
+  http: false,
+  run: async (args) => {
+    if (!args.view && !args.path) {
+      return "Error: At least --view or --path is required.";
+    }
+    const nav: Record<string, string> = {};
+    if (args.view) nav.view = args.view;
+    if (args.path) nav.path = args.path;
+    nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await writeAppState("navigate", nav);
+    return `Navigating to ${args.view || args.path}`;
   },
-};
-
-export async function run(args: Record<string, string>): Promise<string> {
-  if (!args.view && !args.path) {
-    return "Error: At least --view or --path is required.";
-  }
-  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}`;
-}
-
-export default async function main(): Promise<void> {
-  const args = parseArgs(process.argv.slice(2)) as Record<string, string>;
-  if (!args.view && !args.path) {
-    console.error(
-      "Error: At least --view or --path is required. Usage: pnpm action navigate --view=home",
-    );
-    process.exit(1);
-  }
-  const result = await run(args);
-  console.error(result);
-  console.log(JSON.stringify({ result }));
-}
+});

package/src/templates/default/actions/view-screen.ts

@@ -1,39 +1,22 @@
-/**
- * See what the user is currently looking at on screen.
- *
- * Reads and returns the current navigation state from application state.
- *
- * Usage:
- *   pnpm action view-screen
- */
-
-import { parseArgs } from "@agent-native/core";
+import { defineAction } from "@agent-native/core";
 import { readAppState } from "@agent-native/core/application-state";
-import type { ScriptTool } from "@agent-native/core";
+import { z } from "zod";
 
-export const tool: ScriptTool = {
+export default defineAction({
   description:
     "See what the user is currently looking at on screen. Returns the current navigation state. Note: basic screen context is auto-included with each message — use this tool only when you need a detailed or refreshed snapshot.",
-  parameters: {
-    type: "object",
-    properties: {},
-  },
-};
-
-export async function run(_args: Record<string, string>): Promise<string> {
-  const navigation = await readAppState("navigation");
+  schema: z.object({}),
+  http: false,
+  readOnly: true,
+  run: async () => {
+    const navigation = await readAppState("navigation");
 
-  const screen: Record<string, unknown> = {};
-  if (navigation) screen.navigation = navigation;
+    const screen: Record<string, unknown> = {};
+    if (navigation) screen.navigation = navigation;
 
-  if (Object.keys(screen).length === 0) {
-    return "No application state found. Is the app running?";
-  }
-  return JSON.stringify(screen, null, 2);
-}
-
-export default async function main(): Promise<void> {
-  const args = parseArgs(process.argv.slice(2)) as Record<string, string>;
-  const result = await run(args);
-  console.log(result);
-}
+    if (Object.keys(screen).length === 0) {
+      return "No application state found. Is the app running?";
+    }
+    return screen;
+  },
+});

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

@@ -6,6 +6,7 @@ import {
   appBasePath,
   appPath,
 } from "@agent-native/core/client";
+import { TAB_ID } from "../lib/tab-id";
 
 export interface NavigationState {
   view: string;
@@ -30,7 +31,10 @@ export function useNavigationState() {
     fetch(agentNativePath("/_agent-native/application-state/navigation"), {
       method: "PUT",
       keepalive: true,
-      headers: { "Content-Type": "application/json" },
+      headers: {
+        "Content-Type": "application/json",
+        "X-Request-Source": TAB_ID,
+      },
       body: JSON.stringify(state),
     }).catch(() => {});
   }, [location.pathname]);
@@ -65,7 +69,10 @@ export function useNavigationState() {
       // 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" },
+        headers: {
+          "X-Agent-Native-CSRF": "1",
+          "X-Request-Source": TAB_ID,
+        },
       }).catch(() => {});
       qc.setQueryData(["navigate-command"], null);
       return;
@@ -74,7 +81,10 @@ export function useNavigationState() {
 
     fetch(agentNativePath("/_agent-native/application-state/navigate"), {
       method: "DELETE",
-      headers: { "X-Agent-Native-CSRF": "1" },
+      headers: {
+        "X-Agent-Native-CSRF": "1",
+        "X-Request-Source": TAB_ID,
+      },
     }).catch(() => {});
 
     const path = routerPath(cmd.path || pathFromView(cmd.view));

package/src/templates/default/app/lib/tab-id.ts

@@ -0,0 +1 @@
+export const TAB_ID = Math.random().toString(36).slice(2, 10);

package/src/templates/default/app/root.tsx

@@ -25,6 +25,7 @@ import {
 import { Toaster } from "sonner";
 import { configureTracking } from "@agent-native/core/client";
 import { useNavigationState } from "./hooks/use-navigation-state";
+import { TAB_ID } from "./lib/tab-id";
 configureTracking({
   getDefaultProps: (_name, properties) => ({
     ...properties,
@@ -86,7 +87,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 function DbSyncSetup() {
   const qc = useQueryClient();
   useNavigationState();
-  useDbSync({ queryClient: qc, queryKeys: ["files", "data"] });
+  useDbSync({ queryClient: qc, ignoreSource: TAB_ID });
   return null;
 }
 

package/src/templates/default/app/routes/_index.tsx

@@ -1,5 +1,6 @@
 import { useTheme } from "next-themes";
 import { IconLoader2 } from "@tabler/icons-react";
+import { useActionQuery } from "@agent-native/core/client";
 
 export function meta() {
   return [{ title: "{{APP_TITLE}}" }];
@@ -20,6 +21,7 @@ export function HydrateFallback() {
 export default function IndexPage() {
   const { resolvedTheme, setTheme } = useTheme();
   const isDark = resolvedTheme === "dark";
+  const { data } = useActionQuery("hello", { name: "{{APP_TITLE}}" });
 
   return (
     <div className="flex flex-col items-center justify-center min-h-screen px-6">
@@ -38,6 +40,15 @@ export default function IndexPage() {
 
         <div className="h-px bg-border" />
 
+        <div className="rounded-lg border border-border/50 px-4 py-3 text-left">
+          <p className="text-[13px] font-medium text-foreground">
+            Action-backed data
+          </p>
+          <p className="text-[12px] text-muted-foreground mt-0.5">
+            {data?.message ?? "Loading action result..."}
+          </p>
+        </div>
+
         <div className="grid grid-cols-2 gap-3 text-left">
           <a
             href="https://agent-native.com/docs"

package/src/templates/default/package.json

@@ -17,7 +17,8 @@
     "@tabler/icons-react": "^3.40.0",
     "h3": "^2.0.1-rc.20",
     "isbot": "^5",
-    "postgres": "^3.4.9"
+    "postgres": "^3.4.9",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@react-router/dev": "^7.13.1",

package/src/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -68,7 +68,7 @@ Controls how the action is exposed as an HTTP endpoint:
 
 ### Screen Refresh (automatic)
 
-The framework auto-refreshes the UI after any successful mutating action. On completion of a non-`GET` action, the server emits a poll event 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.
+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:
 

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

@@ -27,7 +27,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   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 — that caused a request storm in production.
+   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:
 
@@ -136,6 +136,14 @@ Without jitter prevention, a cycle occurs: the UI writes state, sync detects the
 
 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.

package/src/templates/workspace-core/AGENTS.md

@@ -66,6 +66,14 @@ shadcn/ui components and `@tabler/icons-react`. Do not add `lucide-react` or
 another icon library. Read `.agents/skills/shadcn-ui/SKILL.md` before adding,
 updating, or debugging shadcn components.
 
+Normal app data must flow through actions. For CRUD that the agent can perform,
+create `defineAction` files in `actions/`, mark reads with
+`http: { method: "GET" }`, and call them from React with `useActionQuery` /
+`useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*` for
+the same data unless the route is for uploads, streaming, webhooks, OAuth, or
+another route-only concern. Action-backed UI is what makes agent-created or
+agent-edited records appear without a manual refresh.
+
 In local development, run
 `pnpm exec agent-native create <app-name> --template=<template>` from the
 workspace root. In production, Dispatch posts new-app requests to Builder

package/src/templates/workspace-root/AGENTS.md

@@ -95,6 +95,13 @@ coding agents can discover the same workspace-wide guidance from the root.
   `@tabler/icons-react`. Do not add `lucide-react` or another icon library.
   Read `packages/shared/.agents/skills/shadcn-ui/SKILL.md` before adding,
   updating, or debugging shadcn components.
+- Normal app data must flow through actions. For CRUD that the agent can
+  perform, create `defineAction` files in `actions/`, mark reads with
+  `http: { method: "GET" }`, and call them from React with `useActionQuery` /
+  `useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*`
+  for the same data unless the route is for uploads, streaming, webhooks,
+  OAuth, or another route-only concern. Action-backed UI is what makes
+  agent-created or agent-edited records appear without a manual refresh.
 - In local development, scaffold the app from the workspace root with
   `pnpm exec agent-native create <app-id> --template=<template>`. In production
   Dispatch posts the request to Builder branch creation; the Builder branch

package/dist/templates/default/server/routes/api/hello.get.ts

@@ -1,5 +0,0 @@
-import { defineEventHandler } from "h3";
-
-export default defineEventHandler(() => {
-  return { message: "Hello from your @agent-native/core app!" };
-});

package/dist/templates/default/shared/api.ts

@@ -1,6 +0,0 @@
-/**
- * Shared API types and constants.
- * Importable from both client (@shared/api) and server.
- */
-
-export const API_BASE = "/api";

package/src/templates/default/server/routes/api/hello.get.ts

@@ -1,5 +0,0 @@
-import { defineEventHandler } from "h3";
-
-export default defineEventHandler(() => {
-  return { message: "Hello from your @agent-native/core app!" };
-});

package/src/templates/default/shared/api.ts

@@ -1,6 +0,0 @@
-/**
- * Shared API types and constants.
- * Importable from both client (@shared/api) and server.
- */
-
-export const API_BASE = "/api";