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

package/dist/ui/tool_call_card.d.ts

@@ -8,6 +8,56 @@ export type ToolDisplayMode = (typeof TOOL_DISPLAY)[keyof typeof TOOL_DISPLAY];
 export type UnsettledStatus = typeof TOOL_CALL_STATUS.PENDING | typeof TOOL_CALL_STATUS.DEFERRED;
 /** The terminal states a card settles into (everything unsettled excluded). */
 export type SettledStatus = Exclude<ToolCallStatus, UnsettledStatus>;
+/**
+ * One region of a card's body, handed to a host {@link ToolPayloadFormatter}.
+ *
+ * A discriminated union rather than three positional parameters because the two
+ * halves do not carry the same thing: arguments are the parsed record the call
+ * was made with, and a result is the raw string the tool returned, which may not
+ * be JSON at all. Flattening both into one `payload` parameter would force every
+ * formatter to re-derive which it had before it could read it, and the
+ * arguments would arrive re-serialised for no reason.
+ *
+ * `toolName` is the raw tool name, not the card's `x-summary` label -- a
+ * formatter dispatches on identity, and the label is a display string a server
+ * may change.
+ */
+export type ToolPayload = {
+    readonly kind: "arguments";
+    readonly toolName: string;
+    readonly args: Record<string, unknown>;
+} | {
+    readonly kind: "result";
+    readonly toolName: string;
+    readonly status: SettledStatus;
+    readonly text: string;
+};
+/**
+ * Renders one region of a tool card's body, for a host that would rather show a
+ * table or a summary line than a wall of pretty-printed JSON.
+ *
+ * Return a `Node` to take the region over, a `string` to replace its text, or
+ * `null` to fall through to the built-in pretty-print -- so a formatter that
+ * only cares about one tool, or only about results, declines the rest rather
+ * than reimplementing them.
+ *
+ * **Presentation only.** The model reads the tool result from its own copy of
+ * the message, which this never touches, so anything said here is said to the
+ * person and not to the agent. Translating a value -- an enum constant into a
+ * friendly label, an epoch into a date -- belongs on the server, where it also
+ * reaches the model's prose; doing it here would make the card and the answer
+ * beside it disagree about what happened.
+ *
+ * A returned string is set as text, never parsed as markup: this is not a
+ * second HTML channel into the transcript, and a host that wants elements
+ * builds them itself and returns the node.
+ */
+export type ToolPayloadFormatter = (payload: ToolPayload) => Node | string | null;
+/** Optional per-card wiring beyond the name, arguments, label and strings. */
+export interface ToolCallCardOptions {
+    /** Host presentation hook for both body regions. See {@link ToolPayloadFormatter}. */
+    readonly formatPayload?: ToolPayloadFormatter;
+}
 /**
  * A live tool-call card for the chat transcript.
  *
@@ -27,6 +77,12 @@ export type SettledStatus = Exclude<ToolCallStatus, UnsettledStatus>;
  * `--ag-ui-tool-icon-*` custom properties or the `tool-card-icon` part without
  * the card reaching into the host stylesheet.
  *
+ * Either region may be drawn by the host instead: `options.formatPayload` is
+ * asked about each one and pretty-prints as before whenever it declines. The
+ * arguments are offered from the constructor and the result from {@link settle},
+ * because that is when each exists -- so a formatter is asked twice per card,
+ * potentially long apart.
+ *
  * Pure DOM. The host appends {@link element} into its shadow root; all visible
  * text comes from {@link UiStrings}.
  */
@@ -48,6 +104,22 @@ export declare class ToolCallCard {
      * Empty until used, and hidden while empty by the shadow CSS.
      */
     readonly approvalSlot: HTMLDivElement;
+    /**
+     * Where a *nested* run's progress renders — the sub-agent this call delegated
+     * to, narrating itself while the card waits.
+     *
+     * A slot rather than a rendered thing, on the same reasoning as
+     * {@link approvalSlot}: the card owns the position and something else owns the
+     * content. What makes the position right is that the wire keys a delegation on
+     * this card's own `toolCallId`, so the run being narrated is the one this card
+     * already stands for.
+     *
+     * Placed above the Details toggle rather than inside the body, because the
+     * body is what the display modes hide — and a progress line that only appears
+     * in `full` mode would leave exactly the stall it exists to end. Empty on every
+     * card that delegated nothing, and hidden while empty by the shadow CSS.
+     */
+    readonly subagentSlot: HTMLDivElement;
     /**
      * The arguments this call was made with.
      *
@@ -56,7 +128,7 @@ export declare class ToolCallCard {
      * still exist when the user is asked to approve, edit or deny the call.
      */
     readonly args: Record<string, unknown>;
-    constructor(name: string, args: Record<string, unknown>, summary?: string, strings?: UiStrings);
+    constructor(name: string, args: Record<string, unknown>, summary?: string, strings?: UiStrings, options?: ToolCallCardOptions);
     /**
      * Move between the two states that are not an outcome — `pending` (running)
      * and `deferred` (gated, waiting on a person).

package/dist/ui/tool_call_card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool_call_card.d.ts","sourceRoot":"","sources":["../../src/ui/tool_call_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEtF,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE/E,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC,OAAO,GAAG,OAAO,gBAAgB,CAAC,QAAQ,CAAC;AAEjG,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;AA+BrE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;;IACvB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IAStC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAGvC,YACE,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,SAA8B,EAwExC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAMlC;IAED;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAKlD;IAED,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAYhD;CAoCF"}
+{"version":3,"file":"tool_call_card.d.ts","sourceRoot":"","sources":["../../src/ui/tool_call_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEtF,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE/E,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC,OAAO,GAAG,OAAO,gBAAgB,CAAC,QAAQ,CAAC;AAEjG,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;AA+BrE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEN;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;AAElF,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,YAAY;;IACvB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IAStC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMvC,YACE,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,SAA8B,EACvC,OAAO,GAAE,mBAAwB,EAkFlC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAMlC;IAED;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAKlD;IAED,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAgBhD;CAkEF"}

package/dist/ui/ui_strings.d.ts

@@ -123,6 +123,16 @@ export interface UiStrings {
     declinedLabel: string;
     /** Label on the toggle that expands a tool card's body. */
     details: string;
+    /**
+     * The delegation row's text before the server's own status line lands.
+     *
+     * A fallback, not a state: every announcement carries a pre-rendered `status`,
+     * and this only shows if one arrives unusable. The row is the expander, so it
+     * must never be blank.
+     */
+    subAgentWorking: string;
+    /** `aria-label` of the region holding the sub-agent's own tool calls. */
+    subAgentSteps: string;
     /** `aria-label` of the editable arguments field on an approval card. */
     approvalEditArgs: string;
     /** Shown when the edited arguments are not valid JSON. */

package/dist/ui/ui_strings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui_strings.d.ts","sourceRoot":"","sources":["../../src/ui/ui_strings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ui_strings.d.ts","sourceRoot":"","sources":["../../src/ui/ui_strings.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artooi/ag-ui-web-component",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Framework-free <ag-ui-chat> Web Component over the AG-UI protocol. Drop-in chat sidebar with a pluggable client-side tool registry, DOM driver primitives, animations, and destructive-action confirmation modal.",
   "type": "module",
   "main": "./dist/index.js",

package/src/constants.ts

@@ -119,6 +119,45 @@ export const SUGGESTIONS_ACTIVITY_TYPE = "suggestions";
  */
 export const INVALIDATE_CUSTOM_NAME = "ag_ui.invalidate";
 
+/**
+ * The AG-UI `CUSTOM` event `name` carrying a delegated sub-agent's progress.
+ *
+ * Matched exactly, and namespaced the way {@link INVALIDATE_CUSTOM_NAME} is, so
+ * it cannot collide with a host's own custom events on the same open field.
+ *
+ * Routed to the delegating tool card rather than dispatched to the page: the
+ * payload keys on the **parent's own `delegate_task` call id**, so what it
+ * describes is already on screen and the progress belongs beside it. Every other
+ * name still reaches the host as {@link CUSTOM_AGENT_EVENT}.
+ *
+ * Deliberately on the imperative carrier and not on an activity, which means it
+ * is **never persisted and never replayed**. That is the right half of the
+ * split: a delegation that was live an hour ago is not live now, and replaying
+ * its progress on a thread restore would be a lie about a run that is over. On a
+ * reload mid-run the nested detail is gone and the tool card remains.
+ */
+export const SUBAGENT_CUSTOM_NAME = "ag_ui.subagent";
+
+/**
+ * The phases one delegation moves through, as the server spells them.
+ *
+ * Exactly one `STARTED` opens a delegation and exactly one `FINISHED` or
+ * `FAILED` closes it; the two tool phases repeat in between, once per call the
+ * child makes and once per result it gets back.
+ *
+ * `FAILED` carries **no exception text**, 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_CALL_RESULT` for that delegation, on the
+ * card the progress is already attached to.
+ */
+export const SUBAGENT_PHASE = {
+  STARTED: "started",
+  TOOL_CALL: "tool_call",
+  TOOL_RESULT: "tool_result",
+  FINISHED: "finished",
+  FAILED: "failed",
+} as const;
+
 /** Roles a chat message can take. */
 export const MESSAGE_ROLE = {
   USER: "user",
@@ -158,9 +197,32 @@ export const X_NAVIGATES_KEY = "x-navigates";
  */
 export const READ_PAGE_TOOL = "read_page";
 
-/** Upper bound on frontend tool-call → re-run rounds within one send. */
+/**
+ * Default upper bound on frontend tool-call → re-run rounds within one send.
+ * Overridable via `data-max-tool-rounds`, or `AgUiClientConfig.maxToolRounds`
+ * for a host driving the client directly.
+ */
 export const MAX_TOOL_ROUNDS = 10;
 
+/**
+ * The actions a finished assistant message's row can carry, and the tokens
+ * `data-message-actions` selects them by.
+ *
+ * All three are on when the attribute is absent. Naming them individually
+ * rather than shipping one on/off switch is what the three differ over: feedback
+ * is only useful to a host listening for {@link FEEDBACK_EVENT}, retry re-runs
+ * the agent and a constrained surface may not permit that, and copy is the one
+ * nobody objects to. A single switch would make dropping either of the first two
+ * cost the third, and a host that only wanted one gone would rebuild the row
+ * from `attachMessageActions` -- reimplementing the part names, the accessible
+ * grouping and the retry hand-off to lose two buttons.
+ */
+export const MESSAGE_ACTIONS = {
+  COPY: "copy",
+  RETRY: "retry",
+  FEEDBACK: "feedback",
+} as const;
+
 /**
  * Lifecycle status of a rendered tool-call card. A card opens as `PENDING`
  * while the call runs, then settles to `DONE`, `ERROR`, or `DECLINED`.

package/src/core/ag_ui_chat.ts

@@ -15,10 +15,13 @@ import {
   INVALIDATE_CUSTOM_NAME,
   INVALIDATE_EVENT,
   LOAD_CAPABILITY_TOOL,
+  MAX_TOOL_ROUNDS,
+  MESSAGE_ACTIONS,
   MESSAGE_ROLE,
   READ_PAGE_TOOL,
   RUN_FINISHED_EVENT,
   STATE_EVENT,
+  SUBAGENT_CUSTOM_NAME,
   SUBMIT_EVENT,
   SUGGESTIONS_ACTIVITY_TYPE,
   TOGGLE_EVENT,
@@ -79,10 +82,16 @@ import { renderRunNotice } from "../ui/run_notice.js";
 import { SkillsMenu } from "../ui/skills_menu.js";
 import { createStickToBottom, type StickToBottom } from "../ui/stick_to_bottom.js";
 import { STYLES } from "../ui/styles.js";
+import { SubAgentPanel } from "../ui/subagent_panel.js";
+import { subAgentUpdate } from "../ui/subagent_update.js";
 import { renderSuggestionChips } from "../ui/suggestion_chips.js";
 import { ThoughtsBlock } from "../ui/thoughts_block.js";
 import { ThreadDrawer } from "../ui/thread_drawer.js";
-import { ToolCallCard, type ToolDisplayMode } from "../ui/tool_call_card.js";
+import {
+  ToolCallCard,
+  type ToolDisplayMode,
+  type ToolPayloadFormatter,
+} from "../ui/tool_call_card.js";
 import { DEFAULT_UI_STRINGS, mergeUiStrings, type UiStrings } from "../ui/ui_strings.js";
 import { VoiceInput } from "../ui/voice_input.js";
 import {
@@ -532,6 +541,31 @@ export class AgUiChat extends HTMLElement {
    */
   toolSummaries: Record<string, string> = {};
 
+  /**
+   * Optional presentation hook for the two payload regions of a tool-call card
+   * -- the arguments and the result. Unset (the default) leaves both
+   * pretty-printed as JSON.
+   *
+   * The seam exists because a wide result has no good rendering as JSON: a
+   * thirty-field row is a wall of text where the host wanted a table, or a
+   * sentence. `ClientTool.render` cannot answer it -- it is handed the
+   * *arguments* only, and a server-side tool has no `ClientTool` at all, so the
+   * result region was the one part of the transcript a host could not reach.
+   *
+   * **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 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 -- which makes restyling safe
+   * and *rewording* a way to make the card disagree with the prose beside it.
+   * Rename a value on the server, where it reaches both.
+   *
+   * Read at render time rather than captured, so a host that sets it from a
+   * framework effect after the first card still formats the results that settle
+   * afterwards. See {@link ToolPayloadFormatter}.
+   */
+  formatToolPayload: ToolPayloadFormatter | null = null;
+
   /**
    * Localizable UI strings — a partial override merged over the English
    * {@link DEFAULT_UI_STRINGS}. Resolved once on connect (so set it before the
@@ -586,6 +620,16 @@ export class AgUiChat extends HTMLElement {
   readonly #toolRegistry = new ClientToolRegistry();
   /** Tool-call cards awaiting execution, keyed by call id. */
   readonly #toolCards = new Map<string, ToolCallCard>();
+  /**
+   * The live delegation panels, keyed by the **parent's** `delegate_task` call
+   * id — which is what the wire keys a sub-agent's progress on, so this map and
+   * {@link #toolCards} answer to the same key.
+   *
+   * Kept beside the cards rather than on them, so a card stays a card: the tool
+   * card holds the slot and this holds what went into it, the same division the
+   * approval prompt already uses.
+   */
+  readonly #subagentPanels = new Map<string, SubAgentPanel>();
   /**
    * Call ids whose card was already settled from a streamed server-side result
    * (`TOOL_CALL_RESULT`), so the post-run executeTool sweep doesn't overwrite
@@ -1744,6 +1788,42 @@ export class AgUiChat extends HTMLElement {
     this.#quoting = "";
   }
 
+  /**
+   * The tool-round budget from `data-max-tool-rounds`, for one send.
+   *
+   * Anything unparseable becomes `NaN`, which {@link AgUiClient} rejects along
+   * with a bound below one -- so the two ways of setting this are validated in
+   * one place rather than agreeing by coincidence.
+   */
+  #maxToolRounds(): number {
+    const attr = this.getAttribute("data-max-tool-rounds");
+    return attr === null ? MAX_TOOL_ROUNDS : Number.parseInt(attr, 10);
+  }
+
+  /**
+   * Which message actions a finished bubble offers, from
+   * `data-message-actions`.
+   *
+   * Absent means all of them, so the attribute only ever subtracts: the row
+   * shipped without an off switch and a host that never sets this must keep
+   * exactly what it had. A value names the survivors, which makes
+   * `data-message-actions="false"` -- the spelling its sibling
+   * `data-quote-selection` uses -- an empty set by falling out of the same rule
+   * rather than by a case of its own.
+   */
+  #messageActions(): ReadonlySet<string> {
+    const attr = this.getAttribute("data-message-actions");
+    if (attr === null) {
+      return new Set(Object.values(MESSAGE_ACTIONS));
+    }
+    return new Set(
+      attr
+        .split(",")
+        .map((token) => token.trim())
+        .filter((token) => token !== ""),
+    );
+  }
+
   /** The client-side upload size cap from `data-attachment-max-bytes`. */
   #attachmentMaxBytes(): number {
     const attr = this.getAttribute("data-attachment-max-bytes");
@@ -2381,6 +2461,11 @@ export class AgUiChat extends HTMLElement {
     this.#thoughts = null;
     this.#hidePending();
     this.#toolCards.clear();
+    // The panels go with the cards they hung off. Nothing restores them: the
+    // progress rode the imperative carrier and was never persisted, which is
+    // the correct half of that split -- a delegation that was live before this
+    // transcript was wiped is not live now.
+    this.#subagentPanels.clear();
     this.#serverSettled.clear();
     this.#cardElements.clear();
     this.#activityBlocks.clear();
@@ -3414,6 +3499,7 @@ export class AgUiChat extends HTMLElement {
         onPersist: (messages) => this.conversationStore.saveMessages(this.#threadId, messages),
         onStateChanged: (state) => this.#onSharedStateChanged(state),
         connectionLostMessage: this.#strings.connectionLost,
+        maxToolRounds: this.#maxToolRounds(),
       });
     }
     return this.#client;
@@ -3437,32 +3523,45 @@ export class AgUiChat extends HTMLElement {
    * Every finished bubble gets copy and feedback -- both are safe on a message
    * of any age. Retry moves to the newest, because it is the only one where
    * re-running answers the same question rather than rewriting history.
+   *
+   * `data-message-actions` subtracts from that. The row is built only when
+   * something survives to go in it: an empty row still takes its margin, still
+   * answers to the `message-actions` part, and still reads to a screen reader
+   * as a group of actions with none in it.
    */
   #attachActions(bubble: HTMLDivElement, options: { rateable?: boolean } = {}): void {
-    attachMessageActions(bubble, {
-      strings: this.#strings,
-      // Read at click time, not captured: a bubble rendered from markdown holds
-      // its text in the DOM, and that is what the user sees and means to copy.
-      text: () => bubble.textContent as string,
-      // A failed run is copyable -- error text is what people paste into a bug
-      // report -- but not rateable: a rating is a statement about an *answer*,
-      // and mixing "the connection dropped" into that signal makes the host's
-      // feedback data say less than it did before.
-      ...(options.rateable === false
-        ? {}
-        : {
-            onFeedback: (rating: "up" | "down") => {
-              this.dispatchEvent(
-                new CustomEvent<FeedbackDetail>(FEEDBACK_EVENT, {
-                  detail: { content: bubble.textContent as string, rating },
-                  bubbles: true,
-                  composed: true,
-                }),
-              );
-            },
-          }),
-    });
-    this.#moveRetryTo(messageActionBar(bubble, this.#strings));
+    const enabled = this.#messageActions();
+    const copyable = enabled.has(MESSAGE_ACTIONS.COPY);
+    // A failed run is copyable -- error text is what people paste into a bug
+    // report -- but not rateable: a rating is a statement about an *answer*,
+    // and mixing "the connection dropped" into that signal makes the host's
+    // feedback data say less than it did before.
+    const rateable = options.rateable !== false && enabled.has(MESSAGE_ACTIONS.FEEDBACK);
+    if (copyable || rateable) {
+      attachMessageActions(bubble, {
+        strings: this.#strings,
+        // Read at click time, not captured: a bubble rendered from markdown
+        // holds its text in the DOM, and that is what the user sees and means
+        // to copy.
+        ...(copyable ? { text: () => bubble.textContent as string } : {}),
+        ...(rateable
+          ? {
+              onFeedback: (rating: "up" | "down") => {
+                this.dispatchEvent(
+                  new CustomEvent<FeedbackDetail>(FEEDBACK_EVENT, {
+                    detail: { content: bubble.textContent as string, rating },
+                    bubbles: true,
+                    composed: true,
+                  }),
+                );
+              },
+            }
+          : {}),
+      });
+    }
+    if (enabled.has(MESSAGE_ACTIONS.RETRY)) {
+      this.#moveRetryTo(messageActionBar(bubble, this.#strings));
+    }
   }
 
   /** Move the Retry button onto `bar`, taking it off whoever held it. */
@@ -3822,6 +3921,10 @@ export class AgUiChat extends HTMLElement {
           this.#dispatchInvalidation(value);
           return;
         }
+        if (name === SUBAGENT_CUSTOM_NAME) {
+          this.#reportSubAgent(value);
+          return;
+        }
         // Straight out to the host page, uninterpreted. This is the imperative
         // carrier: whatever it means, it means it to the page, not to the
         // transcript -- so it is dispatched and deliberately not rendered,
@@ -4008,6 +4111,52 @@ export class AgUiChat extends HTMLElement {
     );
   }
 
+  /**
+   * Draw one step of a delegated sub-agent's progress, on the card that
+   * delegated.
+   *
+   * `delegationId` is the parent's own `delegate_task` tool-call id, so the
+   * attachment point is a card this element already drew on `TOOL_CALL_START`.
+   * That is the whole design: a run that hands work to a sub-agent used to read
+   * as a stall -- the card sat at "running…" for the child's entire duration --
+   * and the fix is to narrate *into* the thing that was already standing there,
+   * rather than to float a second element with the same identity.
+   *
+   * A progress event for a call this client never drew is dropped. It has no
+   * card to attach to, and inventing a floating one is precisely the alternative
+   * that was rejected: parent and child interleave in the transcript with
+   * nothing marking whose is whose, and the persisted transcript -- which never
+   * held the progress at all -- would not match what was on screen.
+   *
+   * Nothing here writes to the conversation store. `CUSTOM` never enters
+   * `agent.messages`, so a reload mid-run leaves the tool card and loses the
+   * nested detail, which is the intended behaviour rather than a gap.
+   */
+  #reportSubAgent(value: unknown): void {
+    const update = subAgentUpdate(value);
+    if (update === null) {
+      return;
+    }
+    const card = this.#toolCards.get(update.delegationId);
+    if (card === undefined) {
+      return;
+    }
+    let panel = this.#subagentPanels.get(update.delegationId);
+    if (panel === undefined) {
+      // Created on whichever phase arrives first rather than only on `started`.
+      // The contract says exactly one opens a delegation, and a client that
+      // insisted on it would answer a server that dropped one frame by showing
+      // nothing at all for the rest of the run.
+      panel = new SubAgentPanel(this.#strings);
+      this.#subagentPanels.set(update.delegationId, panel);
+      card.subagentSlot.appendChild(panel.element);
+    }
+    panel.report(update);
+    // The card grew, and the transcript is usually pinned to the foot while a
+    // run is in flight.
+    this.#scroller.follow();
+  }
+
   /** A muted "⏹ Stopped" line in the transcript (distinct from the ⚠️ error bubble). */
   #appendStoppedNote(): void {
     const note = document.createElement("div");
@@ -4404,7 +4553,12 @@ export class AgUiChat extends HTMLElement {
         : (this.toolSummaries[call.name] ??
           this.#toolCatalog[call.name]?.summary ??
           prettifyToolName(call.name));
-    const card = new ToolCallCard(call.name, call.args, summary, this.#strings);
+    const card = new ToolCallCard(call.name, call.args, summary, this.#strings, {
+      // A thunk over the live property, not the property itself: the card keeps
+      // this for the life of the call, and the result region is filled when the
+      // tool settles -- which can be long after a host set the hook.
+      formatPayload: (payload) => this.formatToolPayload?.(payload) ?? null,
+    });
     this.#toolCards.set(call.id, card);
     this.#ensureGroup().appendChild(card.element);
     this.#updateEmptyState();

package/src/core/agui_client.ts

@@ -182,6 +182,22 @@ export interface AgUiClientConfig extends AgUiRunInputs {
    * passes its localized string.
    */
   connectionLostMessage?: string;
+  /**
+   * Upper bound on frontend tool-call to re-run rounds within one
+   * {@link AgUiClient.send}. Defaults to {@link MAX_TOOL_ROUNDS}.
+   *
+   * The default suits a chat whose tools answer questions. A page-driving
+   * deployment reaches it legitimately -- filling a form field by field is one
+   * round each -- and the symptom is not an error but an answer that stops
+   * mid-task, which reads as the model giving up. Raise it where a turn is
+   * expected to take many small steps.
+   *
+   * Read once, when the client is built. The bound is a property of the
+   * deployment rather than of a run, so re-reading it per round would only make
+   * a mid-run change possible, and a mid-run change to how long the run may
+   * last is not a thing a host has any way to reason about.
+   */
+  maxToolRounds?: number;
 }
 
 /**
@@ -219,6 +235,7 @@ export class AgUiClient {
    */
   readonly #closedMessageIds = new Set<string>();
   readonly #connectionLostMessage: string;
+  readonly #maxToolRounds: number;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
   // a cancel between frontend-tool rounds doesn't start another round.
   #cancelled = false;
@@ -232,6 +249,12 @@ export class AgUiClient {
     this.#resolveInterrupts = config.resolveInterrupts ?? null;
     this.#onPersist = config.onPersist ?? (() => {});
     this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
+    // Validated here rather than at each caller, so the element's attribute and
+    // a direct consumer get the same answer. A bound below one -- or a NaN from
+    // an unparseable attribute -- is not a smaller budget but a send that runs
+    // the agent zero times, which would look exactly like a broken endpoint.
+    const rounds = config.maxToolRounds ?? MAX_TOOL_ROUNDS;
+    this.#maxToolRounds = rounds >= 1 ? Math.floor(rounds) : MAX_TOOL_ROUNDS;
     const onStateChanged = config.onStateChanged;
     if (onStateChanged !== undefined) {
       // The agent applies STATE_SNAPSHOT / STATE_DELTA itself; subscribing is
@@ -270,7 +293,8 @@ export class AgUiClient {
    *
    * When the agent calls frontend tools, this executes them and re-runs the
    * agent with the results, looping until the agent stops calling frontend
-   * tools (bounded by {@link MAX_TOOL_ROUNDS}).
+   * tools (bounded by {@link AgUiClientConfig.maxToolRounds}, which defaults to
+   * {@link MAX_TOOL_ROUNDS}).
    *
    * `attachments` ride on the user message as a non-standard field so the
    * default store round-trips them for history replay; see
@@ -389,7 +413,7 @@ export class AgUiClient {
     // continues an unfinished frontend-tool round after a page load; this stays
     // inside one #run().
     let resume: ResumeEntry[] | undefined;
-    for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
+    for (let round = 0; round < this.#maxToolRounds; round += 1) {
       // A cancel during the previous round's tool execution lands here: the
       // running handler completed, but no further round starts.
       if (this.#cancelled) {

package/src/index.ts

@@ -11,6 +11,7 @@ export {
   INVALIDATE_EVENT,
   LOAD_CAPABILITY_TOOL,
   MAX_TOOL_ROUNDS,
+  MESSAGE_ACTIONS,
   MESSAGE_ROLE,
   RUN_FINISHED_EVENT,
   STATE_EVENT,
@@ -193,8 +194,11 @@ export {
 export {
   type SettledStatus,
   ToolCallCard,
+  type ToolCallCardOptions,
   type ToolCallStatus,
   type ToolDisplayMode,
+  type ToolPayload,
+  type ToolPayloadFormatter,
 } from "./ui/tool_call_card.js";
 export { DEFAULT_UI_STRINGS, mergeUiStrings, type UiStrings } from "./ui/ui_strings.js";
 export { VERSION } from "./version.js";