@agent-native/core 0.37.2 → 0.38.0

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

@@ -2,8 +2,10 @@
 name: context-awareness
 description: >-
   How the agent knows what the user is looking at. Use when exposing UI state to
-  the agent, implementing view-screen or navigate scripts, wiring navigation
+  the agent, implementing view-screen or navigate actions, wiring navigation
   state, or debugging agent context issues.
+metadata:
+  internal: true
 ---
 
 # Context Awareness
@@ -16,34 +18,31 @@ The agent must always know what the user is currently viewing. The UI writes nav
 
 Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
 
-## The Three Patterns
+## The Core Patterns
 
 ### 1. Navigation State (`navigation` key)
 
-The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on and what item is selected.
+The UI writes a `navigation` key to application-state on every route change. This tells the agent the semantic screen state: view, open IDs, active tab, and focused object.
 
-**UI side** — the `use-navigation-state.ts` hook:
+**UI side** — `useNavigationState`, an app-owned hook (not a framework import) that every template ships at `app/hooks/use-navigation-state.ts`. It is a thin wrapper around the framework primitive `useAgentRouteState`, handling both directions: writing `navigation` on route change and consuming the agent's `navigate` command.
 
-```ts
+```tsx
 // app/hooks/use-navigation-state.ts
-import { useEffect, useCallback } from "react";
-import { useLocation } from "react-router";
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
 
 export function useNavigationState() {
-  const location = useLocation();
-
-  // Sync route to app-state on every navigation
-  useEffect(() => {
-    const state = deriveNavigationState(location.pathname);
-    fetch("/_agent-native/application-state/navigation", {
-      method: "PUT",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(state),
-    }).catch(() => {});
-  }, [location.pathname]);
-
-  // ... also listen for navigate commands (pattern 3)
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      // Optional semantic alias. Raw query params are already exposed in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
 }
 ```
 
@@ -60,12 +59,24 @@ const navigation = await readAppState("navigation");
 
 - `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
 - Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
-- Filter state — active search, label, or category filters
-- Any selection — focused item, selected text range, active tab
+- Semantic aliases — label names, active tabs, focused row, or stable filter names the agent should reason about
+- Any durable selection — focused item, selected text range, active tab
+
+Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.
+
+### 2. Current URL (`__url__` key)
 
-### 2. The `view-screen` Script
+`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.
 
-Every template should have a `view-screen` script. It reads navigation state, fetches the relevant data from the API, and returns a snapshot of what the user sees. This is the agent's eyes.
+Use this for URL-reachable filters and search state. The agent can update it with the built-in `set-search-params` and `set-url-path` tools; do not duplicate the whole query string into `navigation`.
+
+### 3. The `view-screen` Script
+
+Every template should have a `view-screen` script. It reads navigation state,
+the current URL if filters matter, and selection state. It fetches the relevant
+data from existing domain actions, shared data helpers, or Drizzle queries, and
+returns a snapshot of what the user sees. Do not add REST wrappers just so
+`view-screen` can read app data. This is the agent's eyes.
 
 ```ts
 // actions/view-screen.ts
@@ -73,8 +84,15 @@ import { readAppState } from "@agent-native/core/application-state";
 
 export default async function main() {
   const navigation = await readAppState("navigation");
+  const url = (await readAppState("__url__")) as {
+    searchParams?: Record<string, string>;
+  } | null;
   const screen: Record<string, unknown> = { navigation };
 
+  if (url?.searchParams) {
+    screen.activeFilters = url.searchParams;
+  }
+
   // Fetch data based on what the user is viewing
   if (navigation?.view === "inbox") {
     const emails = await fetchEmailList(navigation.label);
@@ -91,7 +109,7 @@ export default async function main() {
 
 **Navigation state is auto-injected into every user message as a `<current-screen>` block**, so the agent always has basic context without calling any tool. The `view-screen` action is still useful when you need a richer snapshot (e.g., fetching the full email thread or form data for the current view).
 
-### 3. The `navigate` Script
+### 4. The `navigate` Script
 
 The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
 
@@ -104,74 +122,56 @@ import { writeAppState } from "@agent-native/core/application-state";
 await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
 ```
 
-**UI side** — the hook polls for the command:
-
-```ts
-const { data: navCommand } = useQuery({
-  queryKey: ["navigate-command"],
-  queryFn: async () => {
-    const res = await fetch("/_agent-native/application-state/navigate");
-    if (!res.ok) return null;
-    const data = await res.json();
-    if (data) {
-      // Delete the one-shot command after reading
-      fetch("/_agent-native/application-state/navigate", { method: "DELETE" });
-      return data;
-    }
-    return null;
-  },
-  staleTime: 2_000,
-});
-
-useEffect(() => {
-  if (navCommand) {
-    router.navigate(buildPath(navCommand));
-  }
-}, [navCommand]);
-```
+**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
+dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
 
 ## Jitter Prevention
 
 When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
 
+Client code can use `useAgentRouteState`, `useSemanticNavigationState`, `setClientAppState`, `writeClientAppState`, `readClientAppState`, and `deleteClientAppState` from `@agent-native/core/client` instead of hand-written `fetch` calls. Pass `{ requestSource: TAB_ID }` on UI writes when pairing with `useDbSync({ ignoreSource: TAB_ID })`; pass `{ keepalive: true }` for short-lived writes such as selection cleanup during unload.
+
 ```ts
 // app/root.tsx
 import { TAB_ID } from "@/lib/tab-id";
 
 useDbSync({
   queryClient,
-  queryKeys: ["app-state", "settings"],
   ignoreSource: TAB_ID,  // ignore events from this tab's own writes
 });
 ```
 
-The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When polling, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
+The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When processing sync events, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
 
 ## Gold-Standard Example: Mail Template
 
-The mail template demonstrates all three patterns working together:
+The mail template demonstrates these patterns working together:
 
 **Navigation state shape:**
 ```json
-{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "search": "budget", "label": "important" }
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "label": "important" }
 ```
 
 **view-screen output:**
 - Reads navigation state
-- Fetches email list matching current view/search/label filters
+- Reads `__url__` if URL query filters matter
+- Fetches email list matching current view/filter state
 - Fetches thread messages if a thread is open
 - Returns everything as a single JSON snapshot
 
 **navigate command:**
 - `{ "view": "starred" }` — switch to starred view
 - `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+- For pure query-filter changes, use `set-search-params`
 
 ## Do
 
 - Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
-- Include all relevant selection state in the `navigation` key (view, item IDs, filters)
+- Include semantic route state in the `navigation` key (view, item IDs, active tab, focused row)
+- Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
 - Update `view-screen` when adding new features — it should return data for every view
-- Use the one-shot `navigate` command pattern for agent-initiated navigation
+- Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
+- Use the one-shot `navigate` command pattern for semantic agent-initiated navigation
 - Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
 
 ## Don't
@@ -180,11 +180,12 @@ The mail template demonstrates all three patterns working together:
 - Don't hardcode navigation paths in scripts — read the current state and branch
 - Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
 - Don't ignore the `<current-screen>` block — it tells you where the user is
-- Don't store fetched data in navigation state — it holds IDs and filters only. The `view-screen` script fetches the actual data.
+- Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
+- Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.
 
 ## Related Skills
 
 - **adding-a-feature** — Context awareness is area 4 of the four-area checklist
-- **real-time-sync** — How polling and `useDbSync` deliver app-state changes to the UI
-- **scripts** — How to create the `view-screen` and `navigate` scripts
+- **real-time-sync** — How `useDbSync` delivers app-state changes to the UI
+- **actions** — How to create the `view-screen` and `navigate` actions
 - **storing-data** — Application-state is one of the core SQL stores

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

@@ -0,0 +1,47 @@
+---
+name: context-xray
+description: >-
+  Inspect and manage the live agent context window with Context X-Ray. Use when
+  context is getting large, the user asks what is in context, or stale tool
+  results/files should be pinned, evicted, restored, or reported by an external
+  host.
+metadata:
+  internal: true
+---
+
+# Context X-Ray
+
+Context X-Ray is the framework's context garbage-collection surface. It shows
+the current thread's model-bound context as content-derived segments with token
+counts, then lets the user or agent pin, evict, or restore individual segments.
+
+## Actions
+
+| Action | When to use |
+| --- | --- |
+| `context-manifest-get` | Read the current manifest for a thread. Returns token totals, segment status, source, and whether changes are enforceable. |
+| `context-pin` | Preserve a segment across future compaction/model calls. Use for task specs, acceptance criteria, user constraints, and other durable context. |
+| `context-evict` | Exclude a stale or irrelevant segment from future model calls. Eviction is reversible and never deletes chat history. |
+| `context-restore` | Undo a pin, evict, or summarize directive for a segment. |
+| `context-report` | External hosts can report their visible context inventory. These manifests are advisory unless Agent-Native owns the emitted content. |
+
+## Rules
+
+- Never evict or summarize protected segments. The manifest marks active-turn
+  user/tool/thinking context as `protected`.
+- Prefer pinning the user's task, requirements, and decisions before evicting
+  large stale tool results.
+- Eviction excludes content from future model calls; it does not delete the
+  canonical transcript or files.
+- In external/advisory mode, be honest: recorded directives are intent for the
+  host except for Agent-Native-originated content we can actually withhold.
+- If token counts are estimated, describe reclaim as approximate.
+
+## Typical Flow
+
+1. Call `context-manifest-get` with the active `threadId`.
+2. Sort segments by `tokenCount` and inspect large stale `Tool results` or
+   `Files read` entries.
+3. Call `context-pin` for essential specs or user instructions.
+4. Call `context-evict` for large irrelevant segments.
+5. Offer `context-restore` if the user wants undo.

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

@@ -4,6 +4,8 @@ description: >-
   How to create new skills for an agent-native app. Use when adding a new
   skill, documenting a pattern the agent should follow, or creating reusable
   guidance for the agent.
+metadata:
+  internal: true
 ---
 
 # Create a Skill
@@ -148,6 +150,32 @@ description: >-
 - Workflow/generator skills: verb-noun (`create-skill`, `capture-learnings`).
 - The directory name must match the `name` in frontmatter.
 
+## Skill Scope (runtime vs dev)
+
+An optional `scope` frontmatter field controls which agent loads the skill:
+
+- `both` (default when omitted) — loaded by the in-app runtime agent. Use for
+  any skill the runtime agent should follow.
+- `runtime` — loaded only by the in-app runtime agent.
+- `dev` — meant for the human's coding agent (e.g. Claude Code) only. **Excluded
+  from the runtime agent everywhere**: not in the system-prompt skills block and
+  not in `docs-search` results.
+
+```markdown
+---
+name: release-checklist
+description: >-
+  Steps for cutting a release. Use when preparing or publishing a new version.
+scope: dev
+---
+```
+
+Leave `scope` off for normal skills — the default (`both`) keeps them loading at
+runtime, so this is fully backward compatible. To make a dev-only skill visible
+to your coding agent but hidden from the runtime agent, mark it `scope: dev` and
+optionally mirror it under `.claude/skills/<name>/SKILL.md` (Claude Code reads
+`.claude/skills/` independently of the runtime's `.agents/skills/`).
+
 ## Tips
 
 - **Keep descriptions under 40 words** — they load into context on every

package/dist/templates/workspace-core/.agents/skills/delegate-to-agent/SKILL.md

@@ -5,6 +5,8 @@ description: >-
   from UI or scripts to the agent, when a user asks for agent behavior or
   LLM-powered features, when tempted to add inline LLM calls, or when sending
   messages to the agent from application code.
+metadata:
+  internal: true
 ---
 
 # Delegate All AI to the Agent
@@ -124,6 +126,55 @@ Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck",
 
 If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
 
+## Delegating to a Sub-Agent (Agent Teams)
+
+`sendToAgentChat()` delegates from app code _to_ the agent. The other axis of
+delegation is the agent handing work _to a sub-agent_ through the Agent Teams
+run-manager. The main chat stays the orchestrator: it spawns sub-agents, then
+reads and integrates their results.
+
+### When to spawn a sub-agent vs do it yourself
+
+- **Do it yourself** when the work is small, on the critical path, or tightly
+  coupled to what you're already doing. Sub-agent overhead and coordination risk
+  outweigh the benefit.
+- **Spawn a sub-agent** for a self-contained unit of work that can run
+  independently — a disjoint investigation, an isolated implementation slice, a
+  long-running search — especially when it frees the main thread to keep
+  orchestrating.
+
+### Briefing contract
+
+Every sub-agent brief must specify four things, or the sub-agent will guess:
+
+- **Objective** — the one concrete outcome it owns, in a sentence.
+- **Context** — the facts it needs (paths, prior findings, constraints) so it
+  doesn't re-derive them.
+- **Output** — the exact shape you want back (a summary, a file edited, a list
+  of paths, a yes/no with rationale).
+- **Boundaries** — what it must NOT touch (files, branches, side effects) and
+  when to stop and report rather than push forward.
+
+### Fan-out discipline
+
+- **Default to a single sub-agent.** Most delegation is one focused task.
+- **Spawn multiple only for genuinely independent units** that don't share state
+  or files. Never parallelize coupled work — if B needs A's output, run them in
+  sequence.
+- **Cap parallel fan-out at ~3.** More sub-agents means more synthesis cost and
+  more chance of conflicting edits to the same area.
+
+### Synthesis discipline
+
+- **Read every result** before concluding — don't act on the first one back.
+- **Reconcile conflicts** between sub-agent findings explicitly; decide which is
+  right rather than averaging or ignoring.
+- **Integrate into one answer.** The main thread produces the single coherent
+  result; it never just forwards raw sub-agent transcripts to the user.
+
+Background sub-agents must use the core run-manager / Agent Teams infrastructure
+rather than ad-hoc LLM calls.
+
 ## Don't
 
 - Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
@@ -157,7 +208,7 @@ See the **a2a-protocol** skill for the full pattern.
 ## Related Skills
 
 - **a2a-protocol** — When the work goes to a different agent, not the local one
-- **scripts** — The agent invokes scripts via `pnpm action <name>` to perform complex operations
+- **actions** — The agent invokes actions via `pnpm action <name>` to perform complex operations
 - **self-modifying-code** — The agent operates through the chat bridge to make code changes
 - **storing-data** — The agent writes results to the database after processing requests
 - **real-time-sync** — The UI updates automatically when the agent writes data

package/dist/templates/workspace-core/.agents/skills/extension-points/SKILL.md

@@ -6,6 +6,8 @@ description: >-
   custom widget to an app surface (e.g. "add a sticky-note widget to my mail
   contact sidebar"), when wiring an ExtensionSlot in a template, or when
   marking an extension as installable into a slot.
+metadata:
+  internal: true
 ---
 
 # Extension Points