cortena-ui 1.4.2 → 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/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/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

package/dist/agent-chat/agui-client.js

@@ -0,0 +1,251 @@
+"use client";
+import { AgentChatBridge } from "./bridge.js";
+//#region src/agent-chat/agui-client.ts
+const DEFAULT_RECONNECT_DELAYS = [
+	500,
+	1e3,
+	2e3,
+	5e3,
+	1e4
+];
+const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* What a relative `baseUrl` resolves against.
+*
+* The browser's own origin, and a placeholder under Node — where this module
+* is exercised by tests with a `fetchImpl` stub and there is no origin to
+* speak of. The placeholder never reaches the network: the stub sees the
+* resolved string, and `/api/core/...` is what it asserts on.
+*/
+function requestBase() {
+	return typeof location === "undefined" ? "http://cortena.invalid" : location.origin;
+}
+const MISSING_AGUI_PEER = "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.";
+/**
+* `@ag-ui/client`, on demand.
+*
+* The specifier is a literal so a bundler still sees the dependency and puts
+* it in a chunk of its own — `test/bundle-probe.test.mjs` measures that the
+* agent-chat entry carries it. What changes is *when* it is evaluated, and
+* what happens when it is not there at all.
+*/
+async function loadHttpAgent() {
+	try {
+		return (await import("@ag-ui/client")).HttpAgent;
+	} catch (cause) {
+		throw new Error(MISSING_AGUI_PEER, { cause });
+	}
+}
+var AguiAgentChatClient = class {
+	agentId;
+	opts;
+	delays;
+	maxAttempts;
+	sleep;
+	chatSinks = /* @__PURE__ */ new Set();
+	toolSinks = /* @__PURE__ */ new Set();
+	approvalSinks = /* @__PURE__ */ new Set();
+	active = null;
+	/** The optional peer, requested when the client is created and awaited per run. */
+	httpAgent;
+	constructor(opts) {
+		this.opts = opts;
+		this.agentId = opts.agentId;
+		this.delays = opts.reconnectDelays ?? DEFAULT_RECONNECT_DELAYS;
+		this.maxAttempts = opts.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
+		this.sleep = opts.sleep ?? defaultSleep;
+		this.httpAgent = loadHttpAgent();
+		this.httpAgent.catch(() => {});
+	}
+	onChat(sink) {
+		this.chatSinks.add(sink);
+		return () => this.chatSinks.delete(sink);
+	}
+	onTool(sink) {
+		this.toolSinks.add(sink);
+		return () => this.toolSinks.delete(sink);
+	}
+	onApproval(sink) {
+		this.approvalSinks.add(sink);
+		return () => this.approvalSinks.delete(sink);
+	}
+	get runUrl() {
+		return `${this.opts.baseUrl}/agui/run`;
+	}
+	get abortUrl() {
+		return `${this.opts.baseUrl}/agui/abort`;
+	}
+	get approvalUrl() {
+		return `${this.opts.baseUrl}/agui/approval`;
+	}
+	headers() {
+		return {
+			authorization: `Bearer ${this.opts.getToken()}`,
+			"content-type": "application/json"
+		};
+	}
+	get fetch() {
+		return this.opts.fetchImpl ?? globalThis.fetch;
+	}
+	/** `sessions.list` and `chat.history` over the REST control plane. */
+	async request(method, params) {
+		const path = `${this.opts.baseUrl}/api/core/${method.split(".").join("/")}`;
+		const readOnly = method === "sessions.list" || method === "chat.history";
+		const url = new URL(path, requestBase());
+		if (readOnly) {
+			for (const [key, value] of Object.entries(params)) if (value !== void 0 && value !== null) url.searchParams.set(key, String(value));
+		}
+		const response = await this.fetch(url.toString(), {
+			method: readOnly ? "GET" : "POST",
+			headers: this.headers(),
+			...readOnly ? {} : { body: JSON.stringify(params) }
+		});
+		if (!response.ok) throw new Error(await readError(response, method));
+		return await response.json();
+	}
+	async send(input) {
+		this.startRun(input);
+	}
+	async startRun(input) {
+		const bridge = new AgentChatBridge({
+			runId: input.runId,
+			sessionKey: input.sessionKey,
+			chat: (event) => this.emit(this.chatSinks, event),
+			tool: (event) => this.emit(this.toolSinks, event),
+			approval: (event) => this.emit(this.approvalSinks, event),
+			...this.opts.now ? { now: this.opts.now } : {}
+		});
+		const forwarded = {
+			...input.thinking ? { thinking: input.thinking } : {},
+			...input.attachments?.length ? { attachments: input.attachments } : {},
+			...input.model ? { model: input.model } : {},
+			...input.a2uiAction ? { a2uiAction: input.a2uiAction } : {},
+			...input.mcpAppAction ? { mcpAppAction: input.mcpAppAction } : {}
+		};
+		let Agent;
+		try {
+			Agent = await this.httpAgent;
+		} catch (err) {
+			bridge.fail(err instanceof Error ? err.message : MISSING_AGUI_PEER);
+			return;
+		}
+		let attempt = 0;
+		let resume = false;
+		for (;;) {
+			const runId = resume ? `${input.runId}:resume-${attempt}` : input.runId;
+			const agent = new Agent({
+				url: this.runUrl,
+				headers: this.headers(),
+				threadId: input.sessionKey,
+				initialMessages: resume ? [] : [{
+					id: input.runId,
+					role: "user",
+					content: input.message
+				}],
+				...this.opts.fetchImpl ? { fetch: this.opts.fetchImpl } : {}
+			});
+			this.active = {
+				runId: input.runId,
+				sessionKey: input.sessionKey,
+				bridge,
+				agent,
+				aborted: this.active?.aborted === true && this.active.runId === input.runId
+			};
+			try {
+				await agent.runAgent({
+					runId,
+					...this.opts.tools?.length ? { tools: this.opts.tools } : {},
+					forwardedProps: {
+						...forwarded,
+						...resume ? { resumeRunId: input.runId } : {}
+					}
+				}, { onEvent: ({ event }) => bridge.handleEvent(event) });
+				return;
+			} catch (err) {
+				if (bridge.finished || this.active?.aborted) return;
+				attempt += 1;
+				if (attempt > this.maxAttempts) {
+					bridge.fail(err instanceof Error ? err.message : "The agent stream failed");
+					return;
+				}
+				await this.sleep(this.delays[Math.min(attempt - 1, this.delays.length - 1)] ?? 1e3);
+				if (bridge.finished || this.active?.aborted) return;
+				resume = true;
+			}
+		}
+	}
+	async abort(params) {
+		const active = this.active;
+		if (active) {
+			active.aborted = true;
+			try {
+				active.agent.abortRun();
+			} catch {}
+		}
+		const runId = params?.runId ?? active?.runId;
+		const threadId = params?.sessionKey ?? active?.sessionKey;
+		if (!runId || !threadId) return;
+		try {
+			await this.fetch(this.abortUrl, {
+				method: "POST",
+				headers: this.headers(),
+				body: JSON.stringify({
+					runId,
+					threadId
+				})
+			});
+		} catch {}
+	}
+	/**
+	* Answer one approval, on the thread and run it arrived on.
+	*
+	* `this.active` is deliberately not consulted. An approval pauses a run, and
+	* a user is free to open another session from the drawer or start another
+	* turn while it waits — at which point `active.sessionKey` is a different
+	* conversation and "allow" would be sent against it. The request carried its
+	* own `{ runId, sessionKey }`; those are what go on the wire.
+	*/
+	async resolveApproval(id, decision, context) {
+		const response = await this.fetch(this.approvalUrl, {
+			method: "POST",
+			headers: this.headers(),
+			body: JSON.stringify({
+				id,
+				decision,
+				threadId: context.sessionKey,
+				runId: context.runId
+			})
+		});
+		if (!response.ok) throw new Error(await readError(response, "approval"));
+	}
+	emit(sinks, event) {
+		for (const sink of [...sinks]) sink(event);
+	}
+};
+/**
+* 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],
+* );
+* ```
+*/
+function createAguiAgentChatClient(options) {
+	return new AguiAgentChatClient(options);
+}
+async function readError(response, method) {
+	try {
+		const body = await response.json();
+		if (body?.error?.message) return body.error.message;
+	} catch {}
+	if (response.status === 404) return `${method} is unavailable (404). Check that the AG-UI and control-plane endpoints are enabled.`;
+	return `${method} failed (${response.status})`;
+}
+//#endregion
+export { MISSING_AGUI_PEER, createAguiAgentChatClient };
+
+//# sourceMappingURL=agui-client.js.map