cortena-ui 1.4.1 → 1.5.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Ascendence AI Technology Pvt Ltd. All rights reserved.
+
+This package is published for use with the Cortena platform by licensed
+Cortena customers and partners only. No permission is granted to copy,
+modify, redistribute or use it outside a Cortena deployment.
+
+Provided as is, without warranty.

package/README.md

@@ -28,18 +28,59 @@ consumer's bundler getting tree-shaking right:
 
 | entry | what it holds | what it costs |
 | --- | --- | --- |
-| `cortena-ui/core` | primitives, overlays, light form controls, `cn`, `useCortenaTheme` | nothing heavy |
+| `cortena-ui/core` | primitives, overlays, light form controls, `AppShell`, `cn`, `useCortenaTheme` | nothing heavy |
 | `cortena-ui/form` | `Form`, `useForm`, `zodResolver`, date pickers, `Dropzone` | react-hook-form, zod, react-day-picker, react-dropzone |
 | `cortena-ui/data-table` | `DataTable` and its parts | TanStack Table and Virtual; exceljs on the first export |
 | `cortena-ui/chart` | `Chart`, themed Recharts primitives | an engine on the first chart drawn, not on import |
 | `cortena-ui/markdown` | `Markdown` | react-markdown, remark-gfm, rehype-sanitize |
 | `cortena-ui/a2ui` | the A2UI catalogue and renderer | most of the package, by design |
 | `cortena-ui/sortable-list` | `SortableList`, `SortableHandle`, `arrayMove` | dnd-kit |
+| `cortena-ui/agent-chat` | `AgentChatPopup`, `AgentChat`, `createAguiAgentChatClient` | the A2UI catalogue, plus `@ag-ui/client` (rxjs, zod 3, uuid, protobuf) |
 
 Each component has exactly one home, so the barrel re-exports every entry
 without an ambiguous name. **Adding a component means adding it to its area
 entry in `src/entries/`, not to `src/index.ts`.**
 
+`AgentChat` has its own entry for the same kind of reason: `@ag-ui/client` is
+the run transport, and an extension that draws a button should not download a
+chat stream it never opens. It is also **not re-exported from the root barrel**,
+so `import { Button } from "cortena-ui"` cannot reach it however the consumer's
+bundler behaves. `pnpm bundle:probe` measures it, and
+`test/bundle-probe.test.mjs` fails if `@ag-ui/*` turns up in any other probe.
+
+`@ag-ui/client` is an **optional peer**, not a dependency: an extension that
+uses this entry installs it itself, at a version its own package.json names.
+
+```jsonc
+"peerDependencies":     { "@ag-ui/client": "^0.0.59" },
+"peerDependenciesMeta": { "@ag-ui/client": { "optional": true } }
+```
+
+As a dependency it was pinned to one exact build for the whole fleet, and an
+app that also talks AG-UI directly — which is every app with a second agent
+surface — resolved two copies. Two copies of an rxjs-based client is two event
+pipelines and two zod registries, and the symptom is a subscription that never
+fires. Optional, because only `createAguiAgentChatClient` imports it: `AgentChat`,
+`AgentChatPopup` and `useAgentChat` are written against the `AgentChatClient`
+interface, so an extension on another transport installs nothing.
+
+And it is loaded **lazily**, inside `createAguiAgentChatClient`, by dynamic
+import. A static import meant the optional peer was not optional at all: with
+it uninstalled the whole `cortena-ui/agent-chat` module failed to evaluate, so
+an extension on another transport could not draw `AgentChatPopup` either — a
+package it had never heard of decided whether its chat rendered, and said so in
+a resolution error. The entry now loads without the peer, and only a run needs
+it; when it is absent the chat shows
+
+> cortena-ui/agent-chat: the AG-UI transport needs the optional peer
+> "@ag-ui/client". Install it (pnpm add @ag-ui/client), or pass your own
+> AgentChatClient to AgentChat.
+
+The specifier stays a literal, so a bundler still splits the transport into a
+chunk of its own and `test/bundle-probe.test.mjs` still measures that the
+agent-chat entry carries it. `test/agent-chat-peer.test.mjs` runs the built
+entry in a child process with the peer made unresolvable.
+
 `SortableList` has its own entry for a specific reason rather than a stylistic
 one: `@dnd-kit/core` and `@dnd-kit/sortable` declare no `"sideEffects"` in their
 package.json, so a bundler must assume importing them does something observable
@@ -86,6 +127,113 @@ regression; `test/chart-bundle.test.tsx` says which line caused it.
   check in light, dark and system-dark; add an entry with every variant and
   size when adding a component.
 
+## Shell chrome
+
+`AppShell` is the chrome every extension wears (§9 of
+how-to-create-a-cortena-extension, audit rule P-10): the registered brand mark
+and the extension name top left, the avatar menu — the only settings entry
+point — top right, and one fixed bottom-right cluster holding the theme toggle
+then the help button. `BrandMark`, `BottomRightCluster`, `ThemeToggle`,
+`HelpButton` and `documentTitle` are exported alongside it.
+
+The mark comes from `cortena-design/marks` by `extension.id`, which is the same
+file the Apps tile, the MCP app card, the agent pop-up pill and the favicon
+draw. Adding a mark, and generating the three favicon files from it with
+`cortena-design-favicon`, are both in `../../CONSUMING.md`, "Shell chrome and
+favicon".
+
+`helpPanel` is a slot until `HelpPanel` lands (EXTBP-24); `help.source` is the
+functional document the panel will read.
+
+## The agent pop-up
+
+`AgentChatPopup` is the extension's own Cortena Agent, in the corner of every
+screen (§17 of how-to-create-a-cortena-extension, audit rule P-25). It mounts in
+`AppShell`'s `agentSlot`, so it stacks above the theme/help cluster rather than
+beside it.
+
+```tsx
+import { AppShell } from "cortena-ui";
+import { AgentChatPopup, createAguiAgentChatClient } from "cortena-ui/agent-chat";
+
+const extension = { id: "tasks", name: "Tasks" };
+
+const client = createAguiAgentChatClient({
+  baseUrl: "/api/agent",   // this extension's own gateway, not cortenacore
+  getToken: () => jwt,     // the signed-in USER's JWT, never a service token
+  agentId: "tasks",        // = the AgentTemplate slug = the extension id
+});
+
+<AppShell
+  extension={extension}
+  user={user}
+  agentSlot={<AgentChatPopup extension={extension} client={client} />}
+/>;
+```
+
+A collapsed pill opens to a panel (420 x 640) and the panel header expands it to
+full screen. **Cmd/Ctrl+J** toggles the pill and the panel; **Escape** steps full
+screen -> panel -> pill, except while a run is streaming, where the composer
+takes Escape to mean "stop the run". The chat is hidden rather than unmounted
+while collapsed, so a run that started before the user collapsed it keeps
+streaming and the pill shows an unread dot.
+
+**Sessions are per window.** The current session key lives in `sessionStorage`
+under a name scoped to the extension id, not in `localStorage`: opening the
+extension in a second window starts a second session rather than adopting the
+first window's. Every session stays listed and is resumable from any window, and
+two windows on one session may both send — cortenacore serialises the runs. A
+new key is minted client-side as `agent:<id>:new-<Date.now()>-<random36>` and
+used immediately, so an in-flight first message is never lost.
+
+### What the extension must proxy
+
+The pop-up talks to one origin, `baseUrl`, and every call carries the user's
+JWT. An extension's gateway proxies these to cortenacore; nothing here holds a
+service credential.
+
+| method + path | what it is |
+| --- | --- |
+| `POST {base}/agui/run` | the run stream. AG-UI `RunAgentInput` in, `text/event-stream` out. `threadId` is the session key verbatim, prefix included |
+| `POST {base}/agui/abort` | `{ runId, threadId }` |
+| `POST {base}/agui/approval` | `{ id, decision, threadId }` — `allow-once`, `allow-always`, `deny`. A separate endpoint on purpose: a decision sent as state on a second `/agui/run` opens a second concurrent stream |
+| `GET {base}/api/core/sessions/list` | the session drawer, filtered client-side to `agent:<id>:` |
+| `GET {base}/api/core/chat/history` | `?sessionKey=&limit=100&offset=` |
+| `POST {base}/tools/invoke` | only for an MCP App frame the host wires in — the app's own `tools/call`, scoped to its `mcp__<server>__` prefix |
+| `GET /api/design-tokens` | only for an MCP App frame: the token stylesheet the sandboxed document themes itself from |
+
+The stream ends by **closing the connection** after `RUN_FINISHED` or
+`RUN_ERROR`. There is no `data: [DONE]` sentinel; emitting one makes the AG-UI
+client error the subject, because it parses every `data:` line as JSON.
+`: keepalive` comment frames are fine.
+
+**Two server toggles must be on**, in every environment that runs an extension.
+Both default to false, and while either is off its paths answer `404` before
+authentication, which reads as "the agent does not exist":
+
+```
+cortenacore.http.endpoints.agui.enabled          = true
+cortenacore.http.endpoints.controlPlane.enabled  = true
+```
+
+### The MCP App frame
+
+Rendering an extension's own screen means a sandboxed iframe, a `srcdoc` CSP, a
+JSON-RPC postMessage bridge and a `tools/invoke` proxy holding a credential —
+host concerns, not component ones. `renderToolCall` is the seam: it is handed
+each tool call and the `ui://` resource its result carries, and a node it
+returns replaces the default card.
+
+```tsx
+<AgentChatPopup
+  extension={extension}
+  client={client}
+  renderToolCall={({ entry, mcpAppUri }) =>
+    mcpAppUri ? <McpAppFrame uri={mcpAppUri} result={entry.output} /> : undefined
+  }
+/>
+```
+
 ## Charts in tests
 
 Both chart engines size themselves from the parent box, and under jsdom every

package/dist/a2ui/catalogue-doc.d.ts

@@ -1,6 +1,6 @@
 "use client";
 import { A2UIComponentSpec } from "./message.js";
-import { A2UICatalogue, A2UIGroup } from "./catalogue.js";
+import { A2UIGroup } from "./catalogue.js";
 //#region src/a2ui/catalogue-doc.d.ts
 /** A JSON Schema object, as far as this module cares. */
 export type JsonSchema = Record<string, unknown>;
@@ -28,17 +28,5 @@ export interface A2UICatalogueDoc {
   generator: string;
   components: A2UIComponentDoc[];
 }
-/** Build the machine-readable catalogue document. */
-export declare function buildCatalogueDoc(catalogue?: A2UICatalogue): A2UICatalogueDoc;
-/**
- * Render the catalogue document as markdown.
- *
- * The output is written to be pasted into a system prompt: one table per
- * component listing every property with its type, whether it is required and
- * what it means, then a fenced example an agent can copy.
- */
-export declare function catalogueMarkdown(doc?: A2UICatalogueDoc): string;
-/** Turn an entry's example into the messages an agent would actually send. */
-export declare function exampleMessages(component: A2UIComponentDoc): unknown[];
 //#endregion
 //# sourceMappingURL=catalogue-doc.d.ts.map

package/dist/a2ui/index.d.ts

@@ -2,6 +2,6 @@
 import { A2UIAction, A2UIActionSpec, A2UIBeginRendering, A2UIChildList, A2UIChildren, A2UIComponentSpec, A2UICreateSurface, A2UIDataBinding, A2UIDeleteSurface, A2UIFoldResult, A2UIMessage, A2UIMessageInput, A2UIPropertyValue, A2UISurface, A2UIUpdateComponents, A2UIUpdateDataModel, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer } from "./message.js";
 import { A2UIColumn, A2UIErrorCard, A2UINodeInfo, A2UIResolvedAction, A2UIRow, A2UITableSource, A2UIView, A2UIViewProps } from "./views.js";
 import { A2UICatalogue, A2UICatalogueEntry, A2UIExample, A2UIGroup, A2UI_CATALOGUE_ID, catalogueNames, defaultCatalogue } from "./catalogue.js";
-import { A2UICatalogueDoc, A2UIComponentDoc, JsonSchema, buildCatalogueDoc, catalogueMarkdown, exampleMessages } from "./catalogue-doc.js";
+import { A2UICatalogueDoc, A2UIComponentDoc, JsonSchema } from "./catalogue-doc.js";
 import { A2UIRenderer, A2UIRendererProps } from "./renderer.js";
-export { type A2UIAction, type A2UIActionSpec, type A2UIBeginRendering, type A2UICatalogue, type A2UICatalogueDoc, type A2UICatalogueEntry, type A2UIChildList, type A2UIChildren, type A2UIColumn, type A2UIComponentDoc, type A2UIComponentSpec, type A2UICreateSurface, type A2UIDataBinding, type A2UIDeleteSurface, A2UIErrorCard, type A2UIExample, type A2UIFoldResult, type A2UIGroup, type A2UIMessage, type A2UIMessageInput, type A2UINodeInfo, type A2UIPropertyValue, A2UIRenderer, type A2UIRendererProps, type A2UIResolvedAction, type A2UIRow, type A2UISurface, type A2UITableSource, type A2UIUpdateComponents, type A2UIUpdateDataModel, type A2UIView, type A2UIViewProps, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, type JsonSchema, buildCatalogueDoc, catalogueMarkdown, catalogueNames, defaultCatalogue, exampleMessages, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer };
+export { type A2UIAction, type A2UIActionSpec, type A2UIBeginRendering, type A2UICatalogue, type A2UICatalogueDoc, type A2UICatalogueEntry, type A2UIChildList, type A2UIChildren, type A2UIColumn, type A2UIComponentDoc, type A2UIComponentSpec, type A2UICreateSurface, type A2UIDataBinding, type A2UIDeleteSurface, A2UIErrorCard, type A2UIExample, type A2UIFoldResult, type A2UIGroup, type A2UIMessage, type A2UIMessageInput, type A2UINodeInfo, type A2UIPropertyValue, A2UIRenderer, type A2UIRendererProps, type A2UIResolvedAction, type A2UIRow, type A2UISurface, type A2UITableSource, type A2UIUpdateComponents, type A2UIUpdateDataModel, type A2UIView, type A2UIViewProps, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, type JsonSchema, catalogueNames, defaultCatalogue, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer };

package/dist/a2ui/views.js

@@ -2,12 +2,12 @@
 "use client";
 import { cn } from "../lib/cn.js";
 import { Alert, AlertDescription, AlertIcon, AlertTitle } from "../components/alert.js";
-import { Badge } from "../components/badge.js";
 import { Button } from "../components/button.js";
+import { Input } from "../components/input.js";
+import { Badge } from "../components/badge.js";
 import { ButtonLink } from "../components/button-link.js";
 import { Card, CardContent } from "../components/card.js";
 import { Checkbox } from "../components/checkbox.js";
-import { Input } from "../components/input.js";
 import { EmptyState } from "../components/empty-state.js";
 import { Field, FieldDescription, FieldError, FieldLabel } from "../components/field.js";
 import { Progress, ProgressLabel, ProgressValue } from "../components/progress.js";

package/dist/a2ui.d.ts

@@ -2,7 +2,7 @@
 import { A2UIAction, A2UIActionSpec, A2UIBeginRendering, A2UIChildList, A2UIChildren, A2UIComponentSpec, A2UICreateSurface, A2UIDataBinding, A2UIDeleteSurface, A2UIFoldResult, A2UIMessage, A2UIMessageInput, A2UIPropertyValue, A2UISurface, A2UIUpdateComponents, A2UIUpdateDataModel, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer } from "./a2ui/message.js";
 import { A2UIColumn, A2UIErrorCard, A2UINodeInfo, A2UIResolvedAction, A2UIRow, A2UITableSource, A2UIView, A2UIViewProps } from "./a2ui/views.js";
 import { A2UICatalogue, A2UICatalogueEntry, A2UIExample, A2UIGroup, A2UI_CATALOGUE_ID, catalogueNames, defaultCatalogue } from "./a2ui/catalogue.js";
-import { A2UICatalogueDoc, A2UIComponentDoc, JsonSchema, buildCatalogueDoc, catalogueMarkdown, exampleMessages } from "./a2ui/catalogue-doc.js";
+import { A2UICatalogueDoc, A2UIComponentDoc, JsonSchema } from "./a2ui/catalogue-doc.js";
 import { A2UIRenderer, A2UIRendererProps } from "./a2ui/renderer.js";
 import "./a2ui/index.js";
-export { type A2UIAction, type A2UIActionSpec, type A2UIBeginRendering, type A2UICatalogue, type A2UICatalogueDoc, type A2UICatalogueEntry, type A2UIChildList, type A2UIChildren, type A2UIColumn, type A2UIComponentDoc, type A2UIComponentSpec, type A2UICreateSurface, type A2UIDataBinding, type A2UIDeleteSurface, A2UIErrorCard, type A2UIExample, type A2UIFoldResult, type A2UIGroup, type A2UIMessage, type A2UIMessageInput, type A2UINodeInfo, type A2UIPropertyValue, A2UIRenderer, type A2UIRendererProps, type A2UIResolvedAction, type A2UIRow, type A2UISurface, type A2UITableSource, type A2UIUpdateComponents, type A2UIUpdateDataModel, type A2UIView, type A2UIViewProps, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, type JsonSchema, buildCatalogueDoc, catalogueMarkdown, catalogueNames, defaultCatalogue, exampleMessages, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer };
+export { type A2UIAction, type A2UIActionSpec, type A2UIBeginRendering, type A2UICatalogue, type A2UICatalogueDoc, type A2UICatalogueEntry, type A2UIChildList, type A2UIChildren, type A2UIColumn, type A2UIComponentDoc, type A2UIComponentSpec, type A2UICreateSurface, type A2UIDataBinding, type A2UIDeleteSurface, A2UIErrorCard, type A2UIExample, type A2UIFoldResult, type A2UIGroup, type A2UIMessage, type A2UIMessageInput, type A2UINodeInfo, type A2UIPropertyValue, A2UIRenderer, type A2UIRendererProps, type A2UIResolvedAction, type A2UIRow, type A2UISurface, type A2UITableSource, type A2UIUpdateComponents, type A2UIUpdateDataModel, type A2UIView, type A2UIViewProps, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, type JsonSchema, catalogueNames, defaultCatalogue, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer };

package/dist/a2ui.js

@@ -2,6 +2,5 @@
 import { A2UIErrorCard } from "./a2ui/views.js";
 import { A2UI_CATALOGUE_ID, catalogueNames, defaultCatalogue } from "./a2ui/catalogue.js";
 import { A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer } from "./a2ui/message.js";
-import { buildCatalogueDoc, catalogueMarkdown, exampleMessages } from "./a2ui/catalogue-doc.js";
 import { A2UIRenderer } from "./a2ui/renderer.js";
-export { A2UIErrorCard, A2UIRenderer, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, buildCatalogueDoc, catalogueMarkdown, catalogueNames, defaultCatalogue, exampleMessages, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer };
+export { A2UIErrorCard, A2UIRenderer, A2UI_CATALOGUE_ID, A2UI_DEFAULT_SURFACE_ID, A2UI_VERSION, catalogueNames, defaultCatalogue, foldMessages, getAtPointer, isDataBinding, parseA2UIMessages, pointerSegments, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer };

package/dist/agent-chat/a2ui-block.d.ts

@@ -0,0 +1,60 @@
+"use client";
+//#region src/agent-chat/a2ui-block.d.ts
+/**
+ * A2UI blocks as the chat carries them.
+ *
+ * Ported from `cortena-shared/src/a2ui/block.ts` (Cortena monorepo, DESIGN-35).
+ * `cortena-shared` is not published, so the parts this package needs are copied
+ * rather than imported; keep the two in step when either changes.
+ *
+ * An agent draws UI by writing a ```a2ui fenced block, cortenacore strips it out
+ * of the prose, and it reaches the client on a channel of its own — a
+ * `CUSTOM cortena.a2ui` event on the AG-UI transport. Both the streaming bubble
+ * and the finished message carry the result here, so the bubble has exactly one
+ * thing to render and no markdown to parse.
+ *
+ * Nothing in this module knows about React: the `messages` array is handed to
+ * `<A2UIRenderer message={...} />` verbatim, and folding a surface, validating a
+ * component and drawing it are the renderer's job.
+ */
+/** One block, as the transport delivers it. */
+export interface A2UIChatBlock {
+  /**
+   * Accumulation key: the surface id the payload names, or a key private to the
+   * block when it names none. Two blocks with the same key are two pushes to one
+   * surface and fold together.
+   */
+  surfaceId: string;
+  /** A2UI messages, in arrival order. */
+  messages: unknown[];
+  /** Where the block came from: assistant text, or a `canvas` tool push. */
+  source?: "text" | "canvas";
+  /** Assistant message the block belonged to, when the transport knows it. */
+  messageId?: string;
+  /** Set when the fence never closed or its body did not parse. */
+  error?: string;
+  /** The raw fence body; only present with `error`. */
+  raw?: string;
+}
+/** Read one block out of an unknown wire value; `null` when it is not one. */
+export declare function readA2UIBlock(value: unknown): A2UIChatBlock | null;
+/**
+ * Pull the `a2ui` content parts out of a chat event message.
+ *
+ * A client that does not know the type ignores it, which is what lets the same
+ * message shape carry blocks to a reader that cannot draw them.
+ */
+export declare function extractA2UIBlocks(message?: {
+  content?: Array<Record<string, unknown>>;
+} | null): A2UIChatBlock[];
+/**
+ * Fold blocks that share a surface id into one, concatenating their messages.
+ *
+ * An agent that streams a surface writes the shell, then the rows, then a
+ * correction — three fences naming one surface. The renderer folds a message
+ * list onto a surface, so handing it the concatenation renders the finished
+ * surface; handing it three separate blocks would draw the shell three times.
+ */
+export declare function foldA2UIBlocks(blocks: readonly A2UIChatBlock[]): A2UIChatBlock[];
+//#endregion
+//# sourceMappingURL=a2ui-block.d.ts.map

package/dist/agent-chat/a2ui-block.js

@@ -0,0 +1,69 @@
+"use client";
+//#region src/agent-chat/a2ui-block.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read one block out of an unknown wire value; `null` when it is not one. */
+function readA2UIBlock(value) {
+	if (!isRecord(value)) return null;
+	const messages = Array.isArray(value.messages) ? value.messages : [];
+	const surfaceId = typeof value.surfaceId === "string" && value.surfaceId ? value.surfaceId : "@default";
+	const error = typeof value.error === "string" && value.error ? value.error : void 0;
+	if (messages.length === 0 && !error) return null;
+	return {
+		surfaceId,
+		messages,
+		...value.source === "canvas" || value.source === "text" ? { source: value.source } : {},
+		...typeof value.messageId === "string" && value.messageId ? { messageId: value.messageId } : {},
+		...error ? { error } : {},
+		...typeof value.raw === "string" ? { raw: value.raw } : {}
+	};
+}
+/**
+* Pull the `a2ui` content parts out of a chat event message.
+*
+* A client that does not know the type ignores it, which is what lets the same
+* message shape carry blocks to a reader that cannot draw them.
+*/
+function extractA2UIBlocks(message) {
+	const blocks = [];
+	for (const part of message?.content ?? []) {
+		if (!isRecord(part) || part.type !== "a2ui") continue;
+		const block = readA2UIBlock(part.a2ui ?? part);
+		if (block) blocks.push(block);
+	}
+	return foldA2UIBlocks(blocks);
+}
+/**
+* Fold blocks that share a surface id into one, concatenating their messages.
+*
+* An agent that streams a surface writes the shell, then the rows, then a
+* correction — three fences naming one surface. The renderer folds a message
+* list onto a surface, so handing it the concatenation renders the finished
+* surface; handing it three separate blocks would draw the shell three times.
+*/
+function foldA2UIBlocks(blocks) {
+	const byId = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const block of blocks) {
+		const existing = byId.get(block.surfaceId);
+		if (!existing) {
+			byId.set(block.surfaceId, {
+				...block,
+				messages: [...block.messages]
+			});
+			order.push(block.surfaceId);
+			continue;
+		}
+		existing.messages.push(...block.messages);
+		if (block.error && !existing.error) {
+			existing.error = block.error;
+			if (block.raw !== void 0) existing.raw = block.raw;
+		}
+	}
+	return order.map((id) => byId.get(id)).filter(Boolean);
+}
+//#endregion
+export { extractA2UIBlocks, foldA2UIBlocks, readA2UIBlock };
+
+//# sourceMappingURL=a2ui-block.js.map

package/dist/agent-chat/a2ui-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2ui-block.js","names":[],"sources":["../../src/agent-chat/a2ui-block.ts"],"sourcesContent":["/**\n * A2UI blocks as the chat carries them.\n *\n * Ported from `cortena-shared/src/a2ui/block.ts` (Cortena monorepo, DESIGN-35).\n * `cortena-shared` is not published, so the parts this package needs are copied\n * rather than imported; keep the two in step when either changes.\n *\n * An agent draws UI by writing a ```a2ui fenced block, cortenacore strips it out\n * of the prose, and it reaches the client on a channel of its own — a\n * `CUSTOM cortena.a2ui` event on the AG-UI transport. Both the streaming bubble\n * and the finished message carry the result here, so the bubble has exactly one\n * thing to render and no markdown to parse.\n *\n * Nothing in this module knows about React: the `messages` array is handed to\n * `<A2UIRenderer message={...} />` verbatim, and folding a surface, validating a\n * component and drawing it are the renderer's job.\n */\n\n/** One block, as the transport delivers it. */\nexport interface A2UIChatBlock {\n  /**\n   * Accumulation key: the surface id the payload names, or a key private to the\n   * block when it names none. Two blocks with the same key are two pushes to one\n   * surface and fold together.\n   */\n  surfaceId: string;\n  /** A2UI messages, in arrival order. */\n  messages: unknown[];\n  /** Where the block came from: assistant text, or a `canvas` tool push. */\n  source?: \"text\" | \"canvas\";\n  /** Assistant message the block belonged to, when the transport knows it. */\n  messageId?: string;\n  /** Set when the fence never closed or its body did not parse. */\n  error?: string;\n  /** The raw fence body; only present with `error`. */\n  raw?: string;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Read one block out of an unknown wire value; `null` when it is not one. */\nexport function readA2UIBlock(value: unknown): A2UIChatBlock | null {\n  if (!isRecord(value)) {\n    return null;\n  }\n  const messages = Array.isArray(value.messages) ? value.messages : [];\n  const surfaceId =\n    typeof value.surfaceId === \"string\" && value.surfaceId ? value.surfaceId : \"@default\";\n  const error = typeof value.error === \"string\" && value.error ? value.error : undefined;\n  if (messages.length === 0 && !error) {\n    return null;\n  }\n  return {\n    surfaceId,\n    messages,\n    ...(value.source === \"canvas\" || value.source === \"text\" ? { source: value.source } : {}),\n    ...(typeof value.messageId === \"string\" && value.messageId\n      ? { messageId: value.messageId }\n      : {}),\n    ...(error ? { error } : {}),\n    ...(typeof value.raw === \"string\" ? { raw: value.raw } : {}),\n  };\n}\n\n/**\n * Pull the `a2ui` content parts out of a chat event message.\n *\n * A client that does not know the type ignores it, which is what lets the same\n * message shape carry blocks to a reader that cannot draw them.\n */\nexport function extractA2UIBlocks(\n  message?: { content?: Array<Record<string, unknown>> } | null,\n): A2UIChatBlock[] {\n  const blocks: A2UIChatBlock[] = [];\n  for (const part of message?.content ?? []) {\n    if (!isRecord(part) || part.type !== \"a2ui\") {\n      continue;\n    }\n    const block = readA2UIBlock(part.a2ui ?? part);\n    if (block) {\n      blocks.push(block);\n    }\n  }\n  return foldA2UIBlocks(blocks);\n}\n\n/**\n * Fold blocks that share a surface id into one, concatenating their messages.\n *\n * An agent that streams a surface writes the shell, then the rows, then a\n * correction — three fences naming one surface. The renderer folds a message\n * list onto a surface, so handing it the concatenation renders the finished\n * surface; handing it three separate blocks would draw the shell three times.\n */\nexport function foldA2UIBlocks(blocks: readonly A2UIChatBlock[]): A2UIChatBlock[] {\n  const byId = new Map<string, A2UIChatBlock>();\n  const order: string[] = [];\n  for (const block of blocks) {\n    const existing = byId.get(block.surfaceId);\n    if (!existing) {\n      byId.set(block.surfaceId, { ...block, messages: [...block.messages] });\n      order.push(block.surfaceId);\n      continue;\n    }\n    existing.messages.push(...block.messages);\n    // The first failure is the one worth showing: later ones are usually the\n    // same malformed payload arriving again.\n    if (block.error && !existing.error) {\n      existing.error = block.error;\n      if (block.raw !== undefined) {\n        existing.raw = block.raw;\n      }\n    }\n  }\n  return order.map((id) => byId.get(id)!).filter(Boolean);\n}\n"],"mappings":";;AAsCA,SAAS,SAAS,OAAkD;CAClE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;;AAGA,SAAgB,cAAc,OAAsC;CAClE,IAAI,CAAC,SAAS,KAAK,GACjB,OAAO;CAET,MAAM,WAAW,MAAM,QAAQ,MAAM,QAAQ,IAAI,MAAM,WAAW,CAAC;CACnE,MAAM,YACJ,OAAO,MAAM,cAAc,YAAY,MAAM,YAAY,MAAM,YAAY;CAC7E,MAAM,QAAQ,OAAO,MAAM,UAAU,YAAY,MAAM,QAAQ,MAAM,QAAQ,KAAA;CAC7E,IAAI,SAAS,WAAW,KAAK,CAAC,OAC5B,OAAO;CAET,OAAO;EACL;EACA;EACA,GAAI,MAAM,WAAW,YAAY,MAAM,WAAW,SAAS,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;EACvF,GAAI,OAAO,MAAM,cAAc,YAAY,MAAM,YAC7C,EAAE,WAAW,MAAM,UAAU,IAC7B,CAAC;EACL,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;EACzB,GAAI,OAAO,MAAM,QAAQ,WAAW,EAAE,KAAK,MAAM,IAAI,IAAI,CAAC;CAC5D;AACF;;;;;;;AAQA,SAAgB,kBACd,SACiB;CACjB,MAAM,SAA0B,CAAC;CACjC,KAAK,MAAM,QAAQ,SAAS,WAAW,CAAC,GAAG;EACzC,IAAI,CAAC,SAAS,IAAI,KAAK,KAAK,SAAS,QACnC;EAEF,MAAM,QAAQ,cAAc,KAAK,QAAQ,IAAI;EAC7C,IAAI,OACF,OAAO,KAAK,KAAK;CAErB;CACA,OAAO,eAAe,MAAM;AAC9B;;;;;;;;;AAUA,SAAgB,eAAe,QAAmD;CAChF,MAAM,uBAAO,IAAI,IAA2B;CAC5C,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,WAAW,KAAK,IAAI,MAAM,SAAS;EACzC,IAAI,CAAC,UAAU;GACb,KAAK,IAAI,MAAM,WAAW;IAAE,GAAG;IAAO,UAAU,CAAC,GAAG,MAAM,QAAQ;GAAE,CAAC;GACrE,MAAM,KAAK,MAAM,SAAS;GAC1B;EACF;EACA,SAAS,SAAS,KAAK,GAAG,MAAM,QAAQ;EAGxC,IAAI,MAAM,SAAS,CAAC,SAAS,OAAO;GAClC,SAAS,QAAQ,MAAM;GACvB,IAAI,MAAM,QAAQ,KAAA,GAChB,SAAS,MAAM,MAAM;EAEzB;CACF;CACA,OAAO,MAAM,KAAK,OAAO,KAAK,IAAI,EAAE,CAAE,CAAC,CAAC,OAAO,OAAO;AACxD"}

package/dist/agent-chat/agui-client.d.ts

@@ -0,0 +1,40 @@
+"use client";
+import { AgentChatClient } from "./types.js";
+//#region src/agent-chat/agui-client.d.ts
+export interface CreateAguiAgentChatClientOptions {
+  /**
+   * Origin the AG-UI and control-plane paths hang off, no trailing slash.
+   * For an extension this is its own gateway, which proxies to cortenacore.
+   */
+  baseUrl: string;
+  /** The signed-in USER's JWT. Read on every request, never captured once. */
+  getToken: () => string;
+  /** The agent template slug — the extension id. Sessions are `agent:<id>:…`. */
+  agentId: string;
+  fetchImpl?: typeof fetch;
+  /** Frontend tools advertised on every run; AG-UI requires a description. */
+  tools?: Array<{
+    name: string;
+    description: string;
+    parameters?: unknown;
+  }>;
+  /** Backoff before re-attaching a dropped stream. */
+  reconnectDelays?: readonly number[];
+  maxReconnectAttempts?: number;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+/**
+ * An `AgentChatClient` that streams over AG-UI and reads sessions and history
+ * over the REST control plane.
+ *
+ * ```tsx
+ * const client = React.useMemo(
+ *   () => createAguiAgentChatClient({ baseUrl: "/api/agent", getToken: () => jwt, agentId: "tasks" }),
+ *   [jwt],
+ * );
+ * ```
+ */
+export declare function createAguiAgentChatClient(options: CreateAguiAgentChatClientOptions): AgentChatClient;
+//#endregion
+//# sourceMappingURL=agui-client.d.ts.map