@agent-native/core 0.35.2 → 0.35.3

package/docs/content/client.md

@@ -1,6 +1,6 @@
 ---
 title: "Client"
-description: "React hooks and utilities for agent-native apps: sendToAgentChat, setContextToAgentChat, useDbSync, useAgentChatGenerating, and cn."
+description: "React hooks and utilities for agent-native apps: sendToAgentChat, optional agent chat context state, useDbSync, useAgentChatGenerating, and cn."
 ---
 
 # Client
@@ -115,59 +115,64 @@ sendToAgentChat({
 | `preset`              | `string?`   | Optional preset name for downstream consumers  |
 | `referenceImagePaths` | `string[]?` | Optional reference image paths                 |
 
-## setContextToAgentChat(opts) {#setcontexttoagentchat}
+## Agent Chat Context State (Advanced) {#agent-chat-context-state}
 
-Stage one or more hidden context nuggets in the active agent chat composer
-without submitting a message or filling the prompt text. Use this when the UI
-lets a user select app objects, rows, elements, files, or other structured data
-that should inform the next prompt, while still letting the user write the
-visible request themselves.
+The context-state APIs are optional plumbing for UI that needs two-way sync with
+staged context chips: rendering the current staged items outside the composer,
+reflecting whether an item is already attached, or providing explicit
+remove/clear controls.
 
-Each context nugget has a stable `key`. Calling `setContextToAgentChat()` again
-with the same key replaces that nugget. Calling it with a new key stacks another
-nugget. The composer shows each nugget as a removable chip, and the framework
-includes the staged context in a hidden `<context>` block only when the user
-submits the prompt.
+Do not reach for these helpers for simple "send this to the agent" or
+"prefill this draft for review" flows. Use `sendToAgentChat()` with `context`
+and `submit` for those.
 
-`addContextToAgentChat()` is an alias for the same replace-by-key behavior.
+| API                               | Use when                                                               |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `useAgentChatContext()`           | A React component needs the live staged context list                   |
+| `setAgentChatContextItem(item)`   | Imperative code should stage or replace one keyed context item         |
+| `listAgentChatContext()`          | Non-React code needs a one-time snapshot of staged context             |
+| `removeAgentChatContextItem(key)` | UI should remove one staged context item by its stable `key`           |
+| `clearAgentChatContext()`         | UI should clear all staged context, such as after a view or mode reset |
+| `refreshAgentChatContext()`       | Imperative code should re-read the latest persisted context snapshot   |
 
-```ts
-import { setContextToAgentChat } from "@agent-native/core";
-
-setContextToAgentChat({
-  key: "selected-element:.thing#hello",
-  title: "Selected Element",
-  context: [
-    "CSS selector: .thing#hello",
-    "HTML:",
-    '<button class="thing" id="hello">Buy now</button>',
-  ].join("\n"),
-});
+`useAgentChatContext()` returns `{ items, set, remove, clear, refresh }`.
 
-setContextToAgentChat({
-  key: "cart",
-  title: "Cart",
-  context: "2 items: Pro plan, extra seat",
-});
-```
+```tsx
+import { useAgentChatContext } from "@agent-native/core";
 
-If an app should only ever stage one item of a kind, reuse the same key:
+function SelectionContextButton({ record }: { record: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-record:${record.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
 
-```ts
-setContextToAgentChat({
-  key: "selected-record",
-  title: "Selected Record",
-  context: JSON.stringify(record, null, 2),
-});
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Record",
+          context: JSON.stringify(record, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
 ```
 
-Use `sendToAgentChat({ message, context, submit: true })` when the UI already
-knows the message to send immediately. Use `sendToAgentChat({ submit: false })`
-only when you want to prefill editable prompt text. Use
-`setContextToAgentChat()` when the UI should add context while leaving the
-prompt box available for the user's own request.
+`listAgentChatContext()` is for imperative code that only needs to inspect the
+current staged items once. `clearAgentChatContext()` is intentionally broad; use
+`removeAgentChatContextItem(key)` when only one selection changed.
 
-### AgentChatContextMessage {#agentchatcontextmessage}
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
 
 | Option        | Type       | Description                                            |
 | ------------- | ---------- | ------------------------------------------------------ |

package/docs/content/context-awareness.md

@@ -92,22 +92,10 @@ Use the `selection` app-state key for durable selection that should survive a mo
 Write it from the UI when the user selects, focuses, or multi-selects meaningful objects:
 
 ```tsx
-import { agentNativePath } from "@agent-native/core/client";
+import { setClientAppState } from "@agent-native/core/client";
 
 async function syncSelection(selection: unknown | null) {
-  const url = agentNativePath("/_agent-native/application-state/selection");
-
-  if (!selection) {
-    await fetch(url, { method: "DELETE", keepalive: true });
-    return;
-  }
-
-  await fetch(url, {
-    method: "PUT",
-    keepalive: true,
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(selection),
-  });
+  await setClientAppState("selection", selection, { keepalive: true });
 }
 ```
 
@@ -134,17 +122,15 @@ The production agent injects that key into the next turn as immediate selection
 Custom editors can write the same key when their selection is not represented by native browser selection:
 
 ```tsx
-await fetch(
-  agentNativePath("/_agent-native/application-state/pending-selection-context"),
+import { setClientAppState } from "@agent-native/core/client";
+
+await setClientAppState(
+  "pending-selection-context",
   {
-    method: "PUT",
-    keepalive: true,
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      text: selectedMarkdown,
-      capturedAt: Date.now(),
-    }),
+    text: selectedMarkdown,
+    capturedAt: Date.now(),
   },
+  { keepalive: true },
 );
 ```
 
@@ -275,15 +261,17 @@ The UI polls for this command and navigates when it appears:
 
 ```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 res = await fetch("/_agent-native/application-state/navigate");
-    if (!res.ok) return null;
-    const data = await res.json();
+    const data = await readClientAppState<NavigateCommand>("navigate");
     if (data) {
-      // Delete the one-shot command after reading
-      fetch("/_agent-native/application-state/navigate", { method: "DELETE" });
+      await deleteClientAppState("navigate");
       return data;
     }
     return null;
@@ -308,17 +296,14 @@ The `use-navigation-state.ts` hook syncs routes to application-state on every na
 // app/hooks/use-navigation-state.ts
 import { useEffect } from "react";
 import { useLocation } from "react-router";
+import { setClientAppState } from "@agent-native/core/client";
 
 export function useNavigationState() {
   const location = useLocation();
 
   useEffect(() => {
     const state = deriveNavigationState(location.pathname);
-    fetch("/_agent-native/application-state/navigation", {
-      method: "PUT",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(state),
-    }).catch(() => {});
+    setClientAppState("navigation", state).catch(() => {});
   }, [location.pathname]);
 }
 ```
@@ -329,6 +314,8 @@ The `deriveNavigationState()` function is template-specific -- it parses the URL
 
 When the agent writes to application-state, the sync system might cause the UI to refetch data it just wrote. This creates jitter. The solution is source tagging:
 
+Use `setClientAppState`, `writeClientAppState`, `readClientAppState`, and `deleteClientAppState` from `@agent-native/core/client` for browser-side application-state access. 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";

package/docs/content/creating-templates.md

@@ -133,7 +133,7 @@ Use the [Database](/docs/database) and [Security](/docs/security) docs before ad
 
 ## Define Operations As Actions {#actions}
 
-Actions are the single source of truth for app behavior. The agent calls them as tools, the frontend calls them through hooks or HTTP, and other apps can reach them through MCP/A2A.
+Actions are the single source of truth for app behavior. The agent calls them as tools, the frontend calls them through hooks, and other apps can reach them through MCP/A2A.
 
 ```ts
 // actions/create-project.ts
@@ -196,7 +196,7 @@ export function AppSync() {
 }
 ```
 
-**The agent-native promise: agent writes show up in the UI without a manual refresh.** `useActionQuery` is the easy path — every hook refetches when a mutating action emits `source: "action"`. If you reach for raw `useQuery` with a custom key (e.g. for a non-action HTTP endpoint, integration status, etc.), fold the per-source counter into the queryKey for targeted refreshes:
+**The agent-native promise: agent writes show up in the UI without a manual refresh.** `useActionQuery` is the easy path — every hook refetches when a mutating action emits `source: "action"`. If you reach for raw `useQuery` with a custom key (for example, a low-level client helper that reads integration status), fold the per-source counter into the queryKey for targeted refreshes:
 
 ```tsx
 import { useChangeVersions } from "@agent-native/core/client";

package/docs/content/key-concepts.md

@@ -45,7 +45,7 @@ Six rules govern the architecture:
 
 Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the six rules, you inherit:
 
-- **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend mutation (`useActionMutation("name")`), an HTTP endpoint at `/_agent-native/actions/:name`, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation.
+- **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation.
 - **A full workspace per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Workspace](/docs/workspace).
 - **Drop-in React components.** `<AgentPanel />` and `<AgentSidebar />` render chat + workspace anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).
 - **Live sync between agent and UI.** Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below.
@@ -151,8 +151,8 @@ export default defineAction({
 One `defineAction()` call gives you:
 
 - **Agent tool** — the agent sees it with the zod-derived JSON Schema and can call it.
-- **Frontend mutation** — `useActionMutation("fetch-data")` with full TypeScript inference.
-- **HTTP endpoint** — `POST /_agent-native/actions/fetch-data` (auto-mounted).
+- **Frontend hook** — `useActionMutation("fetch-data")` with full TypeScript inference.
+- **Framework transport** — auto-mounted behind the client hooks.
 - **CLI** — `pnpm action fetch-data --source=signups` for scripting and agent dev loops.
 - **MCP tool / A2A tool** — when MCP server or A2A is enabled, the same action shows up there too.
 

package/docs/content/sharing.md

@@ -87,7 +87,7 @@ For lists, drop a `<VisibilityBadge visibility={row.visibility} />` next to each
 
 ## Same model, agent and UI {#agent-and-ui}
 
-The framework auto-mounts these actions in every template — the agent calls them as tools, the UI calls them as HTTP endpoints:
+The framework auto-mounts these actions in every template — the agent calls them as tools, and the UI calls them through `useActionQuery` / `useActionMutation`:
 
 | Action                    | What it does                                                                                   |
 | ------------------------- | ---------------------------------------------------------------------------------------------- |

package/docs/content/template-mail.md

@@ -170,7 +170,7 @@ Routes in the UI:
 
 Mail is yours to change. Everything important lives in a handful of places — start there.
 
-**Adding an agent capability.** Add a new file under `templates/mail/actions/` using `defineAction`. Your action becomes both a CLI command (`pnpm action <name>`) and an HTTP endpoint (`/_agent-native/actions/<name>`). Look at `templates/mail/actions/star-email.ts` for a short example or `templates/mail/actions/manage-automations.ts` for one with multiple sub-actions. See the [actions](/docs/actions) docs for the full pattern.
+**Adding an agent capability.** Add a new file under `templates/mail/actions/` using `defineAction`. Your action becomes an agent tool, a CLI command (`pnpm action <name>`), and a typed frontend hook surface through `useActionQuery` / `useActionMutation`. Look at `templates/mail/actions/star-email.ts` for a short example or `templates/mail/actions/manage-automations.ts` for one with multiple sub-actions. See the [actions](/docs/actions) docs for the full pattern.
 
 **Changing the UI.** Routes are in `templates/mail/app/routes/` and components in `templates/mail/app/components/email/` and `templates/mail/app/components/layout/`. The app uses shadcn/ui primitives from `app/components/ui/` and Tabler Icons — stick to those.
 

package/docs/content/voice-input.md

@@ -47,7 +47,7 @@ If no server provider is configured at all, the route returns a 400 the composer
 - **Origin check:** same-origin only.
 - **Max size:** 25 MB.
 
-You don't need to call this directly — the composer does. But if you're building a custom input surface and want the same transcription, POST a `FormData` with an `audio` blob to the same route.
+You don't need to call this directly — the composer does. If you're building a custom input surface, first reuse the shared composer/voice client pieces from `@agent-native/core/client`. Treat this route as the low-level transport boundary for custom helpers that need to send multipart audio.
 
 ## Customizing the provider {#customizing}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.35.2",
+  "version": "0.35.3",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -40,8 +40,12 @@
     "./db/schema": "./dist/db/schema.js",
     "./db/drizzle-config": "./dist/db/drizzle-config.js",
     "./client": "./dist/client/index.js",
+    "./client/AgentPanel": "./dist/client/AgentPanel.js",
+    "./client/application-state": "./dist/client/application-state.js",
+    "./client/api-path": "./dist/client/api-path.js",
     "./client/observability": "./dist/client/observability/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",
+    "./client/settings/useBuilderStatus": "./dist/client/settings/useBuilderStatus.js",
     "./onboarding": "./dist/onboarding/index.js",
     "./shared": "./dist/shared/index.js",
     "./scripts": "./dist/scripts/index.js",

package/src/templates/default/AGENTS.md

@@ -7,7 +7,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 ### Core Principles
 
 1. **Shared SQL database** -- All app state lives in SQL. Local SQLite at `data/app.db` is the zero-setup dev fallback; deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. 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()`. When UI selections should add hidden context for the user's next prompt without submitting, use `setContextToAgentChat()` with a stable `key`.
+2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`. Use `sendToAgentChat({ message, context, submit })` for simple UI handoffs and prefill/review flows. Only use the agent-chat context state helpers (`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`, `removeAgentChatContextItem`, `clearAgentChatContext`) when the UI needs two-way sync with staged context chips.
 3. **Actions for app operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`; `defineAction` also auto-exposes those operations at `/_agent-native/actions/:name` for the UI. Do not create custom REST routes that re-export actions.
 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.

package/src/templates/default/DEVELOPING.md

@@ -81,7 +81,7 @@ export default defineNitroPlugin(async (nitroApp) => {
 | `readResource`, `writeResource`              | Read/write resources (from `@agent-native/core/resources`)                 |
 | `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
 | `sendToAgentChat`                            | Send or prefill messages in the agent chat from UI (client-side)           |
-| `setContextToAgentChat`                      | Stage keyed context chips for the next agent chat prompt from UI           |
+| Agent chat context state helpers             | Optional advanced helpers for two-way sync with staged context chips       |
 | `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
 
 ## Adding a Script
@@ -102,18 +102,12 @@ sendToAgentChat({
 });
 ```
 
-To add hidden context without submitting or filling the prompt text, stage
-keyed context nuggets. Multiple nuggets stack; using the same `key` replaces the
-previous nugget.
-
-```ts
-import { setContextToAgentChat } from "@agent-native/core";
-setContextToAgentChat({
-  key: "selected-record",
-  title: "Selected Record",
-  context: JSON.stringify(record, null, 2),
-});
-```
+For most UI handoffs, pass hidden context directly with `sendToAgentChat()`. Use
+`submit: false` when the user should review the draft first. Use
+`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`,
+`removeAgentChatContextItem`, and `clearAgentChatContext` only for advanced UI
+that needs to read, mirror, stage, remove, or clear staged context chips as local
+interface state.
 
 **From scripts:**
 

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

@@ -14,10 +14,12 @@ agent should know.
 - All AI/LLM behavior goes through the app's agent chat. UI and server code
   must not call model providers, AI SDK `generateText()` / `streamText()`, or
   other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
-  work. When selected UI data should become hidden context for the user's next
-  prompt without submitting anything, use `setContextToAgentChat()` with a
-  stable `key`. Read `.agents/skills/delegate-to-agent/SKILL.md` before
-  building agent-driven UI or "AI" features.
+  work, including hidden `context` and `submit: false` prefill/review flows.
+  Only use `useAgentChatContext`, `setAgentChatContextItem`,
+  `listAgentChatContext`, `removeAgentChatContextItem`, and
+  `clearAgentChatContext` when UI needs two-way sync with staged context chips.
+  Read `.agents/skills/delegate-to-agent/SKILL.md` before building agent-driven
+  UI or "AI" features.
 - Put shared code in `packages/shared` only when multiple apps need it.
 - Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
 - Store shared runtime configuration in the workspace root `.env`; use

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

@@ -11,10 +11,12 @@ coding agents can discover the same workspace-wide guidance from the root.
 - All AI/LLM behavior goes through the app's agent chat. UI and server code
   must not call model providers, AI SDK `generateText()` / `streamText()`, or
   other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
-  work. When selected UI data should become hidden context for the user's next
-  prompt without submitting anything, use `setContextToAgentChat()` with a
-  stable `key`. Read `packages/shared/.agents/skills/delegate-to-agent/SKILL.md`
-  before building agent-driven UI or "AI" features.
+  work, including hidden `context` and `submit: false` prefill/review flows.
+  Only use `useAgentChatContext`, `setAgentChatContextItem`,
+  `listAgentChatContext`, `removeAgentChatContextItem`, and
+  `clearAgentChatContext` when UI needs two-way sync with staged context chips.
+  Read `packages/shared/.agents/skills/delegate-to-agent/SKILL.md` before
+  building agent-driven UI or "AI" features.
 
 ## Workspace Resources