cortena-ui 1.4.2 → 1.6.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# cortena-ui
+
+Notable changes per release. Versions before 1.6.0 are recorded in the git log
+and in `../../CONSUMING.md`; this file starts where the changelog does.
+
+## 1.6.0
+
+### Added
+
+- **`cortena-ui/agent-chat`: one plain progress line per tool call** (SKILLS-9).
+  Each AG-UI tool call becomes a sentence under the assistant turn — a spinner
+  while it runs, a tick when it lands, a cross and the error envelope's message
+  when it fails, and the elapsed time on anything still running after eight
+  seconds. The list is labelled `Progress` and is deliberately NOT a live
+  region of its own: it is drawn inside the transcript, which is already
+  `role="log" aria-live="polite"`.
+  - `agent-chat/step-label.ts`: `stepLabel(toolName, args, phase)`,
+    `confirmationRequiredLabel(args)` and `humaniseId(id)` — the wording map for
+    `engram_search`, `engram_describe` and `broker_invoke`, pure and with no
+    dependency on the result.
+  - `useAgentChat` gains `steps: AgentChatStep[]`, paired by AG-UI
+    `toolCallId`. A `409 confirmation_required` result relabels the step rather
+    than failing it; an aborted or errored run ends every step still running.
+  - Steps are kept in `sessionStorage` beside the session key, so a collapsed
+    pop-up, a reload or a remount mid-run does not lose them —
+    `chat.history` cannot bring them back, because the server never sees them.
+  - New exports: `AgentSteps`, `AgentStepsProps`, `AgentChatStep`,
+    `AgentStepPhase`, `stepLabel`, `confirmationRequiredLabel`, `humaniseId`,
+    `genericLabel`, `isGenericLabel`, `truncate`, `readResultMetadata`,
+    `AgentToolResultMetadata`, `AgentToolResultMeta`, `readStoredSteps`,
+    `writeStoredSteps`, `serialiseSteps`, `stepsStorageKey`, `STEP_LIMIT`.
+
+- **The outcome of a tool call is read from `TOOL_CALL_RESULT.metadata`**
+  (SKILLS-9 review). `AgentChatBridge` forwards the metadata into
+  `AgentToolEvent.data.metadata`, and the store decides from
+  `{ toolName, isError, meta?: { status, code, message } }` — an error with
+  `meta.code === "confirmation_required"` is the broker asking a question, any
+  other error is worded from `meta.message` or the first 200 characters of the
+  result text, and everything else is done. `content` is never parsed for an
+  outcome: a Cortena tool result is `{ content: [...], details }`, so the
+  `ok: false` the client used to look for was never at the top level and every
+  failed call was drawn as a success.
+
+- **A step always stops spinning, and never claims more than it knows.** A
+  plain `RUN_FINISHED` marks every open step done with its label untouched (the
+  run succeeded, so the call did); an abort marks them `stopped` — a new,
+  neutral status, because the user asked for it and a red cross reads as a
+  fault they caused; and a step restored from storage as `running` or `paused`
+  comes back `stopped` with no message, because the page went away, not the
+  tool call. A `tool.start` for a step that has already ended is a reconnect
+  replay and is ignored.
+
+- **An interrupt is not a success** (SKILLS-9 review 2). `RUN_FINISHED` with
+  `outcome.type === "interrupt"` is cortenacore pausing the run for an approval
+  or a frontend tool with the tool call STILL OPEN, and ticking it told the user
+  a write had gone through while the card asking their permission for it was on
+  the screen. `AgentChatEvent` carries `interrupted`, and such a step becomes
+  `paused` — a second neutral status, "Waiting for your approval", no spinner
+  and no elapsed counter. The result on the continuation resolves it; a `Deny`
+  marks it `stopped`. A stored `status` is validated against the known set on
+  the way back in, and anything else is `stopped`.
+
+- **A late result cannot resurrect a dropped step** (SKILLS-9 review 2). A
+  runaway turn pushes its first calls past `STEP_LIMIT`, and their results
+  arrive afterwards; the store keeps the last 100 dropped ids and ignores them
+  rather than appending a `Working: tool` line for the oldest call of the turn
+  at the bottom of the strip.
+
+- **`isError` is believed from either witness** (SKILLS-9 review 2). A
+  `tool.error` whose metadata arrived without the field was read as a success.
+
+- **The id and the tool name are bounded** (SKILLS-9 review 2) — 80 characters,
+  in the stored projection and on `data-tool`. Neither is written by this
+  package, and 9 kB of either filled the 64 kB slot on its own.
+
+- **Bounded and sanitised labels.** Every interpolated string — an operation id,
+  a tool name, a server message — goes through `truncate`, which strips
+  `\p{Cf}` and `\p{Cc}` before the length check, so a bidi override cannot
+  reverse a line and 8 kB of catalogue id cannot fill the strip.
+
+- **Only a projection is persisted.** `id`, `toolName`, `label`, `status`,
+  `startedAt`, `endedAt`, `errorMessage` — never `args`, which are the user's
+  data. The write is debounced 250 ms and flushed on unmount, the list is capped
+  at `STEP_LIMIT` in the reducer, and the slot is capped at 64 kB, oldest first.
+
+- **Accessibility.** The elapsed counter is `aria-hidden` (it changed once a
+  second inside a live region), a running step is held out of the announcement
+  until its arguments have produced a real sentence rather than reading out
+  "Working: broker_invoke" and correcting itself, and the label span is keyed on
+  the words, so a re-word is a node replacement rather than a mutated text node
+  some screen readers never announce.
+
+### Unchanged
+
+- No change to AG-UI protocol handling beyond forwarding
+  `TOOL_CALL_RESULT.metadata`, which the bridge already parsed and dropped.
+  Streamed reasoning keeps the fix that stops a later event wiping it, now with
+  the re-attach rewind covered by a test.
+- `agent-chat` remains the only entry that can reach `@ag-ui/client`; every
+  other bundle probe is unchanged.
+
+### Bundle
+
+- `agent-chat` grows **+6.8 kB** total (2,738.6 → 2,745.4 kB) and **+5.9 kB**
+  eager (843.4 → 849.3 kB): the wording map, the step reducer and the strip.
+  Not "unmoved" — it is a new surface, and it costs what it costs. Every other
+  entry is byte-identical, and `CONSUMING.md`'s table carries the numbers.

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,197 @@ 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.
+
+### Progress steps
+
+Every AG-UI tool call becomes **one plain sentence** under the assistant turn,
+streamed as it happens: a spinner while it runs, a tick and muted text when it
+lands, a cross and the failure's `message` when it fails, and a neutral
+"Stopped" when the user pressed Stop. A step still running after eight seconds
+appends the time it has taken. The list is an `aria-live="polite"` region, so a
+screen reader hears the run rather than silence — the seconds are `aria-hidden`
+(they change every second) and a step is held out of the announcement until its
+arguments have produced a real sentence.
+
+This is not the tool strip at the foot of the panel. The strip is the record —
+tool name, arguments, output, the `ui://` resource `renderToolCall` mounts an
+MCP App from — and reading it means knowing what `broker_invoke` is. The steps
+are for the person waiting.
+
+The wording is `stepLabel(toolName, args, phase)` in `agent-chat/step-label.ts`,
+a pure function with no network and no result:
+
+| the call | the line |
+| --- | --- |
+| `engram_search {intent}` | Looking for a way to \<intent\>, truncated at 80 characters |
+| `engram_describe {id: "skill.…"}` | Reading skill: \<the call's `title`, or the id's last segment\> |
+| `engram_describe {id}` | Checking how to \<id as words: `tasks.task.list` → "tasks task list"\> |
+| `broker_invoke {operation, confirmed: true}` | Doing: \<operation\>, then Done: \<operation\> |
+| `broker_invoke {operation}` | Fetching \<operation\> |
+| anything else, or arguments not yet arrived | Working: \<tool name\> |
+
+A step that finished on that last line is re-worded if its arguments arrive
+late; a step that already has a real sentence keeps it.
+
+Two of those need saying out loud. **An unconfirmed invoke is worded as a
+read** — "Fetching …" — because the client cannot know read from write before
+the reply comes back; only the catalogue knows, and the model only sets
+`confirmed` once the user has said yes. And a result whose code is
+`confirmation_required` is **not** drawn as a failure: the step keeps its tick
+and is relabelled "Needs your confirmation: \<operation\>", which is what the
+broker is actually saying.
+
+Every string interpolated into a label — an intent, a title, an operation id, a
+tool name, a server's message — is bounded at 80 characters (200 for a failure
+message) and stripped of control and format characters first, so a catalogue
+entry cannot fill the strip and a U+202E cannot reverse it.
+
+#### How a step knows it failed
+
+**`TOOL_CALL_RESULT.metadata`, and nothing else.** The contract cortenacore
+emits, and the only thing this client reads:
+
+```jsonc
+metadata: {
+  toolName: "broker_invoke",
+  isError: true,
+  meta: { status: 409, code: "confirmation_required", message: "Set confirmed=true." }
+}
+```
+
+`meta` is optional; where it is absent, only `isError` can be trusted. An error
+with `meta.code === "confirmation_required"` is the question above; any other
+error is worded from `meta.message`, or from the first 200 characters of the
+result text when there is none.
+
+`content` is **never** parsed for an outcome. It is the result as the model sees
+it — for a Cortena tool, `{ content: [{ type: "text", text }], details }` — and
+looking for an `ok: false` in it is guessing at a shape nobody promised.
+
+Steps live in `useAgentChat`'s `steps`, are cleared when the next run starts,
+and are kept in `sessionStorage` beside the session key. That last part is not
+decoration: `chat.history` has no steps in it — the server never sees them — so
+a collapsed pop-up, a reload or a host remount mid-run would otherwise lose the
+whole strip. `AgentSteps` is exported for a host that wants to draw them
+somewhere else.
+
+#### What is kept, and where
+
+Steps are held in memory with their `args`, and **only a projection is
+persisted**: `id`, `toolName`, `label`, `status`, `startedAt`, `endedAt`,
+`errorMessage`. A call's arguments are the user's data and do not belong in a
+store every script on the origin can read; the label is already derived from
+them. The write is debounced by 250 ms and flushed on unmount, the list is
+capped at 50 steps, and the slot is capped at 64 kB with the oldest dropped
+first. A step restored with `status: "running"` comes back as "Interrupted." —
+the run that owned it is gone, and no result will ever arrive.
+
+### 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
@@ -175,7 +407,7 @@ from `@a2ui/*` is installed, so `vitest.config.ts` has no entry for it.
 pnpm check        # types
 pnpm lint:design  # no literals where a token exists; no dangling var()
 pnpm build        # dist/ via tsdown (ESM + d.ts); also runs on prepack
-pnpm test         # the browser suite, then the bundle budgets
+pnpm test         # changed-only: the suites of this package your diff affects
 pnpm test:bundle  # bundle budgets alone (builds first, then real Vite apps)
 pnpm bundle:probe # the size table, printed, without asserting anything
 pnpm guide        # three-theme guide on a local Vite server
@@ -205,7 +437,7 @@ guide/                Vite app: ?theme=light|dark|system frames, or all three
 ## Releasing
 
 ```bash
-pnpm ui:check && pnpm ui:test        # browser suite, then the bundle budgets
+pnpm ui:check && FORCE_FULL=1 pnpm test:all   # types, token lint, every suite
 cd packages/ui && npm version minor && npm publish   # prepack builds dist/
 git push --follow-tags
 ```

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