@agent-native/core 0.152.1 → 0.153.0

package/corpus/templates/macros/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,206 @@
+---
+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 actions, wiring navigation
+  state, or debugging agent context issues.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Context Awareness
+
+## Rule
+
+The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.
+
+## Why
+
+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 Core Patterns
+
+### 1. Navigation State (`navigation` key)
+
+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** — `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.
+
+```tsx
+// app/hooks/use-navigation-state.ts
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
+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),
+      // 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 ?? "/",
+  });
+}
+```
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- 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.
+
+Keep `application_state` values small. Do not store pasted files, base64 images,
+recording chunks, screenshots, or other large blobs in navigation or app-state
+keys; upload them and store only a URL or storage handle.
+
+### 2. Current URL (`__url__` key)
+
+`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.
+
+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
+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);
+    screen.emailList = emails;
+  }
+  if (navigation?.threadId) {
+    const thread = await fetchThread(navigation.threadId);
+    screen.thread = thread;
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+**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).
+
+### 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.
+
+**Agent side:**
+
+```ts
+import { writeAppState } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
+```
+
+**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
+dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
+
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
+## 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,
+  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 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 these patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- 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 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 `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — always check navigation state
+- 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 write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- 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 `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/corpus/templates/macros/.agents/skills/delegate-to-agent/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: delegate-to-agent
+description: >-
+  How to delegate all AI work to the agent chat. Use when delegating AI work
+  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.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Delegate All AI to the Agent
+
+## Rule
+
+The app's default AI surface is the agent chat. Any user-facing work that asks
+the model to research, analyze, generate, recommend, synthesize, or reason over
+multiple steps must start or continue in the AgentSidebar so users can see,
+steer, and audit the work. UI buttons use `sendToAgentChat()` with
+`openSidebar: true`, and follow-up or revision text belongs in that same thread
+instead of a second app-local textbox.
+
+Actions are tools, not alternate AI runtimes. Keep them deterministic and
+focused: provider reads, validation, deterministic transforms, CRUD, and
+persistence are good action work. Let the agent orchestrate several such tools
+when the workflow is AI-shaped or user-steerable. Server-side one-shot model
+calls are a rare escape hatch for narrow text transforms only; use
+`completeText()` from `@agent-native/core/server` only when the work
+intentionally does not need tools, chat history, run state, side effects, or
+user steering.
+
+## Why
+
+The agent is the single AI interface. It has context about the full project, can read/write any file, and can run scripts. Inline LLM calls bypass this — they create a shadow AI that doesn't know what the agent knows and can't coordinate with it.
+
+## How
+
+**From the UI (client):**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+sendToAgentChat({
+  message: "Generate a summary of this document",
+  context: documentContent, // optional hidden context (not shown in chat UI)
+  submit: true, // auto-submit to the agent
+  openSidebar: true,
+});
+```
+
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
+**From the UI, in the background:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+This is still a full agent run: tools, actions, thread state, and run tracking
+all remain active. It simply does not focus or open the sidebar.
+
+Use this silent form only for explicitly background or system-initiated work.
+It is not the default for a user clicking an AI-labeled button; visible work
+should open the sidebar so the user can follow and redirect the run.
+
+**From scripts (Node):**
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+agentChat.submit("Process the uploaded images and create thumbnails");
+```
+
+**For narrow server-side text transforms:**
+
+```ts
+import { completeText } from "@agent-native/core/server";
+
+const result = await completeText({
+  systemPrompt: "Return exactly one sentiment label.",
+  input: messageBody,
+  maxOutputTokens: 12,
+  temperature: 0,
+});
+```
+
+If the narrow exception is exposed to the UI, wrap it in an action so the UI
+and agent share the same operation. Keep it clearly non-conversational and do
+not call provider SDKs directly.
+
+**From the UI, detecting when agent is done:**
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client/agent-chat";
+
+function MyComponent() {
+  const isGenerating = useAgentChatGenerating();
+  // Show loading state while agent is working
+}
+```
+
+## `submit` vs Prefill
+
+The `submit` option controls whether the message is sent automatically or placed in the chat input for user review:
+
+| `submit` value | Behavior                                | Use when                                                                            |
+| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `true`         | Auto-submits to the agent immediately   | Routine operations with clear intent; keep `openSidebar: true` for visible work |
+| `false`        | Prefills the AgentSidebar composer      | Review, edit, or add detail before the run; use the existing sidebar thread   |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                       |
+
+```ts
+// Auto-submit: routine operation
+sendToAgentChat({ message: "Update the project summary", submit: true });
+
+// Prefill: let user review before sending
+sendToAgentChat({
+  message: "Delete all projects older than 30 days",
+  submit: false,
+  openSidebar: true,
+});
+```
+
+## Capture user input in the sidebar
+
+The AgentSidebar composer is the default prompt surface. When a button needs
+the user to describe what to create, prefill that same composer and let the
+user edit or complete it:
+
+```tsx
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Help me create a research report from this brief:",
+      context: researchBrief,
+      submit: false,
+      openSidebar: true,
+    })
+  }
+>
+  Start in agent
+</Button>
+```
+
+Never auto-submit a generic creative prompt when the user has not said what
+they want. Auto-submit without additional input is fine when intent is
+unambiguous:
+
+- "Try to fix" on a tool error — submits the error details with a clear fix instruction
+- "Retry the last operation" after a transient failure
+- Single-purpose buttons where there is nothing meaningful for the user to add
+
+Use a Popover only for compact, structured parameters the UI must validate,
+such as a date range, target, or approval choice. Do not add a second freeform
+prompt or follow-up textbox for an AI workflow; keep the conversation and
+revisions in the AgentSidebar thread.
+
+## 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
+- Don't `import OpenAI from "openai"` in client or server code
+- Don't make direct API calls to any LLM provider
+- Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
+- Don't build "AI features" that bypass the agent chat
+- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
+- Don't use `completeText()` for workflows that need tools, database writes,
+  auditability, user steering, or multi-step reasoning. Use the agent chat
+  instead, optionally with `background: true`.
+
+## Exception
+
+Scripts may call external APIs (image generation, search, etc.) — but the AI
+reasoning and orchestration still goes through the agent. A script is a tool
+the agent uses, not a replacement for the agent.
+
+`completeText()` is allowed for small server-side transforms such as
+classification, extraction, rewriting a short string, or normalizing messy
+provider text. It deliberately runs with `tools: []` and does not create chat
+thread state.
+
+## When to Use A2A Instead
+
+`sendToAgentChat()` delegates work to the **local** agent — the one running alongside your app. When the work should go to a **different** agent entirely (e.g., asking an analytics agent for data, or a calendar agent for availability), use the A2A (agent-to-agent) protocol instead.
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// Call a different agent — not the local agent chat
+const stats = await callAgent(
+  "https://analytics.example.com",
+  "What were last week's signups?",
+  { apiKey: process.env.ANALYTICS_A2A_KEY },
+);
+```
+
+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
+- **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