@agent-native/core 0.54.1 → 0.56.0

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

@@ -0,0 +1,210 @@
+---
+title: "Native Chat UI"
+description: "Action-declared native chat renderers, reusable DataTable/DataChart outputs, and how BYO agent runtimes should connect to Agent-Native chat."
+---
+
+# Native Chat UI
+
+Native chat UI is the in-app rendering path for first-party agent output. An
+action returns structured JSON, the chat runtime recognizes an explicit widget
+discriminant, and `<AssistantChat>` renders a real React component in the
+conversation. You do not build an iframe or a one-off HTML artifact for the
+normal app chat.
+
+Use native chat UI when the user should inspect output where the agent is
+already speaking: query results, response insights, setup summaries,
+approval/denial controls, or links into app views. Use [MCP Apps](/docs/mcp-apps)
+when an external host such as Claude, ChatGPT, Copilot, or Cursor should render
+an inline route from your app.
+
+## Action-declared widgets {#action-declared-widgets}
+
+The native path has two explicit parts:
+
+- `outputSchema` validates the action's response shape.
+- `chatUI.renderer` selects the native React renderer for the validated result.
+
+The built-in data renderers use a plain JSON result with `widget` plus the
+matching payload:
+
+| Widget            | Required payload             | Renders as                                      |
+| ----------------- | ---------------------------- | ----------------------------------------------- |
+| `"data-table"`    | `table`                      | A native, reusable data table                   |
+| `"data-chart"`    | `chartSeries`                | A native bar, line, or area chart               |
+| `"data-insights"` | `table` and/or `chartSeries` | A combined insight card with chart/table output |
+
+Server actions should import the server-safe helpers and schemas from
+`@agent-native/core/data-widgets`; client code can import the same types from
+`@agent-native/core/client/chat` or `@agent-native/core/client`.
+
+```ts
+import {
+  ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+  dataInsightsWidgetResultSchema,
+  defineAction,
+} from "@agent-native/core";
+import { createDataInsightsWidgetResult } from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Analyze form responses.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+    title: "Response insights",
+  },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response insights",
+      display: {
+        title: "42 responses",
+        description: "Completion rate rose this week.",
+        primaryAction: {
+          label: "Open response insights",
+          href: "/response-insights",
+        },
+      },
+      chartSeries: {
+        type: "bar",
+        title: "Responses by day",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 8 },
+          { day: "Tue", responses: 13 },
+        ],
+      },
+      table: {
+        title: "Top answers",
+        columns: [
+          { key: "answer", label: "Answer" },
+          { key: "count", label: "Count", align: "right" },
+        ],
+        rows: [
+          { answer: "Yes", count: 31 },
+          { answer: "No", count: 11 },
+        ],
+        totalRows: 2,
+      },
+    }),
+});
+```
+
+The renderer only takes over when the action declares `chatUI` or the result has
+an explicit known `widget` discriminant. It never shape-infers arbitrary objects
+and it never executes HTML or JavaScript from tool results.
+
+## DataTable output {#data-table}
+
+`table` is intentionally simple so list, SQL, analytics, and setup actions can
+reuse it:
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+Prefer stable column keys and JSON-safe row values. Use `totalRows`,
+`sampledRows`, and `truncated` when the action is showing a slice of a larger
+result set.
+
+## DataChart output {#data-chart}
+
+`chartSeries` supports the common chart shapes used in agent answers without
+requiring each template to ship its own chat renderer:
+
+```ts
+{
+  type: "bar" | "line" | "area";
+  title?: string;
+  xKey: string;
+  series: Array<{ key: string; label: string; color?: string }>;
+  data: Array<Record<string, unknown>>;
+  sampled?: boolean;
+}
+```
+
+Keep chart data compact. For large datasets, aggregate in the action and link
+to the full app view with `display.primaryAction` or action `link` metadata.
+
+## Native widgets vs MCP Apps {#native-vs-mcp-apps}
+
+Native chat widgets and MCP Apps are complementary:
+
+- **Native widgets** are for the app's own chat runtime. The action result is
+  JSON, and the framework renders the built-in React widget.
+- **MCP Apps** are for external hosts. The action declares `mcpApp` and usually
+  `link`, and the host renders a real app route inline when supported.
+- **Deep links** remain the universal fallback. Use action `link` or
+  `display.primaryAction` so CLI clients, older MCP hosts, and plain transcript
+  readers can open the full app view.
+
+When both a native widget payload and MCP Apps metadata are present, the in-app
+chat prefers the native widget. External hosts use the MCP Apps resource or the
+deep link fallback.
+
+## Custom native renderers {#custom-native-renderers}
+
+Register product-specific components by exact renderer id, then declare that id
+on the action:
+
+```tsx
+import { registerActionChatRenderer } from "@agent-native/core/client/chat";
+
+registerActionChatRenderer({
+  id: "crm.deal-card",
+  renderer: "crm.deal-card",
+  Component: ({ context }) => <DealCard result={context.resultJson} />,
+});
+```
+
+```ts
+export default defineAction({
+  description: "Show a deal card.",
+  outputSchema: dealCardSchema,
+  chatUI: { renderer: "crm.deal-card" },
+  run: async () => ({ dealId: "deal_123", amount: 42000 }),
+});
+```
+
+Use this for first-party app UI. Keep cross-host iframe UI in `mcpApp`, and keep
+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.
+
+## Related docs {#related-docs}
+
+- [Actions](/docs/actions) — define the operations that return native widget data.
+- [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.
+- [Key Concepts](/docs/key-concepts#protocols) — protocol status and positioning.

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. 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.
+
 ## 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](/docs/native-chat-ui) 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.56.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -37,6 +37,7 @@
     "./server/design-token-utils": "./dist/server/design-token-utils.js",
     "./brand-kit": "./dist/brand-kit/index.js",
     "./brand-kit/fig": "./dist/brand-kit/fig/index.js",
+    "./data-widgets": "./dist/data-widgets/index.js",
     "./agent-web": "./dist/agent-web/index.js",
     "./db": "./dist/db/index.js",
     "./db/schema": "./dist/db/schema.js",