@agent-native/core 0.54.1 → 0.55.0

package/docs/content/key-concepts.md

@@ -190,21 +190,40 @@ 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                 | What agent-native provides                                                                                             | What you write                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| Agent tool calling      | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                          | `defineAction()`                        |
-| UI actions              | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                        | The same action                         |
-| HTTP and CLI            | Actions auto-mount at `/_agent-native/actions/:name` and run via `pnpm action <name>`.                                 | The same action                         |
-| MCP server              | External MCP hosts get Streamable HTTP tools, the `ask-agent` meta-tool, and optional MCP Apps resources.              | The same action, plus optional `mcpApp` |
-| MCP Auth                | Remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes. | Nothing per action                      |
-| A2A                     | Other agents discover the agent card and call the app over JSON-RPC tasks.                                             | The same actions and agent config       |
-| Deep links              | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.        | Optional `link` metadata                |
-| MCP clients             | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                 | `mcp.config.json` or settings           |
-| Instructions and skills | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.       | Workspace resources, not protocol glue  |
-| Agent Web               | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.           | Route access plus `agentWeb` config     |
-| Extensions              | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                           | Extension HTML using `appAction()`      |
-
-The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, or `mcpApp` metadata only when the surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP Auth, UI mutations, CLI commands, and deep-link handoffs are adapters around that same core.
+| 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 Auth                | Shipping         | 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       |
+| A2UI                    | Watch / future   | A promising declarative UI wire format for agent-generated cross-platform widgets.                                     | A renderer/adapter when it matures      |
+| ACP                     | Coding-agent IDE | Useful for coding agents inside editors/IDEs; not the general app-agent UI 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 Auth, 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. [A2UI](https://developers.googleblog.com/introducing-a2ui-an-open-project-for-agent-driven-interfaces/) is a promising declarative UI format for generated widgets. [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}
+
+Those protocol adapters let the same app grow across three product shapes:
+
+| Shape                 | User experience                                                                                                        | Best for                                                       |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Headless agent**    | Call actions and the agent from your code, another app, MCP, A2A, HTTP, or CLI.                                        | Automation, integrations, background jobs, developer workflows |
+| **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.
 
 ## Agent modifies code {#agent-modifies-code}
 

package/docs/content/mcp-apps.md

@@ -9,6 +9,8 @@ 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 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.
+
 ## Authoring: optional MCP Apps UI {#mcp-apps}
 
 For hosts that support the MCP Apps extension, an action can also advertise an inline UI resource with `mcpApp`. This is a progressive enhancement for flows where the external agent should hand the user an interactive surface instead of only text — for example reviewing an email draft, editing a calendar invite, or choosing between generated dashboard variants.

package/docs/content/mcp-protocol.md

@@ -15,7 +15,7 @@ Every agent-native app automatically exposes a remote MCP (Model Context Protoco
 | Make your app callable over MCP (server setup, auth, tools) | This page                                |
 | Give your app's agent more tools from external MCP servers  | [MCP Clients](/docs/mcp-clients)         |
 | App-to-app delegation via JSON-RPC                          | [A2A Protocol](/docs/a2a-protocol)       |
-| Build or embed interactive MCP App UIs                      | [MCP Apps](/docs/mcp-apps)               |
+| Build or embed interactive MCP App resources                | [MCP Apps](/docs/mcp-apps)               |
 
 If your goal is to connect Claude, ChatGPT, Claude Code, Codex, Cursor, or Claude Cowork to hosted agent-native apps, start with [External Agents](/docs/external-agents). It documents the recommended single Dispatch connector at `https://dispatch.agent-native.com/_agent-native/mcp`, direct per-app URLs for isolated app access, standard remote MCP OAuth, fallback config for older clients, MCP Apps inline UIs, and deep links back into the UI. This page is the lower-level MCP server reference.
 
@@ -29,7 +29,7 @@ Key concepts:
 - **Streamable HTTP** — uses the modern MCP transport over standard HTTP (POST + SSE)
 - **Same actions** — the exact same action registry that powers agent chat and A2A
 - **`ask-agent` tool** — a meta-tool that delegates to the full agent loop for complex tasks
-- **MCP Apps** — actions can advertise inline HTML UIs through the official `io.modelcontextprotocol/ui` extension
+- **MCP Apps** — actions can advertise interactive UI resources through the official `io.modelcontextprotocol/ui` extension
 - **Standard remote MCP OAuth** — OAuth 2.1 discovery, dynamic client registration, authorization-code + PKCE, refresh-token rotation
 - **Bearer auth fallback** — uses `ACCESS_TOKEN`, `ACCESS_TOKENS`, or connect-minted JWTs for clients that cannot run OAuth
 

package/docs/content/template-plan.md

@@ -211,6 +211,7 @@ After writing the folder, the agent starts a tiny localhost bridge and opens the
 hosted Plan UI against that local-only source:
 
 ```bash
+npx @agent-native/core@latest plan local check --dir plans/<slug>
 npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
 ```
 
@@ -220,7 +221,21 @@ The page is the normal Plan viewer, but the browser fetches `plan.mdx`,
 `canvas.mdx`, `prototype.mdx`, `.plan-state.json`, and local image assets from
 the localhost bridge. Plan content is not written to the hosted database and is
 not sent through hosted Plan actions. Keep the bridge process running while you
-review; the URL is local to your machine and is not a shareable team link.
+review; the URL is local to your machine and is not a shareable team link. The
+serve command writes the open URL to `.plan-url` by default so coding agents can
+capture it without scraping long-running stdout; treat that file as local-only
+because the URL contains the bridge token, and do not commit it.
+
+On macOS, `--open` prefers Chrome/Chromium because Safari can block the hosted
+HTTPS Plan page from fetching an HTTP localhost bridge. For headless
+troubleshooting, run:
+
+```bash
+npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind plan
+```
+
+`verify` starts the bridge, checks the private-network preflight and JSON
+payload, prints diagnostics, and exits.
 
 If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can also
 open the editable app route:

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

@@ -11,7 +11,7 @@ If you only remember one thing from this page, remember this: most AI apps today
 
 ## What it looks like as a user {#what-it-looks-like}
 
-Picture your inbox, calendar, or analytics dashboard. Now picture an agent panel docked on the right side of that app. You can:
+Picture your inbox, calendar, form builder, or analytics dashboard. Sometimes the first screen is chat: you ask what you want, the agent guides setup, shows a table or chart, and opens the right app view. Sometimes chat is docked on the right side of a full application. In both cases, you can:
 
 - **Click anything you'd normally click.** All the buttons, lists, dashboards, keyboard shortcuts — they all still work. This is a real app, not a chat window pretending to be one.
 - **Or just ask.** Type "reply to the email from Sara saying I'll be there by 3" into the agent. It opens the right thread, drafts the reply, and shows it to you for approval — exactly as if you'd done it by hand.
@@ -63,6 +63,14 @@ Even when the agent does all the heavy lifting, humans still need to:
 
 At minimum, "a UI for the agent" is an observability and management dashboard. At maximum, it's a full SaaS app with the agent embedded as a co-pilot. Both ends count as agent-native — see [Pure-Agent Apps](/docs/pure-agent-apps) for the minimal end and [Templates](/docs/cloneable-saas) for the maximal end.
 
+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.
+- **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.
+
 ## Why every app benefits from an agent {#why-every-app-benefits-from-an-agent}
 
 The flip side is just as important. Existing SaaS products keep hitting the same wall: 80% of what you need works great, and 20% you just can't change. Adding a chat sidebar rarely fixes that — the chat usually can't actually _do_ the things the UI can.
@@ -173,7 +181,7 @@ import { AgentSidebar } from "@agent-native/core/client";
 <AgentSidebar />;
 ```
 
-One action, many surfaces: the agent calls it as a tool, the UI calls it as a typesafe mutation, external agents reach it over [A2A](/docs/a2a-protocol), and MCP hosts call it through the app's [MCP server](/docs/mcp-protocol), optionally with MCP Apps UI resources and standard remote MCP OAuth handled by the framework. See [Actions](/docs/actions) for the full reference.
+One action, many surfaces: the agent calls it as a tool, the UI calls it as a typesafe mutation, native chat can render explicit widget results, external agents reach it over [A2A](/docs/a2a-protocol), and MCP hosts call it through the app's [MCP server](/docs/mcp-protocol), optionally with MCP Apps UI resources and standard remote MCP OAuth handled by the framework. See [Actions](/docs/actions) for the full reference.
 
 ## What's next {#whats-next}
 

package/package.json

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