@agent-native/core 0.55.0 → 0.56.1

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/what-is-agent-native.md

@@ -66,7 +66,7 @@ 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.
+- **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.
@@ -181,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, 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.
+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.55.0",
+  "version": "0.56.1",
   "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",
@@ -140,7 +141,9 @@
     "./tsconfig.base.json": "./tsconfig.base.json"
   },
   "sideEffects": [
-    "*.css"
+    "*.css",
+    "dist/client/chat/widgets/builtin-tool-renderers.js",
+    "dist/client/dev-overlay/builtins.js"
   ],
   "files": [
     "bin",