@agent-native/core 0.56.1 → 0.58.0

package/docs/content/key-concepts.md

@@ -190,27 +190,27 @@ See [Context Awareness](/docs/context-awareness) for the full pattern: navigatio
 
 Agent-native supports a lot of agent-facing protocols because different hosts standardize different pieces of the same workflow. App authors should not have to choose among them or rebuild the same operation for each client. The center of gravity stays the action system.
 
-| Surface                 | Status              | What agent-native provides                                                                                                      | What you write                          |
-| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| Agent tool calling      | Shipping            | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                                   | `defineAction()`                        |
-| UI actions              | Shipping            | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                                 | The same action                         |
-| Native chat widgets     | Shipping            | Tool results with explicit widget discriminants can render native tables, charts, approvals, and setup cards in chat.           | Structured action results               |
-| HTTP and CLI            | Shipping            | Actions auto-mount at `/_agent-native/actions/:name` and run via `pnpm action <name>`.                                          | The same action                         |
-| MCP server              | Shipping            | External MCP hosts get Streamable HTTP tools, the `ask-agent` meta-tool, and optional MCP Apps resources.                       | The same action, plus optional `mcpApp` |
-| MCP OAuth               | Shipping            | Standard remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes. | Nothing per action                      |
-| MCP Apps                | Shipping            | External hosts that support app resources can render iframe/native-host widgets, with deep-link fallback elsewhere.             | Optional `mcpApp` metadata              |
-| A2A                     | Shipping            | Other agents discover the agent card and call the app over JSON-RPC tasks.                                                      | The same actions and agent config       |
-| Deep links              | Shipping            | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.                 | Optional `link` metadata                |
-| MCP clients             | Shipping            | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                          | `mcp.config.json` or settings           |
-| Instructions and skills | Shipping            | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.                | Workspace resources, not protocol glue  |
-| Agent Web               | Shipping            | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.                    | Route access plus `agentWeb` config     |
-| Extensions              | Shipping            | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                                    | Extension HTML using `appAction()`      |
-| AG-UI                   | Adapter target      | A good fit for connecting an external agent runtime to an agent-native chat/UI shell through event streams.                     | An adapter, not duplicate actions       |
-| ACP                     | Coding-agent/editor | Useful for coding agents inside editors/IDEs; not the general BYO app-chat runtime contract.                                    | Editor/agent adapter work               |
-
-The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, `mcpApp`, or an explicit native widget result only when a surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP OAuth, UI mutations, native chat widgets, CLI commands, and deep-link handoffs are adapters around that same core.
-
-Adapter horizon: [AG-UI](https://docs.ag-ui.com/introduction) is a strong fit for connecting external agent runtimes to Agent-Native chat and app shells through events. [ACP](https://zed.dev/acp) is important for coding-agent/editor interoperability, but it is not the general BYO app-agent UI contract.
+| Surface                     | Status              | What agent-native provides                                                                                                            | What you write                                    |
+| --------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Agent tool calling          | Shipping            | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                                         | `defineAction()`                                  |
+| UI actions                  | Shipping            | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                                       | The same action                                   |
+| Native chat widgets         | Shipping            | Tool results with explicit widget discriminants can render native tables, charts, and typed app results in chat.                      | Structured action results                         |
+| AgentChatRuntime connectors | Shipping            | The chat shell can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or normalized HTTP streams. | Pick a runtime helper or stream normalized events |
+| HTTP and CLI                | Shipping            | Actions auto-mount at `/_agent-native/actions/:name` and run via `pnpm action <name>`.                                                | The same action                                   |
+| MCP server                  | Shipping            | External MCP hosts get Streamable HTTP tools, the `ask-agent` meta-tool, and optional MCP Apps resources.                             | The same action, plus optional `mcpApp`           |
+| MCP OAuth                   | Shipping            | Standard remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes.       | Nothing per action                                |
+| MCP Apps                    | Shipping            | External hosts that support app resources can render iframe/native-host widgets, with deep-link fallback elsewhere.                   | Optional `mcpApp` metadata                        |
+| A2A                         | Shipping            | Other agents discover the agent card and call the app over JSON-RPC tasks.                                                            | The same actions and agent config                 |
+| Deep links                  | Shipping            | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.                       | Optional `link` metadata                          |
+| MCP clients                 | Shipping            | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                                | `mcp.config.json` or settings                     |
+| Instructions and skills     | Shipping            | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.                      | Workspace resources, not protocol glue            |
+| Agent Web                   | Shipping            | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.                          | Route access plus `agentWeb` config               |
+| Extensions                  | Shipping            | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                                          | Extension HTML using `appAction()`                |
+| ACP                         | Coding-agent/editor | Useful for coding agents inside editors/IDEs; not the general BYO app-chat runtime contract.                                          | Editor/agent adapter work                         |
+
+The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, `mcpApp`, or an explicit native widget result only when a surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP OAuth, UI mutations, native chat widgets, AgentChatRuntime connectors, CLI commands, and deep-link handoffs are adapters around that same core.
+
+Adapter horizon: [A2UI](https://a2ui.org/) is worth watching for portable generated UI across trust boundaries, but first-party Agent-Native widgets should stay explicit native renderers. [ACP](https://zed.dev/acp) is important for coding-agent/editor interoperability, but it is not the general BYO app-agent UI contract.
 
 ## Three product shapes {#three-product-shapes}
 
@@ -222,7 +222,7 @@ Those protocol adapters let the same app grow across three product shapes:
 | **Rich chat agent**   | A standalone or embedded chat can guide setup, call tools, request approvals, and render native tables/charts/results. | Agent-first workflows that still need inspectable output       |
 | **Whole application** | Chat starts central when helpful, then becomes a sidebar next to forms, dashboards, editors, calendars, or documents.  | Durable products where humans and agents share state over time |
 
-You should be able to start with the headless contract, add rich chat, and then grow a full app around the same actions and SQL state instead of rebuilding.
+You should be able to start with the headless contract, add rich chat, and then grow a full app around the same actions and SQL state instead of rebuilding. See [Agent Surfaces](/docs/agent-surfaces) for the concrete choice guide and APIs.
 
 ## Agent modifies code {#agent-modifies-code}
 
@@ -302,6 +302,7 @@ Adopting the framework is valuable mostly because of what you stop having to bui
 - **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).
+- **BYO agent chat runtimes.** The same chat UI can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or your own normalized HTTP stream. See [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes).
 - **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.
 - **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication).
 - **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).
@@ -320,5 +321,6 @@ For detailed guidance on specific patterns:
 - [Context Awareness](/docs/context-awareness) — navigation state, view-screen, navigate commands
 - [Skills Guide](/docs/skills-guide) — framework skills, domain skills, creating custom skills
 - [Native Chat UI](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture
+- [Agent Surfaces](/docs/agent-surfaces) — headless, rich chat, embedded sidecar, and full-app paths
 - [A2A Protocol](/docs/a2a-protocol) — agent-to-agent communication
 - [Multi-App Workspace](/docs/multi-app-workspace) — host many apps in one monorepo with shared auth, skills, components, and credentials

package/docs/content/mcp-apps.md

@@ -9,7 +9,7 @@ MCP Apps are the official `io.modelcontextprotocol/ui` extension that lets compa
 
 For connecting external agents and the broader MCP server setup, see [External Agents](/docs/external-agents) and [MCP Protocol](/docs/mcp-protocol). This page covers authoring MCP App resources and the embed bridge that powers them.
 
-Inside an Agent-Native app's own chat, prefer [native chat renderers](/docs/native-chat-ui) for first-party widgets such as tables, charts, setup cards, and approvals. Use MCP Apps for external/cross-host inline UI in Claude, ChatGPT, Copilot, Cursor, and other compatible hosts, with the action `link` as the universal deep-link fallback.
+Inside an Agent-Native app's own chat, prefer [native chat renderers](/docs/native-chat-ui) for first-party widgets such as tables, charts, typed results, and approval affordances. Use MCP Apps for external/cross-host inline UI in Claude, ChatGPT, Copilot, Cursor, and other compatible hosts, with the action `link` as the universal deep-link fallback.
 
 ## Authoring: optional MCP Apps UI {#mcp-apps}
 

package/docs/content/native-chat-ui.md

@@ -178,32 +178,111 @@ arbitrary query execution behind typed read actions rather than raw SQL in chat.
 
 ## BYO agent runtimes {#byo-agent-runtimes}
 
-Agent-Native ships the chat/runtime stack: thread persistence, streaming,
-attachments, tool calls, run recovery, approvals, suggestions, native widgets,
-and SQL-backed app state. In docs, `AgentChatRuntime` refers to that standard
-runtime posture, not a separate package you need to replace.
-
-For bring-your-own agent work, keep the action surface and app state as the
-contract:
-
-- Use `createAgentChatAdapter()` or the `<AssistantChat createAdapter={...} />`
-  prop when you need a custom assistant-ui transport while keeping the standard
-  chat runtime.
-- Use `PromptComposer` only when your product owns the full external runtime
-  and wants the Agent-Native composer field without the standard transcript.
-- Treat AG-UI as the likely adapter shape for external event-stream runtimes.
-  It should adapt into Agent-Native actions, context, and native renderers
-  rather than creating a second app API.
-- Treat ACP as coding-agent/editor interoperability. It is useful for IDE
-  agents, but it is not the general BYO chat runtime contract for app users.
-
-The goal is one operation model: actions, SQL state, context awareness, native
-widgets, MCP Apps, A2A, and MCP all wrap the same app capabilities instead of
-forking behavior per agent surface.
+`AgentChatRuntime` is the bring-your-own-agent contract for the chat shell. It
+lets an agent you built elsewhere stream normalized events into Agent-Native's
+conversation UI while keeping the shared composer, transcript rendering, tool
+cards, approvals, native widgets, and surrounding app layout. For how this fits
+with headless actions, embedded sidecars, and full applications, see
+[Agent Surfaces](/docs/agent-surfaces).
+
+Use the generic HTTP runtime when your agent can expose a POST endpoint that
+returns SSE or NDJSON runtime events:
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:mastra",
+  label: "Mastra",
+  endpoint: "/api/mastra/chat",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAgentToken()}`,
+  }),
+});
+
+export function SupportChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+If your endpoint already streams a common agent protocol, use the matching
+connector and skip writing a custom mapper:
+
+```ts
+import {
+  createAgUiChatRuntime,
+  createClaudeAgentChatRuntime,
+  createOpenAIAgentsChatRuntime,
+  createOpenAIResponsesChatRuntime,
+  createVercelAiChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const openAiAgentsRuntime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/openai-agents/chat",
+});
+
+const openAiResponsesRuntime = createOpenAIResponsesChatRuntime({
+  endpoint: "/api/openai-responses/chat",
+});
+
+const claudeAgentRuntime = createClaudeAgentChatRuntime({
+  endpoint: "/api/claude-agent/chat",
+});
+
+const vercelAiRuntime = createVercelAiChatRuntime({
+  endpoint: "/api/vercel-ai/chat",
+});
+
+const agUiRuntime = createAgUiChatRuntime({
+  endpoint: "/api/ag-ui/chat",
+});
+```
+
+The endpoint may stream the normalized event shape directly:
+
+```txt
+data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+For very simple agents, a JSON response `{ "text": "..." }` is accepted and
+converted into a single assistant message. For richer agents, stream
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+`usage`, `error`, and `done` events. Tool results can carry `mcpApp` or
+`chatUI` metadata, so action-declared native widgets still render without
+iframes.
+
+When you want the built-in Agent-Native transport as a runtime object, use:
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+Use `<AssistantChat createAdapter={...} />` only when you need full
+assistant-ui adapter control. Use `PromptComposer` by itself when your product
+owns the entire external transcript and only wants Agent-Native's composer
+field.
+
+OpenAI, AG-UI, Claude Agent SDK, and Vercel AI SDK streams can use the standard
+connector helpers. ACP remains coding-agent/editor interoperability, not the
+general app-chat runtime for end users. A2UI is not claimed as supported here;
+if it matures, it should adapt into this same explicit runtime/widget contract.
 
 ## Related docs {#related-docs}
 
 - [Actions](/docs/actions) — define the operations that return native widget data.
+- [Agent Surfaces](/docs/agent-surfaces) — decide whether you need headless, chat, sidecar, or full app.
 - [Drop-in Agent](/docs/drop-in-agent) — mount the standard chat runtime.
 - [Component API](/docs/components) — custom chat layers and tool renderers.
 - [MCP Apps](/docs/mcp-apps) — inline UI for external MCP hosts.

package/docs/content/plan-plugin.md

@@ -37,9 +37,35 @@ the Plan MCP connector. They write `plans/<slug>/plan.mdx` plus optional
 `canvas.mdx`, `prototype.mdx`, and `.plan-state.json`, then preview locally with:
 
 ```bash
-npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan --open
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
 ```
 
+This starts a tiny localhost bridge and opens the Plan UI against the local
+folder. (`plan local preview` runs a local Plan dev-server route instead, and
+`plan local preview --out preview.html` is a legacy escape hatch that writes a
+standalone static HTML file. `plan serve` is accepted as a short alias for
+`plan local serve`.)
+
+A few local-files-mode gotchas worth knowing:
+
+- **Use a Chromium browser.** Safari blocks the hosted HTTPS Plan page from
+  reading the `http://127.0.0.1` localhost bridge (mixed-content / private
+  network), so the page hangs on "Loading plan." On macOS `--open` already
+  prefers Chrome/Chromium/Edge/Brave; if Safari opens anyway, reopen the printed
+  URL in a Chromium browser.
+- **The served URL is written to `plans/<slug>/.plan-url`** (override with
+  `--url-file`). A backgrounded or headless agent can read that file instead of
+  scraping the long-running `serve` stdout. Treat it as a local token file and
+  do not commit it.
+- **Verify headlessly** when no browser is available:
+  `npx @agent-native/core@latest plan local verify --dir plans/<slug>` starts the
+  bridge, checks the private-network preflight and JSON payload, prints
+  diagnostics, and exits non-zero on failure — no human eyes required.
+- **Run `plan local check` first.** It validates the MDX against the Plan
+  renderer's block schema (including required fields like `checklist` item
+  `id`/`label` and `question-form` question `id`/`title`/`mode`), so authoring
+  mistakes surface before the browser handoff instead of as a stuck loader.
+
 For folders in the current repo, the direct local route includes `?path=...` so
 the local Plan app can keep browser edits saving to the repo folder. The Plan
 app uses `apps.plan.roots[0].path` in `agent-native.json` as the default place

package/docs/content/pure-agent-apps.md

@@ -5,7 +5,7 @@ description: "Apps where the agent is the whole product — open it, ask for wha
 
 # Pure-Agent Apps
 
-This is the minimal end of agent-native — for the full-UI end, start from a [template](/docs/cloneable-saas).
+This is the minimal end of agent-native — for the full-UI end, start from a [template](/docs/cloneable-saas). If you are choosing between headless, chat-first, embedded, and full-app shapes, start with [Agent Surfaces](/docs/agent-surfaces).
 
 Imagine opening an app and seeing… just a chat. No dashboard. No sidebar full of menus. No forms. You ask for what you want — "summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week" — and the agent goes off and does it. The output shows up in chat, in Slack, in your inbox, wherever it belongs.
 
@@ -90,6 +90,7 @@ Most pure-agent apps eventually want a little custom UI — not a dashboard, but
 ## What's next
 
 - [**Getting Started**](/docs/getting-started) — clone the Starter template
+- [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
 - [**Messaging the agent**](/docs/messaging) — how users talk to the agent across web, Slack, Telegram, email
 - [**Recurring Jobs**](/docs/recurring-jobs) — scheduled prompts the agent runs on its own
 - [**Dispatch**](/docs/template-dispatch) — the workspace template that's a great starting point for pure-agent apps

package/docs/content/using-your-agent.md

@@ -39,6 +39,7 @@ _For developers building the app._
 The agent isn't a separate app you tab over to. It ships as a handful of React components — a sidebar, a raw panel, and a `sendToAgentChat()` call — that you drop into any app. Render `<AgentSidebar>` to give every screen a toggleable agent, or wire a button to hand a specific task off to the chat instead of running a one-shot LLM call.
 
 → [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>`, `<AgentSidebar>`, and `sendToAgentChat()` into any React app. _(For developers building the app.)_
+→ [**Agent Surfaces**](/docs/agent-surfaces) — choose whether the workflow should be headless, chat-first, embedded, or a full app. _(For developers designing the product shape.)_
 
 ## You can go UI-light {#ui-light}
 

package/docs/content/what-is-agent-native.md

@@ -66,10 +66,10 @@ At minimum, "a UI for the agent" is an observability and management dashboard. A
 There are three useful shapes:
 
 - **Headless** — call the agent and actions from code, HTTP, CLI, MCP, or A2A.
-- **Rich chat** — give the agent a first-class chat UI with native tool widgets such as tables, charts, approvals, setup cards, and links into app views. See [Native Chat UI](/docs/native-chat-ui).
+- **Rich chat** — give the agent a first-class chat UI with native tool widgets such as tables, charts, typed results, approvals, and links into app views. See [Native Chat UI](/docs/native-chat-ui).
 - **Whole app** — put a full application around the agent, with SQL state, context awareness, deep links, and live sync so humans and agents stay in the same workspace.
 
-Agent-native is designed so those are stages, not rewrites. You can start headless, add rich chat, and grow into a full app around the same action surface.
+Agent-native is designed so those are stages, not rewrites. You can start headless, add rich chat, and grow into a full app around the same action surface. See [Agent Surfaces](/docs/agent-surfaces) for the concrete APIs behind each shape.
 
 ## Why every app benefits from an agent {#why-every-app-benefits-from-an-agent}
 
@@ -186,6 +186,7 @@ One action, many surfaces: the agent calls it as a tool, the UI calls it as a ty
 ## What's next {#whats-next}
 
 - [**Getting Started**](/docs) — pick a template and run it
+- [**Agent Surfaces**](/docs/agent-surfaces) — choose headless, rich chat, embedded sidecar, or full app
 - [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, context awareness, portability
 - [**Templates**](/docs/cloneable-saas) — templates as complete products you own
 - [**Workspace**](/docs/workspace) — the per-user customization layer (skills, memory, instructions, MCP) backed by SQL, not files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.56.1",
+  "version": "0.58.0",
   "type": "module",
   "engines": {
     "node": ">=22"