@agent-native/core 0.46.0 → 0.48.1

package/docs/content/dispatch.md

@@ -7,9 +7,9 @@ description: "The workspace control plane: secrets vault, integration hub, cross
 
 Dispatch is the central app that sits in front of every other app in your workspace and handles secrets, integrations, messaging, and cross-app delegation. It is the **workspace control plane** — the single agent your team talks to, the single place credentials live, and the single router that decides which specialist app should handle a given request.
 
-Without Dispatch, every app in a multi-app workspace ends up re-implementing the same plumbing: its own Slack bot, its own secret store, its own scheduled jobs, its own copy of the workspace's instructions. Rotating one API key turns into ten redeployments. Adding a new policy turns into ten copy-pastes. Dispatch centralizes all of that in one app so the others stay focused on their domain.
+> **Dispatch the template vs. `@agent-native/dispatch` the package.** This page covers the Dispatch app/template concept — what it does and why you'd want it. The `@agent-native/dispatch` npm package is the separately published runtime that bundles the Dispatch template's server logic (vault, integrations, destinations, scheduled jobs, and cross-app delegation) as a drop-in package for workspaces that extend it. For the scaffolded app itself (routes, screens, agent guide), see the [Dispatch template](/docs/template-dispatch).
 
-> Dispatch is shipped as a first-party template. This page covers the **concept** — what it is, why you'd want it, and how it fits into a workspace. For the scaffolded app itself (routes, screens, agent guide), see the [Dispatch template](/docs/template-dispatch).
+Without Dispatch, every app in a multi-app workspace ends up re-implementing the same plumbing: its own Slack bot, its own secret store, its own scheduled jobs, its own copy of the workspace's instructions. Rotating one API key turns into ten redeployments. Adding a new policy turns into ten copy-pastes. Dispatch centralizes all of that in one app so the others stay focused on their domain.
 
 ## When you want Dispatch {#when}
 
@@ -68,50 +68,24 @@ Dispatch gateway is the lower-friction path.
 
 ### Workspace resources
 
-Skills, guardrail instructions, agent profiles, and reference resources can be authored once in Dispatch and inherited by the rest of the workspace. Resources with **All apps** scope are global: Dispatch stores them once at workspace scope, and every app agent reads them at runtime. They are not copied into each app, and there is no manual workspace-resource sync step. App shared resources and personal resources can override or narrow the workspace defaults locally. Selected resources use explicit per-app grants for app-specific exceptions.
-
-Use the canonical paths to control how agents consume them:
-
-- `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails loaded by every app agent
-- `skills/<slug>/SKILL.md` for on-demand skills available through `/` commands and the prompt skill index
-- `context/<slug>.md` for brand, persona, positioning, messaging, company facts, and other reference material the agent reads when relevant
-- `agents/<slug>.md` for reusable custom agent profiles
-- `mcp-servers/<slug>.json` for HTTP MCP servers that should add external tools to granted app agents
-
-Starter global resources usually look like:
-
-```text
-context/company.md
-context/brand.md
-context/messaging.md
-instructions/guardrails.md
-skills/company-voice/SKILL.md
-```
+Skills, guardrail instructions, agent profiles, and reference resources can be authored once in Dispatch and inherited by the rest of the workspace. Resources with **All apps** scope are global: Dispatch stores them once at workspace scope, and every app agent reads them at runtime. They are not copied into each app, and there is no manual workspace-resource sync step. App shared resources and personal resources can override or narrow the workspace defaults locally.
 
-Set these to **All apps** when every app should inherit the same company facts, brand rules, messaging, safety constraints, and customer-facing writing style. Use selected-app grants only for resources that are genuinely app-specific.
+See [Workspace — Global resources](/docs/workspace#global-resources) for the canonical path table, starter pack, and override model.
 
 MCP server resources use JSON and are intentionally HTTP-only. Store tokens in
 Dispatch Vault, grant or sync those keys to the target apps, and reference them
 from headers with `${keys.NAME}` so the raw credential never lives in the
 resource body.
 
-The **Resources** page highlights this starter pack in a Global context section so admins can quickly see which files exist, whether they are scoped to all apps, restore missing starter files without overwriting existing ones, and edit their contents. Expand any resource to preview its effective runtime stack for a selected app/user: workspace default, organization/app override, then personal override. Each app card also has a **Context** view that shows exactly what that app receives: inherited workspace resources, selected grants, and auto-loaded instructions. Use a resource row's **Stack** control to inspect which layer wins for that app.
-
-This is how a team-wide change ("always use British English in customer-facing replies") or a shared brand guideline propagates without editing ten repos.
+The **Resources** page highlights the recommended starter pack so admins can quickly see which files exist, restore missing starter files without overwriting existing ones, and edit their contents. Expand any resource to preview its effective runtime stack for a selected app/user. Each app card also has a **Context** view that shows exactly what that app receives.
 
 ### Dreams
 
 Dispatch Dreams review prior agent runs, feedback, evals, and repeated failures to propose durable improvements. A dream report is a review surface, not a silent rewrite: it can suggest personal memory updates, stale-memory cleanup, shared `LEARNINGS.md` edits, workspace instruction/skill/knowledge/agent resources, or recurring jobs, and each proposal links back to the runs that justify it. Shared instructions and team-wide resources require review before they are applied, especially when the evidence came from inbound Slack, email, Telegram, WhatsApp, or web content.
 
-Before proposing a write, Dreams compare the evidence against the personal memory index, existing `memory/*.md` notes, and shared `LEARNINGS.md`. If a lesson is already captured, the report records that it was skipped; if a related personal memory looks stale, the proposal targets that existing note instead of creating a duplicate. Dream reports deduplicate repeated evidence by thread, signal type, and normalized quote, strip injected context from correction detection, and summarize raw eval/tool rows into readable bullets. If a pass finds signals but creates no proposals, guardrail notes explain which evidence was suppressed.
-
-Use Dreams as the workspace's offline reflection loop: "what did agents keep getting wrong this week?", "what should we remember?", and "which repeated workflow should become a skill or scheduled job?"
-
-Start from the **Dreams** tab in Dispatch. Run a manual pass first, open a proposal review sheet to compare the current target with the proposed content and source evidence, then apply only the changes you want to keep. Once the reports are consistently useful, Dispatch can create a recurring dream job that keeps producing proposals without auto-applying shared or instruction-level changes. Workspace-instruction proposals require durable evidence from at least two threads or two source apps, while eval-only noise, account setup issues, quota limits, and single-app UI wording corrections remain out of all-app instructions.
+Before proposing a write, Dreams compare the evidence against the personal memory index, existing `memory/*.md` notes, and shared `LEARNINGS.md`. If a lesson is already captured, the report records that it was skipped; if a related personal memory looks stale, the proposal targets that existing note instead of creating a duplicate.
 
-When a workspace has several thread-debug sources, Dreams can scan them together with `sourceId: "all"` or an explicit `sourceIds` list. Each source gets its own timeout, start stagger, concurrency cap, per-thread timeout, and persisted health row, so a slow or unavailable production database produces a partial result instead of blocking the whole dream pass.
-
-Recurring dream settings are stored at user or org scope and can be edited from the Dreams settings sheet. They control the cron schedule, source selection, per-source timeout, source concurrency, source start stagger, per-thread timeout, candidate limit, and minimum candidate threshold. The default recurring shape is a weekly all-source review that writes proposals only; applying shared or workspace-resource proposals still goes through review and approval.
+Start from the **Dreams** tab in Dispatch. Run a manual pass first, open a proposal review sheet to compare the current target with the proposed content and source evidence, then apply only the changes you want to keep. Once the reports are consistently useful, Dispatch can create a recurring dream job that keeps producing proposals without auto-applying shared or instruction-level changes.
 
 ### Approval flow
 
@@ -125,7 +99,7 @@ Walk through one example end-to-end. A user DMs the bot: _"summarize last week's
 2. **Fresh processor execution.** The processor endpoint runs in a brand-new function execution with its own full timeout. It atomically claims the task and starts the agent loop.
 3. **Dispatch agent decides.** The agent reads the message, recognizes "signups" as an analytics intent, and invokes `call-agent` against the analytics app's [A2A endpoint](/docs/a2a-protocol). The actual SQL work runs over there.
 4. **Reply posted in thread.** The analytics agent returns a result. Dispatch formats it and posts back into the same Slack thread the user wrote in, using the linked identity if there is one (so the agent acts with the requester's permissions, not the workspace owner's).
-5. **Recovery if anything dies.** If the processor crashes mid-flight — A2A timeout, downstream agent error, function freeze — a retry job sweeps stuck tasks every 60 seconds and re-fires the processor. Up to three attempts before the task is marked `failed`. The user still gets a reply on the next sweep instead of the message disappearing into the void.
+5. **Recovery if anything dies.** If the processor crashes mid-flight — A2A timeout, downstream agent error, function freeze — a retry job sweeps stuck tasks every 60 seconds and re-fires the processor. Up to three attempts before the task is marked `failed`.
 
 The same flow applies for email, Telegram, and WhatsApp — only the adapter changes.
 
@@ -137,8 +111,6 @@ The whole pipeline is built to survive on every serverless host (Netlify, Vercel
 - **A2A continuation polling.** When Dispatch delegates to another app, it polls the downstream task with a bounded timeout. If the downstream agent takes too long or crashes, Dispatch records the continuation and the retry job picks it up — the user's Slack reply still arrives.
 - **Auto-signed cross-app A2A.** Hosted multi-app workspaces auto-generate per-app A2A credentials at deploy time, so apps in the same workspace can call each other without you ever pasting a JWT secret. Dispatch's agent-discovery layer reads those creds from the workspace database so newly added apps appear as callable peers automatically.
 
-This is the hardened reliability story. Conceptually: every step that crosses a network or a process boundary is recoverable.
-
 ## Setup {#setup}
 
 Three short steps:
@@ -155,4 +127,4 @@ Then add credentials to the vault and (optionally) author global workspace resou
 - [Messaging](/docs/messaging) — connecting Slack, email, Telegram, WhatsApp
 - [A2A Protocol](/docs/a2a-protocol) — how cross-app delegation works under the hood
 - [Multi-App Workspace](/docs/multi-app-workspace) — the deployment shape Dispatch is built for
-- [Workspace Management](/docs/workspace-management) — git/GitHub governance that pairs with Dispatch's runtime governance
+- [Workspace Governance](/docs/workspace-management) — git/GitHub governance that pairs with Dispatch's runtime governance

package/docs/content/drop-in-agent.md

@@ -5,9 +5,13 @@ description: "Mount the agent chat + workspace into any React app with <AgentPan
 
 # Drop-in Agent
 
+> **Developer page.** This page is for developers embedding the agent into a React app. For the end-user experience of working with the agent, see [Using Your Agent](/docs/using-your-agent).
+
 You don't need to build agent-native from scratch. The agent chat, workspace tab, CLI terminal, voice input, and all the related infrastructure ship as a handful of React components you drop into any app.
 
 > **Prerequisite:** the server has to be running the `agent-chat-plugin` (it auto-mounts in every template). If you're starting from scratch, see [Server](/docs/server).
+>
+> Need the public API map instead of a tutorial? See [Component API](/docs/components).
 
 ## The components at a glance {#components}
 
@@ -16,6 +20,8 @@ You don't need to build agent-native from scratch. The agent chat, workspace tab
 | `<AgentSidebar>`      | Wraps your app, adds a toggleable side panel containing the full agent | You want the agent available alongside your app on every screen |
 | `<AgentToggleButton>` | Opens/closes `<AgentSidebar>` (put it in your header)                  | Pair with `<AgentSidebar>`                                      |
 | `<AgentPanel>`        | The raw panel itself — chat + CLI + workspace tabs                     | You want full control over layout, or a dedicated agent page    |
+| `<AgentChatSurface>`  | A pre-wired panel/page chat surface                                    | You want chat without the sidebar wrapper                       |
+| `<AssistantChat>`     | Lower-level chat renderer with composer/history hooks                  | You need custom chrome around the standard conversation UI      |
 | `sendToAgentChat()`   | Programmatically send a message to the chat                            | A button that hands work to the agent instead of running inline |
 | `useActionMutation()` | Typesafe frontend wrapper around an action                             | The UI needs to run the same operation an agent tool would run  |
 
@@ -124,6 +130,22 @@ import { sendToAgentChat } from "@agent-native/core/client";
 
 `sendToAgentChat` returns a stable `tabId` you can use to track the chat run.
 
+For silent work, pair `newTab`, `background`, and `openSidebar: false`:
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+This is still a full agent run with tools, actions, thread state, and run
+tracking. It simply does not steal focus from the user's current sidebar state.
+
 When the same route is embedded as an MCP App, submitted
 `sendToAgentChat()` calls are forwarded to the host chat where supported; see
 [Client](/docs/client#sendtoagentchat) for the MCP App bridge behavior.
@@ -136,14 +158,113 @@ import { useSendToAgentChat } from "@agent-native/core/client";
 const { send, isGenerating } = useSendToAgentChat();
 ```
 
+## Custom chat UI layers {#custom-chat-ui}
+
+If you do not want `<AgentSidebar>`, choose the lowest layer that still lets the
+framework own the agent runtime:
+
+- **`<AgentChatSurface>`** — use this for a dedicated chat route or embedded
+  panel. It keeps the standard chat/runtime wiring without the sidebar wrapper.
+- **`<AssistantChat>`** — use this when you want to own surrounding chrome,
+  tabs, headers, empty states, or composer slots while keeping the standard
+  conversation renderer and adapter.
+- **`@agent-native/core/client/chat`** — use this focused subpath when building
+  a custom surface from pieces: `AssistantChat`, `MultiTabAssistantChat`,
+  `useChatThreads`, `AgentConversation`, composer exports, and the standard
+  chat adapters.
+- **`@agent-native/core/client/composer`** — use this for the chat field itself:
+  `PromptComposer` for the complete field, or `TiptapComposer` only when you
+  are already wiring assistant-ui primitives yourself.
+- **`@agent-native/core/client/conversation`** — use this for transcript
+  rendering without the full chat runtime.
+- **`createAgentChatAdapter()`** — use this only when building a custom
+  assistant-ui runtime. It connects to the same `/_agent-native/agent-chat`
+  stream and preserves run-manager recovery, attachments, model selection, and
+  thread metadata.
+
+Avoid posting directly to `/_agent-native/agent-chat` from product UI. If a
+lower-level helper is missing for a real custom surface, add that named helper
+first so client code does not learn a second, ad hoc transport.
+
+### Build your own sidebar from pieces {#build-your-own-sidebar}
+
+The stock sidebar is optional. A custom sidebar can keep your own layout and
+still reuse the framework runtime:
+
+```tsx
+import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";
+
+function MyAgentSidebar({ projectSlug }: { projectSlug: string }) {
+  const threads = useChatThreads(undefined, projectSlug);
+  const threadId = threads.activeThreadId ?? undefined;
+
+  return (
+    <aside className="grid h-full grid-cols-[220px_1fr]">
+      <ThreadList
+        threads={threads.threads}
+        activeThreadId={threadId}
+        onSelect={threads.switchThread}
+      />
+      <AssistantChat threadId={threadId} />
+    </aside>
+  );
+}
+```
+
+If you only need the field for a custom runtime, use the composer subpath:
+
+```tsx
+import { PromptComposer } from "@agent-native/core/client/composer";
+
+<PromptComposer
+  placeholder="Ask the agent..."
+  onSubmit={async (text, files, references, options) => {
+    await sendToYourRuntime({ text, files, references, options });
+  }}
+/>;
+```
+
+`TiptapComposer` is also public, but it is intentionally lower-level: render it
+inside an assistant-ui thread/composer context. Most app code should use
+`PromptComposer` or `AssistantChat`.
+
+### Raw text completion escape hatch {#raw-text-completion}
+
+For narrow server-side transforms that intentionally do not need tools, chat
+history, run state, or user steering, use `completeText()` from
+`@agent-native/core/server`. Keep it server-only and wrap user-facing usage in
+an action so the UI and agent share the same operation.
+
+```ts
+import { defineAction } from "@agent-native/core";
+import { completeText } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Classify a message",
+  run: async ({ body }: { body: string }) => {
+    const result = await completeText({
+      systemPrompt: "Return exactly one label.",
+      input: body,
+      maxOutputTokens: 12,
+      temperature: 0,
+    });
+    return { label: result.text.trim() };
+  },
+});
+```
+
+If the work needs actions, files, database writes, auditability, or multi-step
+reasoning, use `sendToAgentChat()` instead, optionally with `background: true`
+and `openSidebar: false`.
+
 ## Typesafe actions from the UI: `useActionMutation()` {#use-action-mutation}
 
-When the UI needs to run the same operation an agent tool would run — the fourth rung of the [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
+When the UI needs to run the same operation an agent tool would run — rung 3 of the [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
 
 ```tsx
 import { useActionMutation } from "@agent-native/core/client";
 
-const { mutate, isPending } = useActionMutation("replyToEmail");
+const { mutate, isPending } = useActionMutation("reply-to-email");
 
 <Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
   Send Reply

package/docs/content/embedding-sdk.md

@@ -5,6 +5,41 @@ description: "Embed an Agent-Native sidecar into an existing SaaS app with page
 
 # Embedding SDK
 
+## Installation {#installation}
+
+```bash
+pnpm add @agent-native/embedding
+```
+
+Subpath exports from `@agent-native/embedding`:
+
+| Import path                        | What it provides                                                                        |
+| ---------------------------------- | --------------------------------------------------------------------------------------- |
+| `@agent-native/embedding`          | `EmbeddedApp` picker component, `getA2AUrl`, `getMcpUrl`, `sendMessage` (streaming A2A) |
+| `@agent-native/embedding/react`    | React-specific hooks and components                                                     |
+| `@agent-native/embedding/bridge`   | `announceEmbeddedAppReady`, `sendEmbeddedAppMessage` — used inside the embedded app     |
+| `@agent-native/embedding/agent`    | Agent endpoint helpers                                                                  |
+| `@agent-native/embedding/protocol` | Protocol types                                                                          |
+
+For the **batteries-included embedded mode** (full sidecar with actions, database, and agent chat), install `@agent-native/core` on the server and use `createAgentNativeEmbeddedPlugin`:
+
+```bash
+pnpm add @agent-native/core
+```
+
+## Choosing a mode {#choosing-a-mode}
+
+| Mode                                 | Use it when                                                                                         | Package                                                  |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **EmbeddedApp picker**               | Launching a full Agent-Native app as a focused iframe (asset picker, form builder, approval panel). | `@agent-native/embedding`                                |
+| **Batteries-included server plugin** | Adding a durable agent sidecar with its own database and actions to your existing SaaS app.         | `@agent-native/core` + `createAgentNativeEmbeddedPlugin` |
+| **`<AgentNative>` host component**   | Client-side: rendering the agent sidecar panel in your React app shell with live page context.      | `@agent-native/core/client`                              |
+| **Extension slot**                   | Embedding a sandboxed mini-app (extension) inside an existing agent-native template.                | `@agent-native/core` extensions system                   |
+
+The CLAW-style host bridge described below uses the batteries-included plugin (server) + the `<AgentNativeEmbedded>` component (client). It is the recommended default when you want the agent to see and operate on the page the user is already using.
+
+---
+
 The embedding SDK is for the CLAW-style shape: keep your existing SaaS app, add a durable agent sidecar, and let that agent see and operate on the page the user is already using.
 
 Use it when you want an assistant that can:

package/docs/content/extensions.md

@@ -151,7 +151,7 @@ Inside the iframe sandbox, every extension has these helpers on `window`:
 | `extensionData.get(collection, id, opts?)`       | Get a single item                                         | `extensionData.get('notes', 'note-1')`                    |
 | `extensionData.remove(collection, id, opts?)`    | Delete a persisted item                                   | `extensionData.remove('notes', 'note-1')`                 |
 
-Two rules of thumb:
+Three rules of thumb:
 
 - **Prefer `appAction` over `dbQuery`.** Actions are the template's official surface — they handle access control, scoping, and validation for you. Reach for raw SQL only when no action fits.
 - **Use `appAction` for template data.** Extension `appFetch` is limited to framework `/_agent-native/*` endpoints; template `/api/*` routes are blocked by the iframe bridge.
@@ -215,7 +215,7 @@ In practice you don't run those three commands by hand. Just say "pin this widge
 
 > **Slots are an _added_ capability, not a prerequisite.** Plenty of useful extensions never get installed into a slot — they live happily on their own page. Reach for slots when the widget needs to be _next to_ what the user is looking at in the host template.
 
-For deeper detail on slots — how to declare them in your template, how the context contract works, how installs are scoped — see the `extension-points` skill.
+For deeper detail on slots — how to declare them in your template, how the context contract works, how installs are scoped — see the `extension-points` skill. Skills ship inside every scaffolded template under `.agents/skills/`; see [Skills Guide](/docs/skills-guide) for how they work.
 
 ## Sharing {#sharing}