@artooi/ag-ui-web-component 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -7,6 +7,229 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] — 2026-08-30
+
+### Changed
+
+- **The rating pair is off unless a host asks for it.** `data-message-actions`
+  now defaults to `copy,retry`; thumbs need
+  `data-message-actions="copy,retry,feedback"`.
+
+  Copy and retry work with nothing wired -- copy reads the DOM, retry drives this
+  element. The rating pair does not: it fires `ag-ui-feedback` and stores nothing
+  by design, because a rating belongs to whatever the host already uses for
+  product signal. With no listener the buttons still latch `aria-pressed`, which
+  is deliberate -- a rating is a standing statement about a message -- so a
+  reader is told their rating was taken, a screen reader announces it as pressed,
+  and nothing recorded anything.
+
+  This README has said since the row shipped that two buttons leading nowhere are
+  worse than none. Defaulting them on was that sentence being false. Neither
+  known consumer of this component listens for the event, so both were shipping
+  exactly the buttons the sentence warns about.
+
+  The row shipped two days ago in 0.29.0, so the population relying on the old
+  default is close to nobody, and a host that does listen restores them with one
+  attribute.
+
+
+## [0.30.0] — 2026-08-30
+
+### Added
+
+- **The sub-agent fixture was re-copied after the server added a `timestamp` to
+  every `CUSTOM` event.** Reading the wire rather than the prose is what found
+  that gap: `CUSTOM` was the only event type in the stream without one. The
+  client needed no change to absorb it — the field is additive and ignored here —
+  which is the degradation story working, and the copy is byte-identical to the
+  producer's again.
+
+- **A delegated sub-agent's progress, on the card that delegated it.** A run that
+  hands work to a sub-agent read as a stall: the parent's `delegate_task` card
+  sat at "running..." for the child's entire duration, however many tools the
+  child called, with nothing on screen. The component now consumes the AG-UI
+  `CUSTOM` event named `ag_ui.subagent` and draws it — the first real consumer of
+  the `onCustomEvent` carrier opened in 0.29.0.
+
+  **It attaches rather than floats, because the wire lets it.** `delegationId` is
+  the *parent's own* `delegate_task` tool-call id, not the child's run id, so the
+  thing being narrated is a card this component already drew on
+  `TOOL_CALL_START`. The surface is one collapsed row inside that card, carrying
+  the server's pre-rendered `status` line and nothing else, expanding onto the
+  child agent's own tool calls. A ten-step child costs one row until somebody
+  opens it, and there is no second visual language to learn.
+
+  Two alternatives were considered and dropped. A bare status line is cheaper and
+  gives up the detail entirely. Inline child cards in the main transcript
+  interleave parent and child with nothing marking whose is whose — and in an
+  order the persisted transcript, which never held the progress, cannot
+  reproduce.
+
+  **A failure carries no exception text on this channel, and none is invented
+  here.** That is the same reasoning that redacts a `RUN_ERROR`: an exception's
+  words are written for an operator. The detail rides the ordinary
+  `TOOL_CALL_RESULT` for that delegation and lands in the same card's result
+  region, a few pixels below the row that reported the failure.
+
+  **Nothing is persisted or replayed.** A `CUSTOM` event never enters the message
+  list, which is the correct half of the carrier split — a delegation that was
+  live an hour ago is not live now. Reload mid-run and the tool card is still
+  there while the nested detail is not; that is the intended behaviour rather
+  than a gap. Like `ag_ui.invalidate`, the name is routed rather than forwarded,
+  so it does not also arrive as an `ag-ui-custom` event; every other name still
+  reaches the host untouched.
+
+  A child's calls are keyed by the child's own `toolCallId`, so the `tool_call`
+  that opens one and the `tool_result` that settles it are one row updated in
+  place. The wire's tri-state `ok` is kept as one: absent while the call runs,
+  and only then a mark, since flattening "in flight" into "failed" would draw
+  every running call as a failure for as long as it ran. The row sits outside the
+  card body so it survives every `data-tool-display` mode — a progress line
+  visible only in `full` would leave the stall it exists to end.
+
+  New parts: `tool-card-subagent` on the card's region, and `subagent`,
+  `subagent-row`, `subagent-icon`, `subagent-status`, `subagent-steps`,
+  `subagent-step`, `subagent-step-icon`, `subagent-step-name` inside it. New
+  strings: `subAgentWorking`, `subAgentSteps`.
+
+  Tested against a fixture generated by the server's own encoder rather than a
+  hand-written double, replayed both through the subscriber and, in Chromium,
+  through the real `HttpAgent` from Server-Sent Events — with the resulting boxes
+  measured at sidebar and phone widths, since the row is a new control in a card
+  that already existed.
+
+- **`formatToolPayload` — a host hook for what a tool card's body says.** The
+  card pretty-printed its two payloads as JSON and offered no way in, so a
+  thirty-field result rendered as a wall of text where the host wanted a table
+  or a sentence. `ClientTool.render` could not answer it: it is handed the
+  *arguments* only, and a server-side tool has no `ClientTool` at all, which
+  left the result region the one part of the transcript a host could not reach.
+  The hook is asked about each region of each card and may return a `Node`, a
+  `string`, or `null` to leave the built-in rendering alone.
+
+  **Both halves, one hook, told apart by `kind`.** They take different code
+  paths — arguments are rendered when the card is built, the result when it
+  settles — so covering only the result would have left the other half needing a
+  second hook later, and two hooks differing only in which region they draw is a
+  worse surface than one that says which. They do not carry the same thing,
+  which is why the payload is a discriminated union rather than a flat
+  `(toolName, payload, kind)`: `arguments` hands over the parsed record the call
+  was made with, `result` the raw string the tool returned plus the outcome it
+  settled on. Flattening them would have forced every formatter to re-derive
+  which it had, and re-serialised the arguments for nothing.
+
+  **Scoped to presentation, deliberately.** The card and the model already read
+  separate copies of a tool result — the model's is maintained by
+  `@ag-ui/client` from the same event and persisted with the history, and the
+  card has always shown that string reformatted — so a formatter changes what
+  the person reads and nothing the agent reads. That is what makes restyling
+  safe here, and equally why *rewording* was rejected: renaming a value belongs
+  on the server, where it reaches the model's prose too, instead of leaving the
+  card disagreeing with the answer beside it. A returned string is set as text
+  and never parsed as markup, so this is not a second HTML channel into the
+  transcript.
+
+  A region a formatter drew is marked `data-formatted`, which relaxes the
+  preformatted whitespace the JSON block relies on — a table would otherwise
+  inherit it as mangled cell spacing. Whitespace only: the card's face, frame
+  and scroll cap stay, because the card is one visual object and a payload sized
+  for a wide page must still be contained by a sidebar. `ToolPayload`,
+  `ToolPayloadFormatter` and `ToolCallCardOptions` are exported for a host
+  building cards itself.
+
+- **`data-max-tool-rounds` — the tool-round budget is configurable.** The cap on
+  frontend tool-call to re-run rounds within one send was the constant
+  `MAX_TOOL_ROUNDS` (10) with one read and no way to change it. Ten suits a chat
+  whose tools answer questions; a page-driving deployment reaches it
+  legitimately — filling a form is one round per field — and the symptom is not
+  an error but an answer that stops mid-task, which reads as the model giving
+  up. `AgUiClientConfig.maxToolRounds` is the seam for a host driving the client
+  directly. A value below one is ignored rather than honoured: it would not be a
+  smaller budget but a send that never runs the agent at all, which would look
+  exactly like a broken endpoint. Validation lives in the client, so the
+  attribute and the config option cannot drift apart.
+
+- **`data-message-actions` — the message action row has an opt-out.** The row
+  shipped with `::part()` hooks and no off switch, and ran on every finished
+  assistant bubble; a host embedding the component in a constrained surface had
+  no way to suppress it. The attribute is a comma list of the actions to keep
+  (`copy` / `retry` / `feedback`), and `="false"` — the spelling its sibling
+  gesture `data-quote-selection` already uses — leaves none. Absent means all
+  three, so the attribute only ever subtracts and a host that never sets it
+  keeps exactly what it had.
+
+  **Per-action rather than one switch**, because the three disappear for
+  different reasons: the rating pair is only useful to a host listening for
+  `ag-ui-feedback` and is two dead buttons otherwise, retry re-runs the agent
+  which a constrained surface may forbid, and copy is the one nobody objects to.
+  A single switch would have made dropping either of the first two cost the
+  third — and a host wanting one gone would have rebuilt the row from
+  `attachMessageActions`, reimplementing the part names, the accessible grouping
+  and the retry hand-off in order to lose two buttons. With nothing left the row
+  is not built at all: an empty one still takes its margin and still announces
+  itself to a screen reader as a group of actions. `MESSAGE_ACTIONS` is exported
+  as the token vocabulary.
+
+### Changed
+
+- **`MessageActionsOptions.text` is optional**, and its absence is what omits
+  the copy button — the same idiom `onFeedback` already used, where what a
+  button needs to do its job is also the statement that it belongs. Additive for
+  existing callers.
+
+### Documentation
+
+- **The README's API reference now agrees with the source, and a test keeps it
+  there.** `tests/readme_api_surface.test.ts` asserted only that every exported
+  *name* appeared somewhere in the README, which is the weakest claim a document
+  can make about a symbol: two of the wrong descriptions below were about
+  symbols the README named correctly and then described wrongly, so they passed
+  the gate as written. It now checks the claims the README actually makes,
+  wherever those can be derived from the source cheaply — the completeness of
+  the attribute, method and property lists; the live / connect-time split
+  against `observedAttributes` itself; the members of a documented object shape
+  against the interface that declares them; the parameter count of a documented
+  call or arrow type; that every `chat.x` the README writes names a real member;
+  and the markdown mechanics that make a claim readable at all — a link
+  resolving to a heading, a table row not split by a bare `|`, a run of rows not
+  orphaned from its header. The file states its own boundary in a comment: it reads structure and
+  never semantics, so return types, parameter types, prose and inherited
+  interface members are deliberately outside it. Reimplementing a TypeScript
+  parser here would cost more than the drift it caught.
+
+- **`title-text` was documented as "the only observed attribute".** It is one of
+  eighteen, and the fourteen it did not mention are exactly the ones whose whole
+  purpose is to warn a framework host that a late attribute write is inert — so
+  the sentence told a reader that the machinery built for their case does not
+  exist. A new *When each attribute is read* subsection splits the observed set
+  into the four that are live and the fourteen that are connect-time, says what
+  a late write to each does, and names the one attribute
+  (`data-launcher-icon-url`) that is read while connecting but is not observed,
+  so a late write to that one is inert *and* silent.
+
+- **`UploadHandler` was documented without the `signal` that prevents a leak.**
+  The type takes a third `signal?: AbortSignal`, fired when the tray removes a
+  chip or the element is torn down. A tus or direct-to-S3 adapter written from
+  the two-parameter signature orphans a server-side file on every removed chip,
+  which is a storage bill rather than a visible bug. `UploadOptions` and
+  `TranscribeOptions` were each missing `credentials` for the same reason
+  nothing noticed: an omitted option reads as an option that does not exist.
+
+- **Other corrections found by the same sweep.** `parseToolCatalog` was still
+  documented with its pre-0.28.0 name-to-summary return, though it returns
+  `Record<string, ToolCatalogEntry>`; `QuestionRenderer` pointed at
+  `AgUiChat.questionRenderer`, which has never existed (the property is
+  `askUserRenderer`); `ConfirmationOptions`, `ApprovalOptions` and
+  `ApprovalRequest` each omitted a member; `quotableSelection` was documented
+  with two of its three parameters; the `TOOL_DISPLAY` constants row omitted
+  `inline` though the attribute row had it; the Methods list was eight short and
+  the Properties list nine, including the deprecated `registerStateHook` and the
+  `closeCheckpoints` / `toggleCheckpoints` pair; two rows hid an unescaped `|`
+  inside a code span, which splits the row wherever the README is rendered; a
+  paragraph with a code block sat in the middle of the attribute table, breaking
+  it into two tables and orphaning the seven rows below it; and two links
+  pointed at an `#events` section that has never existed.
+
 ## [0.29.0] — 2026-08-29
 
 ### Added
@@ -2365,7 +2588,9 @@ hosts that both arrange the page the way it expects.
 ### Notes
 - First release — exercising the automated npm OIDC publish pipeline end-to-end.
 
-[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.29.0...HEAD
+[Unreleased]: https://github.com/Artui/ag-ui-web-component/compare/v0.31.0...HEAD
+[0.31.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.30.0...v0.31.0
+[0.30.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/Artui/ag-ui-web-component/compare/v0.26.1...v0.27.0

package/README.md

@@ -49,6 +49,7 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
 - [New chat and collapse](#new-chat-and-collapse)
   - [Collapsing to the launcher](#collapsing-to-the-launcher)
 - [Tool-call display modes](#tool-call-display-modes)
+- [Delegated sub-agents](#delegated-sub-agents)
 - [Markdown rendering](#markdown-rendering)
 - [Follow-up suggestions](#follow-up-suggestions)
 - [Editing a gated call before approving it](#editing-a-gated-call-before-approving-it)
@@ -161,7 +162,7 @@ another origin, add `credentials="include"` too; see
 | --- | --- | --- |
 | `endpoint` | `endpoint` | The AG-UI endpoint URL. Required to send. Reflecting getter + setter. |
 | `credentials` | `credentials` | Cookie policy for every request the element makes: `omit` / `same-origin` / `include`. Unset means the browser default (`same-origin`), which sends no cookies cross-origin. See [Authenticating requests](#authenticating-requests). |
-| `title-text` | — | Header label; defaults to `"Assistant"`. The only **observed** attribute (live-updates the header). |
+| `title-text` | — | Header label; defaults to `"Assistant"`. Live: writing it after the element connects re-labels the header. See [When each attribute is read](#when-each-attribute-is-read). |
 | `data-tool-display` | `toolDisplay` | Tool-call card detail: `inline` / `minimal` / `compact` / `full` (default `full`). |
 | `data-text-animation` | — | Incoming-text reveal: `none` (default) / `fade` / `word`. |
 | `data-prompt-chips` | — | Present (bare, or any value but `"false"`) to surface skills as chips. |
@@ -183,6 +184,15 @@ another origin, add `credentials="include"` too; see
 | `data-launcher-icon-url` | — | Icon image URL for the collapsed launcher only, when it should differ from the header's. Falls back to `data-icon-url`; a slotted `slot="launcher"` wins over both. |
 | `data-unread-badge` | — | **On by default.** `="false"` hides the launcher's unread badge; the count and the `ag-ui-unread` event keep running. See [Collapsing to the launcher](#collapsing-to-the-launcher). |
 | `data-quote-selection` | — | **On by default.** `="false"` stops the transcript offering to quote a selection. `quote()` keeps working either way. See [Quoting a selection](#quoting-a-selection). |
+| `data-message-actions` | — | **All on by default.** A comma list of the actions a finished answer keeps: `copy` / `retry` / `feedback` (e.g. `"copy,retry"`). `="false"` removes the row entirely. See [Message actions](#message-actions-copy-retry-feedback). |
+| `data-max-tool-rounds` | — | Upper bound on frontend tool-call → re-run rounds within one send (default 10; a value below 1 is ignored). Raise it for a page-driving agent whose turn takes many small steps. See [The run loop](#the-run-loop-and-the-ag-ui-client). |
+| `data-page-actions` | — | Opt-in built-in page-action tools: a comma list of `scroll` / `drag` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
+| `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
+| `data-answer-well` | — | CSS-only boolean: box each assistant turn (its text, tool cards, and thinking) in one bordered "well". Off by default. See [The answer well](#the-answer-well). |
+| `collapsed` | `collapsed` | Reflected boolean; collapses the widget to its [launcher](#collapsing-to-the-launcher) (a rail under `placement="sidebar"`, the header bar under `embedded` / `page`). Persisted per-tab in `sessionStorage`. |
+| `theme` | — | CSS-only: `light` (default) / `dark` / `auto` / `code`. |
+| `density` | — | CSS-only: `comfortable` (default) / `compact`. |
+| `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `sidebar` / `full` / `page` / `embedded`. |
 
 Each header control also takes its own icon slot — `icon-history`, `icon-checkpoints`,
 `icon-new`, `icon-collapse` — with the built-in glyph as the fallback, so a host can project a
@@ -194,19 +204,39 @@ same way: `icon-send`, `icon-stop`, `icon-attach`, `icon-voice`.
   <svg slot="icon-new" width="16" height="16"><!-- ... --></svg>
 </ag-ui-chat>
 ```
-| `data-page-actions` | — | Opt-in built-in page-action tools: a comma list of `scroll` / `drag` (e.g. `"scroll,drag"`). See [Page-action tools](#page-action-tools). |
-| `data-side` | — | CSS-only, for `placement="sidebar"`: which edge it docks to — `right` (default) / `left`. |
-| `data-answer-well` | — | CSS-only boolean: box each assistant turn (its text, tool cards, and thinking) in one bordered "well". Off by default. See [The answer well](#the-answer-well). |
-| `collapsed` | `collapsed` | Reflected boolean; collapses the widget to its [launcher](#collapsing-to-the-launcher) (a rail under `placement="sidebar"`, the header bar under `embedded` / `page`). Persisted per-tab in `sessionStorage`. |
-| `theme` | — | CSS-only: `light` (default) / `dark` / `auto` / `code`. |
-| `density` | — | CSS-only: `comfortable` (default) / `compact`. |
-| `placement` | — | CSS-only: `floating` (default) / `bottom-left` / `side` / `sidebar` / `full` / `page` / `embedded`. |
 
-**Properties** (JS only, not attributes): `headers`, `getHeaders`, `allowImages`, `autoConfirm`,
-`confirmPredicate`, `askUser`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`,
-`getPageMap`, `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`,
-`navigationResult`, `skillContext`, `toolSummaries`, `strings`, `resolvePageTarget`, plus the
-mirrors `endpoint` / `userKey` / `toolDisplay` / `collapsed` / `credentials`.
+#### When each attribute is read
+
+The element observes two groups of attributes, and they behave differently once it is in the DOM.
+Nothing outside those groups is observed: a CSS-only attribute (`theme`, `density`, `data-side`,
+`data-answer-well`) is read by the stylesheet rather than by script, and `endpoint`,
+`data-tool-display`, `data-text-animation`, `data-runs-url`, `data-page-actions`,
+`data-message-actions`, `data-max-tool-rounds`, `data-unread-badge` and `data-quote-selection` are
+re-read at each use, so a late write to any of those simply takes effect. The one attribute in
+neither camp is `data-launcher-icon-url`: it is read while the element connects, like the group
+below, but is not observed, so a late write is inert and says nothing.
+
+**Live attributes.** Written at any time, before or after the element connects, and acted on
+either way: `title-text`, `placement`, `credentials`, `user-key`.
+
+**Connect-time attributes.** Read once, while the element connects, to decide what chrome exists at
+all — the tray, the mic, the skills menu, the header mark. Writing one afterwards has **no effect**;
+the element logs a console warning naming the attribute rather than failing silently, because the
+symptom is an affordance that never appears and that reads as a broken component. Set them before
+the element enters the DOM, or remove and re-insert it. See
+[Framework hosts](#framework-hosts-configure-before-you-insert), where the boundary bites hardest.
+The list: `data-attachments-url`, `data-attachment-accept`, `data-attachment-max-bytes`,
+`data-transcribe-url`, `data-threads-url`, `data-threads-cache`, `data-tools-url`,
+`data-skills-url`, `data-skills`, `data-prompt-chips`, `data-slash-commands`, `data-theme-toggle`,
+`data-strings`, `data-icon-url`.
+
+**Properties** (JS only, not attributes): `headers`, `getHeaders`, `trustedOrigins`, `allowImages`,
+`autoConfirm`, `confirmPredicate`, `askUser`, `askUserRenderer`, `approvalRenderer`,
+`approveWithEdits`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`, `getPageMap`,
+`autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`, `navigationResult`,
+`skillContext`, `toolSummaries`, `formatToolPayload`, `formatRelativeTime`, `strings`,
+`resolvePageTarget`, `sharedState`, plus the read-only `unread` and `unhandledActivityTypes`, and
+the attribute mirrors `endpoint` / `userKey` / `toolDisplay` / `collapsed` / `credentials`.
 
 `headers` and `getHeaders` authenticate **every** request the element makes, not only the agent
 run; `getHeaders` is the one to use for a credential that rotates. See
@@ -226,15 +256,20 @@ the django-ag-ui `@tool` registry), whose schema never reaches the browser — e
 labels are fetched automatically — per card, `x-summary` → an explicit
 `toolSummaries` entry → the fetched catalog → the raw name.
 
-**Properties** (selected): `sharedState` — AG-UI shared state (documented under Tools & state).
+`sharedState` is AG-UI shared state, documented under
+[the run loop](#the-run-loop-and-the-ag-ui-client); `unread` and `unhandledActivityTypes` are
+read-only counters, covered under [the unread badge](#the-unread-badge) and
+[finding out what arrived](#finding-out-what-arrived).
 
 Code blocks in an agent's answer carry a **copy button**, revealed on hover or
 keyboard focus and styleable via the `code-copy` part. Override its labels with
 the `copyCode` / `copied` / `copyFailed` strings.
 
-**Methods**: `registerTool`, `registerPageState`, `setSkills`, `sendMessage`, `attachFile`,
-`appendMessage`, `newChat`, `setCollapsed`, `toggleCollapsed`, `toggleTheme`, `openThreads`,
-`openCheckpoints`, `reload`.
+**Methods**: `registerTool`, `registerPageState`, `registerActivityRenderer`, `setSkills`,
+`sendMessage`, `attachFile`, `appendMessage`, `retryLastTurn`, `quote`, `offerQuoteInPage`,
+`enableCharts`, `newChat`, `setCollapsed`, `toggleCollapsed`, `toggleTheme`, `openThreads`,
+`openCheckpoints`, `closeCheckpoints`, `toggleCheckpoints`, `reload`, and the deprecated
+`registerStateHook` (renamed to `registerPageState`).
 
 ### Sending from your own UI
 
@@ -486,7 +521,12 @@ an AG-UI `AbstractAgent`. On the first send the element builds a client (via the
    render into a bubble; each `TOOL_CALL_END` becomes a tool-call card.
 3. Any **frontend** tool calls collected during the run are executed locally, their results are
    appended as `tool` messages, and the agent is re-run with the results.
-4. This repeats until the agent stops calling frontend tools, bounded by `MAX_TOOL_ROUNDS`.
+4. This repeats until the agent stops calling frontend tools, bounded by `MAX_TOOL_ROUNDS`
+   (10) — raise it with `data-max-tool-rounds`, or `AgUiClientConfig.maxToolRounds` when you
+   drive the client yourself. The default suits a chat whose tools answer questions; a
+   page-driving deployment reaches it legitimately, one round per field filled, and the symptom
+   is not an error but an answer that stops mid-task. A value below 1 is ignored rather than
+   honoured — it would be a send that never runs the agent at all.
 
 Tool calls the client doesn't own (server-side tools the server already executed) are left alone —
 the loop doesn't re-run them, but their streamed `TOOL_CALL_RESULT` is rendered into the tool-call
@@ -1076,7 +1116,7 @@ interchangeable:
 | | Carrier | Reaches | Persisted | Replayed |
 | --- | --- | --- | --- | --- |
 | **Content** | `ACTIVITY_SNAPSHOT` | the transcript | yes | yes |
-| **Imperative** | `CUSTOM` | your page, as [`ag-ui-custom`](#events) | no | no |
+| **Imperative** | `CUSTOM` | your page, as [`ag-ui-custom`](#host-seams-the-spa-story) | no | no |
 
 ⇒ **Content has a place in the conversation and should come back. An imperative
 has no place and no meaning once acted on** — replaying "refetch the board" on
@@ -1118,6 +1158,42 @@ visible. Style them via the `tool-card-args` / `tool-card-result` parts, their h
 transcript, the way `data-answer-well` does — the modes are pure visibility over one DOM shape,
 selected by the shadow CSS from the host attribute.
 
+### Drawing a card's body yourself
+
+A thirty-field result is a wall of JSON where a host wanted a table, or a
+sentence. `formatToolPayload` is the seam: it is asked about each region of each
+card and may return a `Node` to take it over, a `string` to replace its text, or
+`null` to leave the built-in pretty-print alone.
+
+```js
+chat.formatToolPayload = (payload) => {
+  if (payload.kind !== "result" || payload.toolName !== "list_orders") {
+    return null; // everything else keeps the default rendering
+  }
+  const table = document.createElement("table");
+  // ... build it from JSON.parse(payload.text)
+  return table;
+};
+```
+
+Both halves come through the same hook, told apart by `kind`: `arguments`
+carries the parsed record the call was made with, `result` the raw string the
+tool returned plus the outcome it settled on. A region a formatter took over is
+marked `data-formatted`, which relaxes the preformatted whitespace the default
+JSON block relies on — a table would otherwise inherit it as mangled cell
+spacing. Whitespace only: the card's face, frame and scroll cap stay, so one long
+payload still cannot stretch the transcript, and a host wanting different
+typography restyles the `tool-card-result` part.
+
+This is **presentation, not translation.** The card and the model already read
+separate copies of a tool result — the model's is maintained by `@ag-ui/client`
+from the same event — so a formatter changes what the person reads and nothing
+the agent reads. That is what makes restyling safe here, and it is also why
+*rewording* belongs on the server: renamed there, the new wording reaches the
+model's prose too, instead of leaving the card disagreeing with the answer beside
+it. A returned string is set as text, never parsed as markup — this is not a
+second HTML channel into the transcript.
+
 A gated call carries the decision (`approved by you` / `declined by you`, part
 `tool-card-decision`, attribute `data-decision`) — from the client-side confirmation card and
 from the server-side approval interrupt alike. The prompt itself disappears once answered: a
@@ -1144,6 +1220,72 @@ speed; the spin respects `prefers-reduced-motion`).
 
 ---
 
+## Delegated sub-agents
+
+A run that hands work to a sub-agent reads as a stall. The parent's
+`delegate_task` card sits at "running…" for the child's entire duration —
+however many tools the child calls, however long it takes — with nothing on
+screen to say anything is happening.
+
+If your server narrates that, the component draws it. The wire is an ordinary
+AG-UI `CUSTOM` event named `ag_ui.subagent`, carrying:
+
+| Key | Meaning |
+| --- | --- |
+| `delegationId` | the **parent's own `delegate_task` tool-call id** — not the child's run id |
+| `agent` | the child agent's name |
+| `phase` | one of `started`, `tool_call`, `tool_result`, `finished`, `failed` |
+| `status` | a pre-rendered line, ready to show |
+| `tool` | `toolCallId`, `name` and `ok`, on the two tool phases only |
+
+Exactly one `started` opens a delegation and exactly one `finished` or `failed`
+closes it. `ok` is a tri-state: `null` while the child's call runs, `true` on a
+result it accepted, `false` on one that came back to it.
+
+Because the key is the *parent's* call id, the surface attaches to a card that
+already exists rather than floating a second element with the same identity: one
+**collapsed row per delegation**, live, carrying the server's `status` line and
+nothing else, expanding onto the child's own tool calls. A ten-step child costs
+one row until somebody opens it, and there is no second visual language — it
+reads the way tool cards already read.
+
+`status` is why the collapsed row needs no wording of its own. The structured
+keys are there for a host that would rather write its own.
+
+The row shows in **every** [display mode](#tool-call-display-modes), including
+`minimal`. It sits outside the card body rather than in it, because the body is
+what the density modes hide — and a live progress line that only appeared in
+`full` would leave exactly the stall it exists to end. Same reasoning that shows
+a deferred card's arguments whatever the mode.
+
+**A failure carries no exception text on this channel, deliberately** — the same
+reasoning that redacts a `RUN_ERROR`, since an exception's words are written for
+an operator. The detail rides the ordinary tool result for that delegation, which
+lands in the same card's `Result` region a few pixels below. Nothing here invents
+words the server declined to send.
+
+**None of it is persisted.** A `CUSTOM` event never enters the message list, so
+nothing replays on a thread restore — which is the right half of the
+[carrier split](#which-carrier-should-the-server-use): a delegation that was live
+an hour ago is not live now, and replaying its progress would be a lie about a
+run that is over. Reload mid-run and the tool card is still there; the nested
+detail is not. That is the intended behaviour.
+
+Like `ag_ui.invalidate`, this name is **routed** rather than forwarded: it draws
+itself and does not also arrive as an `ag-ui-custom` event. Every other name
+still reaches your page untouched.
+
+Style it through `tool-card-subagent` (the region inside the card), `subagent`,
+`subagent-row`, `subagent-icon`, `subagent-status`, `subagent-steps`,
+`subagent-step`, `subagent-step-icon` and `subagent-step-name`. The two glyph
+states reuse the card's own `--ag-ui-tool-icon-done` / `--ag-ui-tool-icon-error`
+properties and its spinner speed, so re-theming the cards re-themes these. The
+row's own chrome comes from `subAgentWorking` and `subAgentSteps` in
+[`UiStrings`](#internationalization-i18n); everything else on the row is the
+server's text.
+
+---
+
 ## Resizing the panel
 
 The panel carries a drag handle on its leading corner (or leading edge, docked),
@@ -1297,7 +1439,10 @@ message's own text.
   rather than being told its last answer was wrong.
 - **Copy** puts the message's text on the clipboard, and says so on the button.
   A refused clipboard permission is reported there too, rather than thrown.
-- **Thumbs up / down** fire [`ag-ui-feedback`](#events) and **store nothing**.
+- **Thumbs up / down** fire `ag-ui-feedback` (wired below) and **store nothing**.
+  **Off unless you ask for them** — `data-message-actions="copy,retry,feedback"`.
+  Without a listener the buttons still latch, so a reader is told a rating was
+  taken while nothing recorded it.
 
 Retry sits on the **last** answer only. Re-running an older turn is branching,
 and for a page-driving agent editing a past turn is not neutral — those turns
@@ -1316,6 +1461,25 @@ less. This is why a dropped connection is still rendered as an **error** rather
 than demoted to a run notice — a notice "never settles, takes no action, and
 carries no controls", and a failure with a way back needs one.
 
+The row can be trimmed, or removed, with `data-message-actions` — a comma list of
+the actions to keep, or `="false"` for none at all:
+
+```html
+<!-- copy only: nothing here listens for a rating, and the surface forbids re-runs -->
+<ag-ui-chat endpoint="/agent/" data-message-actions="copy"></ag-ui-chat>
+```
+
+The default is `copy,retry`. Those two work with nothing wired; the rating pair
+needs a listener, so it is asked for rather than assumed.
+
+It is per-action rather than one switch because the three disappear for
+different reasons. Thumbs are only useful to a host listening for
+`ag-ui-feedback`, and two buttons that lead nowhere are worse than none. Retry
+re-runs the agent, which a constrained surface may not permit. Copy is the one
+nobody objects to — and with a single switch, dropping either of the others would
+have cost it too. Nothing survives, and no row is built at all: an empty row
+still takes its margin and still announces itself as a group of actions.
+
 `retryLastTurn()` is public, for a host driving its own message UI.
 
 ```js
@@ -1963,9 +2127,9 @@ re-export point. Internal modules import from leaf paths.
 | `isNavigates(parameters)` | function | Read the `x-navigates` flag. |
 | `createPageActionTools(enabled, resolveTarget)` | function | Build the opt-in `scroll_to` / `drag_and_drop` tools. |
 | `PAGE_ACTIONS` | const | The page-action opt-in tokens (`scroll` / `drag`). |
-| `ResolvePageTarget` | type | `(target) => HTMLElement | null` — the page-target resolver. |
+| `ResolvePageTarget` | type | `(target) => HTMLElement \| null` — the page-target resolver. |
 | `X_DESTRUCTIVE_KEY` / `X_NAVIGATES_KEY` | const | The JSON-Schema extension keys. |
-| `parseToolCatalog(data)` | function | Parse a fetched `data-tools-url` catalog into a `name` → `summary` map. |
+| `parseToolCatalog(data)` | function | Parse a fetched `data-tools-url` catalog into a `Record<string, ToolCatalogEntry>` — whole entries, not bare summaries, so a caller can reach `description` too. Malformed input yields an empty map rather than throwing. |
 | `ToolCatalogEntry` | type | One row of that catalog. |
 | `prettifyToolName(name)` | function | Last fallback of the tool-card label chain (`delete_record` reads as *Delete record*). |
 
@@ -2008,15 +2172,15 @@ re-export point. Internal modules import from leaf paths.
 | `RunIndex` | class | Reads a `data-runs-url` run index and derives its resume / fork endpoints. |
 | `RunRow` | type | One run index row (`{ run_id, thread_id, parent_run_id, started_at, continuable, preview? }`). |
 | `CheckpointMenu` | class | The *Continue a run* panel. |
-| `CheckpointVerb` | type | `"resume" | "fork"`. |
+| `CheckpointVerb` | type | `"resume" \| "fork"`. |
 
 ### Attachments
 
 | Export | Kind | Summary |
 | --- | --- | --- |
 | `uploadAttachment(file, options)` | function | The built-in upload (multipart, progress) → `AttachmentRef`. |
-| `UploadOptions` | type | `{ url, headers?, onProgress?, signal? }`. |
-| `UploadHandler` | type | `(file, onProgress) => Promise<AttachmentRef>` — the `uploadHandler` swap seam (TUS / S3). |
+| `UploadOptions` | type | `{ url, headers?, credentials?, onProgress?, signal? }`. `credentials` is spelled as a fetch mode but carried by `XMLHttpRequest.withCredentials`, so only `"include"` is distinguishable. |
+| `UploadHandler` | type | `(file, onProgress, signal?) => Promise<AttachmentRef>` — the `uploadHandler` swap seam (tus / S3). The signal fires when the tray removes a chip or the element is torn down; a handler that honours it aborts its own transport, so a cancelled upload leaves no orphaned file on the server. |
 | `AttachmentRef` | type | The durable upload ref (`{ id, name, mime, size, url? }`). |
 | `messageAttachments(message)` | function | Read the refs a restored user message carries. |
 
@@ -2025,7 +2189,7 @@ re-export point. Internal modules import from leaf paths.
 | Export | Kind | Summary |
 | --- | --- | --- |
 | `transcribeAudio(audio, options)` | function | The built-in transcription POST (multipart) → the transcript text. |
-| `TranscribeOptions` | type | `{ url, headers? }`. |
+| `TranscribeOptions` | type | `{ url, headers?, credentials? }` — `credentials` as fetch's own cookie mode. |
 | `TranscribeHandler` | type | `(audio) => Promise<string>` — the `transcribeHandler` swap seam (Web Speech, direct-to-provider). |
 
 ### UI & DOM primitives
@@ -2034,28 +2198,31 @@ re-export point. Internal modules import from leaf paths.
 | --- | --- | --- |
 | `ToolCallCard` | class | A live tool-call card for the transcript. |
 | `ToolCallStatus` / `SettledStatus` / `ToolDisplayMode` | type | Card lifecycle states + display mode. |
+| `ToolPayloadFormatter` | type | Draws one region of a card's body (`AgUiChat.formatToolPayload`); `null` falls through to the built-in pretty-print. |
+| `ToolPayload` | type | The region being drawn: `arguments` (the parsed record) or `result` (the raw string and its outcome). |
+| `ToolCallCardOptions` | type | Per-card wiring beyond name / args / label / strings — currently `formatPayload`. |
 | `requestConfirmation(host, request, options?)` | function | Append the inline confirmation card to the transcript. |
 | `ConfirmationRequest` | type | What the card displays. |
-| `ConfirmationOptions` | type | `{ signal?, strings? }` — abort resolves the card as declined; `strings` localizes it. |
+| `ConfirmationOptions` | type | `{ signal?, strings?, onAlwaysAllow? }` — abort resolves the card as declined; `strings` localizes it; passing `onAlwaysAllow` is what adds the third button. |
 | `UiStrings` | type | The flat table of every user-facing string. |
 | `DEFAULT_UI_STRINGS` | const | The English defaults (the override floor). |
 | `mergeUiStrings(overrides)` | function | Merge a partial override over the defaults. |
 | `renderMarkdown(text, options?)` | function | Render sanitized markdown/HTML (marked + DOMPurify). |
 | `RenderMarkdownOptions` | type | `{ allowImages? }` — opt `<img>` back into the sanitized output. |
 | `requestApproval(host, request, options?)` | function | Append the inline approval card that gates a server-side tool. |
-| `ApprovalRequest` | type | What that card displays (`{ message?, toolName? }`). |
-| `ApprovalOptions` | type | `{ signal?, strings? }` — abort resolves the card as denied; `strings` localizes it. |
+| `ApprovalRequest` | type | What that card displays (`{ message?, toolName?, args? }`). |
+| `ApprovalOptions` | type | `{ signal?, strings?, onEdit? }` — abort resolves the card as denied; `strings` localizes it; passing `onEdit` offers the call's arguments for editing and is called only when they actually changed. |
 | `ApprovalRenderer` | type | Replace the built-in approval card outright (`AgUiChat.approvalRenderer`). |
 | `requestQuestion(host, request, options?)` | function | Append the inline `ask_user` card (radios and/or free text). |
 | `QuestionRequest` | type | What that card asks. |
 | `QuestionOptions` | type | `{ signal?, strings? }` — abort resolves it with an empty answer. |
-| `QuestionRenderer` | type | Replace the built-in question card outright (`AgUiChat.questionRenderer`). |
+| `QuestionRenderer` | type | Replace the built-in question card outright (`AgUiChat.askUserRenderer`). |
 | `renderChart(spec)` | function | Draw one spec as a self-contained block, or `null` when it says nothing. |
 | `chartSpecFrom(value)` | function | Read an arbitrary payload into a `ChartSpec`, or `null` if it cannot be drawn honestly. |
 | `ChartSpec` / `ChartSeries` / `ChartKind` | type | A chart as data, one named series, and how it is drawn. |
 | `attachQuoteOffer(options)` | function | The page-side select-then-quote offer, with its guards. `AgUiChat.offerQuoteInPage()` is the one-line form. |
 | `PageQuoteOffer` / `PageQuoteOfferOptions` | type | The live offer (`{ element, detach }`) and what it takes. |
-| `quotableSelection(container, roots)` | function | The current selection when it lies inside `container`, read through the shadow-aware API where the engine has one. |
+| `quotableSelection(container, roots, near?)` | function | The current selection when it lies inside `container`, read through the shadow-aware API where the engine has one. `near` is where the gesture ended, used to pick the line the offer hangs from. |
 | `QuotableSelection` | type | `{ text, rect }` — what was selected, and where it sits. |
 | `asQuote(text)` | function | Shape text as a markdown blockquote with a blank line after it. |
 | `MAX_QUOTE_CHARS` | const | The cap a quotation is truncated to (500). |
@@ -2087,8 +2254,9 @@ re-export point. Internal modules import from leaf paths.
 | `COMPACTION_ACTIVITY_TYPE` | The `ACTIVITY_SNAPSHOT` type reporting a trimmed history. |
 | `LOAD_CAPABILITY_TOOL` | The agent-side capability-loading tool's name. |
 | `MESSAGE_ROLE` | Message role constants. |
+| `MESSAGE_ACTIONS` | The message-action tokens `data-message-actions` selects by (`copy` / `retry` / `feedback`). |
 | `TOOL_CALL_STATUS` | Tool-call card status constants. |
-| `TOOL_DISPLAY` | Tool-call display-mode constants (`minimal` / `compact` / `full`). |
+| `TOOL_DISPLAY` | Tool-call display-mode constants (`inline` / `minimal` / `compact` / `full`). |
 | `X_CONFIRM_KEY` | Confirmation-prompt key: on a tool's JSON Schema for a client-side confirmation, and in an AG-UI interrupt's `metadata` for a server-side approval. |
 | `X_SUMMARY_KEY` | JSON-Schema key carrying a short tool-card label. |
 | `MAX_TOOL_ROUNDS` | Upper bound on tool-call → re-run rounds per send. |
@@ -2227,7 +2395,8 @@ component sets, so a new one cannot ship undocumented.
 | Follow-up suggestions | `suggestions`, `suggestion-chip` |
 | Message actions | `message-actions`, `message-action` (plus `message-action-retry`, `message-action-copy`, `message-action-up`, `message-action-down`) |
 | Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`, `run-notice-history-replaced`, `run-notice-chart-undrawable`), `run-notice-icon`, `run-notice-text` |
-| Tool cards | `tool-card`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval` |
+| Tool cards | `tool-card`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval`, `tool-card-subagent` |
+| Delegated sub-agents | `subagent`, `subagent-row`, `subagent-icon`, `subagent-status`, `subagent-steps`, `subagent-step`, `subagent-step-icon`, `subagent-step-name` |
 | Client-side confirmation | `confirm`, `confirm-body`, `confirm-args`, `confirm-actions`, `confirm-button` (plus `confirm-confirm`, `confirm-cancel`, `confirm-always`) |
 | Server-side approval | `approval`, `approval-body`, `approval-actions`, `approval-button` (plus `approval-approve`, `approval-deny`), `approval-edit`, `approval-args`, `approval-error` |
 | Typed question | `question`, `question-body`, `question-options`, `question-choice`, `question-choice-text`, `question-radio`, `question-input`, `question-actions`, `question-button` |