@agent-native/core 0.36.0 → 0.37.1

package/docs/content/context-awareness.md

@@ -11,13 +11,14 @@ How the agent knows what the user is looking at -- and how the agent can control
 
 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. With context awareness, the user can click a row, highlight a paragraph, select a slide element, or press Cmd+I, then say "summarize this" and the agent already knows what "this" means.
 
-Five patterns solve this:
+Six patterns solve this:
 
 1. **Navigation state** -- the UI writes a `navigation` key to application-state on every route change
-2. **Selection state** -- the UI writes a `selection` key when the user focuses, selects, or multi-selects something meaningful
-3. **`view-screen`** -- an action that reads application state, fetches contextual data, and returns a snapshot of what the user sees
-4. **Prompt handoff** -- UI controls call `sendToAgentChat()` when a click should become an agent turn
-5. **`navigate`** -- a one-shot command from the agent that tells the UI where to go
+2. **Current URL** -- the framework writes `__url__` so query params are visible and editable by the agent
+3. **Selection state** -- the UI writes a `selection` key when the user focuses, selects, or multi-selects something meaningful
+4. **`view-screen`** -- an action that reads application state, fetches contextual data, and returns a snapshot of what the user sees
+5. **Prompt handoff** -- UI controls call `sendToAgentChat()` when a click should become an agent turn
+6. **`navigate`** -- a one-shot command from the agent that tells the UI where to go
 
 ## Context layers {#context-layers}
 
@@ -25,25 +26,26 @@ Use different context channels for different jobs:
 
 | Layer                                     | Owner             | Use it for                                                                 |
 | ----------------------------------------- | ----------------- | -------------------------------------------------------------------------- |
-| `navigation` app-state key                | UI                | Current route, view, open record, filters, active tab                      |
+| `navigation` app-state key                | UI                | Semantic route state: current view, open record, active tab, stable IDs    |
+| `__url__` app-state key                   | Framework UI      | Current pathname, search string, hash, and parsed URL query params         |
+| `__set_url__` app-state key               | Agent / framework | One-shot URL edits from `set-search-params` and `set-url-path`             |
 | `selection` app-state key                 | UI                | Durable semantic selection: rows, blocks, shapes, assets, messages         |
 | `pending-selection-context` app-state key | UI / `AgentPanel` | One-shot selected text attached to the next chat turn, usually from Cmd+I  |
 | `view-screen` action                      | Agent             | Hydrating the app-state keys into real records and screen summaries        |
 | `sendToAgentChat()`                       | UI                | Turning a click, command, comment pin, or selected item into a chat prompt |
 | `navigate` app-state key                  | Agent             | Asking the UI to move to another route or focus another object             |
 
-The short version: app state tells the agent what the user is looking at, `view-screen` turns that state into useful data, and `sendToAgentChat()` turns UI intent into a chat message when the user clicks a command.
+The short version: URL query params are the source of truth for shareable filters, `navigation` stores semantic IDs and view names, `view-screen` turns those state layers into useful data, and `sendToAgentChat()` turns UI intent into a chat message when the user clicks a command.
 
 ## Navigation state {#navigation-state}
 
-The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on, what item is open, and which filters shape the visible list.
+The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on, what item is open, and which semantic UI state matters.
 
 ```json
 {
   "view": "inbox",
   "threadId": "thread-123",
   "focusedEmailId": "msg-456",
-  "search": "budget",
   "label": "important"
 }
 ```
@@ -52,10 +54,10 @@ What to include in navigation state:
 
 - `view` -- the current page/section, such as "inbox", "form-builder", or "dashboard"
 - Item IDs -- the selected/open item, such as `threadId` or `formId`
-- Filter state -- active search, label, or category filters
+- Semantic aliases -- active tab, label name, or other stable app concepts that help the agent reason
 - Light focus state -- focused row, active tab, current panel
 
-Keep `navigation` small and URL-like. It should identify the current screen, not duplicate whole records. Fetch records in `view-screen` so the agent always gets fresh data.
+Keep `navigation` small and semantic. It should identify the current screen, not duplicate whole records or mirror every query param. Fetch records in `view-screen` so the agent always gets fresh data.
 
 The agent reads this before acting:
 
@@ -66,6 +68,44 @@ const navigation = await readAppState("navigation");
 // { view: "inbox", threadId: "thread-123", label: "important" }
 ```
 
+## Current URL and filters {#current-url}
+
+`AgentPanel` automatically syncs the current React Router URL into the `__url__` application-state key. The built-in agent includes it in every turn as a `<current-url>` block:
+
+```txt
+<current-url>
+pathname: /adhoc/revenue
+search: ?f_region=west&q=renewal
+searchParams:
+  f_region: west
+  q: renewal
+</current-url>
+```
+
+This is the canonical layer for shareable filter state. If the user can copy a URL and come back to the same filtered list, the filter belongs in the query string. The agent can change those filters with the built-in `set-search-params` tool:
+
+```txt
+set-search-params({ "params": { "f_region": "east", "q": null } })
+```
+
+Use `navigation` only for semantic aliases that help `view-screen` fetch or summarize the right data. A dashboard might keep `navigation.dashboardId` while `__url__.searchParams` owns `f_region`, `f_dateStart`, and `q`.
+
+When `view-screen` returns a richer snapshot, it can copy important URL filters into a friendly `activeFilters` object:
+
+```ts
+const url = (await readAppState("__url__")) as {
+  searchParams?: Record<string, string>;
+} | null;
+
+if (url?.searchParams) {
+  screen.activeFilters = Object.fromEntries(
+    Object.entries(url.searchParams).filter(
+      ([key, value]) => key.startsWith("f_") && value,
+    ),
+  );
+}
+```
+
 ## Selection state {#selection-state}
 
 Selection is semantic UI state. It is how "the chart I clicked", "these three rows", "this slide title", or "the current email draft range" becomes model-visible context.
@@ -257,58 +297,60 @@ import { writeAppState } from "@agent-native/core/application-state";
 await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
 ```
 
-The UI polls for this command and navigates when it appears:
+The UI should consume these commands through `useAgentRouteState`, which handles command polling, tab-scoped fallback keys, duplicate-command protection, and delete-after-read:
 
-```ts
-// UI side -- poll for navigate commands
-import {
-  deleteClientAppState,
-  readClientAppState,
-} from "@agent-native/core/client";
-
-const { data: navCommand } = useQuery({
-  queryKey: ["navigate-command"],
-  queryFn: async () => {
-    const data = await readClientAppState<NavigateCommand>("navigate");
-    if (data) {
-      await deleteClientAppState("navigate");
-      return data;
-    }
-    return null;
-  },
-  staleTime: 2_000,
-});
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
 
-useEffect(() => {
-  if (navCommand) {
-    router.navigate(buildPath(navCommand));
-  }
-}, [navCommand]);
+interface NavigationState {
+  view: "inbox" | "thread";
+  threadId?: string;
+}
+
+export function useNavigationState() {
+  useAgentRouteState<NavigationState>({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname }) => {
+      const match = pathname.match(/^\/thread\/([^/]+)/);
+      return match ? { view: "thread", threadId: match[1] } : { view: "inbox" };
+    },
+    getCommandPath: (command) =>
+      command.view === "thread" && command.threadId
+        ? `/thread/${command.threadId}`
+        : "/",
+  });
+}
 ```
 
 The `navigation` key belongs to the UI -- the agent should never write to it directly. Instead, the agent writes to `navigate`, and the UI performs the actual navigation, which then updates `navigation`.
 
 ## useNavigationState hook {#use-navigation-state}
 
-The `use-navigation-state.ts` hook syncs routes to application-state on every navigation:
+The `use-navigation-state.ts` hook is usually a thin wrapper around `useAgentRouteState`. Template code supplies the app-specific route mapping; core owns application-state writes, command reads/deletes, request-source headers, and duplicate-command prevention.
 
-```ts
+```tsx
 // app/hooks/use-navigation-state.ts
-import { useEffect } from "react";
-import { useLocation } from "react-router";
-import { setClientAppState } from "@agent-native/core/client";
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
 
 export function useNavigationState() {
-  const location = useLocation();
-
-  useEffect(() => {
-    const state = deriveNavigationState(location.pathname);
-    setClientAppState("navigation", state).catch(() => {});
-  }, [location.pathname]);
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      // Optional semantic alias. Raw query params are still visible in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
 }
 ```
 
-The `deriveNavigationState()` function is template-specific -- it parses the URL path and extracts the view, item IDs, and filters relevant to your app.
+For non-router state channels, use the lower-level `useSemanticNavigationState`. It takes a ready-made `state`, an ordered list of `navigationKeys`/`commandKeys`, and an `onCommand` callback, but does not import or assume React Router.
 
 ## Jitter prevention {#jitter-prevention}
 

package/docs/content/creating-templates.md

@@ -215,10 +215,31 @@ Common sources: `"action"` (every successful agent action — the reliable fallb
 
 Application state is how the agent knows what the user is seeing. At minimum, add:
 
-- A UI hook that writes `navigation` state when routes, selected records, filters, or editor selections change.
+- A UI hook that writes semantic `navigation` state when routes, selected records, active tabs, or editor selections change.
 - A `view-screen` action that reads that state and returns the current screen snapshot.
 - A `navigate` action that writes a one-shot `navigate` command for the UI to consume.
 
+Use `useAgentRouteState` for the UI hook so application-state writes, tab-scoped command reads, delete-after-read, and duplicate-command protection stay consistent:
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
+}
+```
+
+Keep shareable filters in URL query params. The framework exposes them to the agent as `<current-url>` and the built-in agent can change them with `set-search-params`; `navigation` should hold semantic IDs and aliases, not a second copy of the full query string.
+
 ```ts
 // actions/navigate.ts
 import { defineAction } from "@agent-native/core";

package/docs/content/workspace.md

@@ -139,7 +139,7 @@ Change how the agent behaves, in 60 seconds.
 
 ## How the Agent Uses Resources {#how-the-agent-uses-resources}
 
-The agent has built-in tools for managing resources: `resource-list`, `resource-read`, `resource-effective`, `resource-write`, and `resource-delete`. These are available in both Code mode and App mode.
+The built-in app agent manages resources with the unified `resources` tool: use `action: "list"`, `"read"`, `"effective"`, `"write"`, `"promote"`, or `"delete"`. External CLI/code agents can use the equivalent `pnpm action resource-*` commands.
 
 At the start of every conversation, the agent automatically reads:
 
@@ -182,7 +182,7 @@ Both normal chat and integration-triggered agent runs load these instruction res
 
 ### Reference Resources {#reference-resources}
 
-Put reusable company context under `context/`: personas, positioning, messaging, product facts, customer proof points, brand guidelines, competitive notes, and similar material. The agent sees an index of workspace and shared reference resources and reads the relevant file with `resource-read` when a task may depend on it. Use `resource-effective --path "context/brand.md"` when you need to see whether a workspace default is overridden by an organization/app or personal resource.
+Put reusable company context under `context/`: personas, positioning, messaging, product facts, customer proof points, brand guidelines, competitive notes, and similar material. The agent sees an index of workspace and shared reference resources and reads the relevant file with the `resources` tool (`action: "read"`) when a task may depend on it. Use `resources` with `action: "effective"` and `path: "context/brand.md"` when you need to see whether a workspace default is overridden by an organization/app or personal resource.
 
 Examples:
 
@@ -440,7 +440,7 @@ What shows up depends on the mode:
 
 ## / Slash Commands {#slash-commands}
 
-Type `/` at the start of a line to invoke a skill. A dropdown shows available skills with their names and descriptions. Selecting a skill adds it as an inline chip, and its content is included as context when the message is sent.
+Type `/` at the start of a line to invoke a skill. A dropdown shows available skills with their names and descriptions. Selecting a skill adds it as an inline chip, and its content is included as context when the message is sent when the backend can resolve it; otherwise the agent receives the exact skill path and reads it with the appropriate resource or file tool.
 
 What shows up depends on the mode:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -43,6 +43,7 @@
     "./client/AgentPanel": "./dist/client/AgentPanel.js",
     "./client/application-state": "./dist/client/application-state.js",
     "./client/api-path": "./dist/client/api-path.js",
+    "./client/route-state": "./dist/client/route-state.js",
     "./client/observability": "./dist/client/observability/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",
     "./client/settings/useBuilderStatus": "./dist/client/settings/useBuilderStatus.js",

package/src/templates/default/AGENTS.md

@@ -37,14 +37,16 @@ Resources are SQL-backed persistent files for notes, learnings, and context.
 1. **`AGENTS.md`** -- inherited workspace defaults, app/team instructions, and user-specific context.
 2. **`LEARNINGS.md`** -- user preferences, corrections, and patterns. Read personal and shared scopes.
 
-**Update `LEARNINGS.md` when you learn something important.**
+**Update `LEARNINGS.md` when you learn something important.** Built-in app
+chat agents use the `resources` tool with the `action` argument. External CLI
+agents can use the equivalent `pnpm action resource-*` commands.
 
-| Action            | Args                                                        | Purpose                 |
-| ----------------- | ----------------------------------------------------------- | ----------------------- |
-| `resource-read`   | `--path <path> [--scope personal\|shared]`                  | Read a resource         |
-| `resource-write`  | `--path <path> --content <text> [--scope personal\|shared]` | Write/update a resource |
-| `resource-list`   | `[--prefix <path>] [--scope personal\|shared\|all]`         | List resources          |
-| `resource-delete` | `--path <path> [--scope personal\|shared]`                  | Delete a resource       |
+| Built-in agent tool call                                                | CLI equivalent                                                                         | Purpose                 |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------- |
+| `resources` with `action: "read"`, `path`, optional `scope`             | `pnpm action resource-read --path <path> [--scope personal\|shared]`                   | Read a resource         |
+| `resources` with `action: "write"`, `path`, `content`, optional `scope` | `pnpm action resource-write --path <path> --content <text> [--scope personal\|shared]` | Write/update a resource |
+| `resources` with `action: "list"`, optional `prefix`/`scope`            | `pnpm action resource-list [--prefix <path>] [--scope personal\|shared\|all]`          | List resources          |
+| `resources` with `action: "delete"`, `path`, optional `scope`           | `pnpm action resource-delete --path <path> [--scope personal\|shared]`                 | Delete a resource       |
 
 ## Application State
 
@@ -57,6 +59,12 @@ Ephemeral UI state is stored in the SQL `application_state` table, accessed via
 
 The `navigation` key is written by the UI whenever the route changes. The `navigate` key is a one-shot command: the agent writes it, the UI reads and executes the navigation, then deletes it.
 
+UI code should use `useAgentRouteState` / `useSemanticNavigationState` from
+`@agent-native/core/client` for navigation sync instead of hand-written
+`fetch("/_agent-native/application-state/...")` calls. Keep shareable filters
+in URL query params; the framework exposes them as `<current-url>` and the
+built-in agent can update them with `set-search-params`.
+
 ## Mounted Workspace Routing
 
 This app may be mounted under `/<app-id>` in a workspace. Inside app source, React Router paths are app-local: use `<Link to="/review">` and `navigate("/review")`, not `/<app-id>/review`. The workspace gateway and `APP_BASE_PATH` add the mounted prefix in the browser; hardcoding it inside React Router links causes doubled URLs such as `/<app-id>/<app-id>/review`.
@@ -123,7 +131,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 **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
+1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes with `useAgentRouteState`
 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; do not create REST wrappers around those actions
 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.

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

@@ -1,10 +1,7 @@
-import { useEffect, useRef } from "react";
-import { useLocation, useNavigate } from "react-router";
-import { useQuery, useQueryClient } from "@tanstack/react-query";
 import {
-  agentNativePath,
   appBasePath,
   appPath,
+  useAgentRouteState,
 } from "@agent-native/core/client";
 import { TAB_ID } from "../lib/tab-id";
 
@@ -18,79 +15,16 @@ export interface NavigationState {
 }
 
 export function useNavigationState() {
-  const location = useLocation();
-  const navigate = useNavigate();
-  const qc = useQueryClient();
-
-  useEffect(() => {
-    const state: NavigationState = {
-      view: viewFromPath(location.pathname),
-      path: appPath(location.pathname),
-    };
-
-    fetch(agentNativePath("/_agent-native/application-state/navigation"), {
-      method: "PUT",
-      keepalive: true,
-      headers: {
-        "Content-Type": "application/json",
-        "X-Request-Source": TAB_ID,
-      },
-      body: JSON.stringify(state),
-    }).catch(() => {});
-  }, [location.pathname]);
-
-  // 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(
-        agentNativePath("/_agent-native/application-state/navigate"),
-      );
-      if (!res.ok) return null;
-      const data = await res.json();
-      return data ?? null;
-    },
-    refetchInterval: 2_000,
+  useAgentRouteState<NavigationState>({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, search, hash }) => ({
+      view: viewFromPath(pathname),
+      path: appPath(`${pathname}${search}${hash}`),
+    }),
+    getCommandPath: (command) =>
+      routerPath(command.path || pathFromView(command.view)),
   });
-
-  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",
-          "X-Request-Source": TAB_ID,
-        },
-      }).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",
-        "X-Request-Source": TAB_ID,
-      },
-    }).catch(() => {});
-
-    const path = routerPath(cmd.path || pathFromView(cmd.view));
-    navigate(path);
-    qc.setQueryData(["navigate-command"], null);
-  }, [navCommand, navigate, qc]);
 }
 
 function viewFromPath(pathname: string): string {