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

package/src/core/ag_ui_chat.ts

@@ -1,20 +1,29 @@
 import { randomUUID } from "@ag-ui/client";
 import type { Context, Interrupt, Message, Tool } from "@ag-ui/core";
 import {
+  ANNOUNCE_CLEAR_MS,
   ATTACHMENT_EVENT,
   CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
+  CUSTOM_AGENT_EVENT,
   DEFAULT_ATTACHMENT_MAX_BYTES,
+  FEEDBACK_EVENT,
   ICON_ATTACH,
   ICON_LAUNCHER,
   ICON_SEND,
   ICON_STOP,
+  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,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
@@ -47,12 +56,20 @@ import { chartSpecFrom } from "../ui/chart_spec_from.js";
 import { CHART_TOOL_NAME, createChartTool } from "../ui/chart_tool.js";
 import { CheckpointMenu, type CheckpointVerb } from "../ui/checkpoint_menu.js";
 import { type ConfirmationRequest, requestConfirmation } from "../ui/confirmation_card.js";
+import {
+  attachMessageActions,
+  messageActionBar,
+  messageActionButton,
+} from "../ui/message_actions.js";
+import { attachQuoteOffer, type PageQuoteOffer } from "../ui/page_quote_offer.js";
 import { prettifyToolName } from "../ui/prettify_tool_name.js";
 import {
   type QuestionRenderer,
   type QuestionRequest,
   requestQuestion,
 } from "../ui/question_card.js";
+import { asQuote, quotableSelection } from "../ui/quote_selection.js";
+import type { RelativeTimeFormatter } from "../ui/relative_time.js";
 import { renderMarkdown } from "../ui/render_markdown.js";
 import {
   createResizeHandle,
@@ -63,10 +80,18 @@ import {
 import { wrapWords } from "../ui/reveal_words.js";
 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 {
@@ -109,6 +134,13 @@ export interface AttachmentsDetail {
 }
 
 /** `detail` shape of the {@link STATE_EVENT} CustomEvent. */
+/** {@link FEEDBACK_EVENT} detail: what was rated, and how. */
+export interface FeedbackDetail {
+  /** The rated message's text, as rendered. */
+  readonly content: string;
+  readonly rating: "up" | "down";
+}
+
 export interface StateDetail {
   readonly state: Readonly<Record<string, unknown>>;
 }
@@ -128,6 +160,83 @@ export interface ToolRun {
 export interface RunFinishedDetail {
   /** In settle order. Empty when the interaction called no tools. */
   readonly tools: readonly ToolRun[];
+  /**
+   * Every key announced during the interaction, de-duplicated, first-seen order.
+   *
+   * **This is the field that makes adoption one line** for a host already
+   * listening here, and the `else` is the whole compatibility story:
+   *
+   * ```js
+   * if (detail.invalidated.length > 0) refetchOnly(detail.invalidated);
+   * else if (detail.tools.some((t) => t.side === "server")) refetchEverything();
+   * ```
+   *
+   * Empty against a server that announces nothing, so an old server and a new
+   * client fall through to the coarse refetch that shipped before either.
+   */
+  readonly invalidated: readonly string[];
+}
+
+/**
+ * Draw one activity, from its content alone.
+ *
+ * The contract is {@link ClientTool.render}'s, and for the same reason rather
+ * than by analogy. An activity is materialised into a `role: "activity"`
+ * message, persisted with the transcript, and re-fired on every restore -- so a
+ * renderer that writes to the page instead of returning DOM fires again on
+ * every thread load, which is exactly the bug the tool registry's purity rule
+ * was written to make unmakeable.
+ *
+ * - a pure function of `content` -- no host state, no network, no clock;
+ * - deterministic, so a reload reproduces what was there before;
+ * - free of effects outside the node it returns, which the component places.
+ *
+ * Return `null` for content that says nothing worth drawing. Anything already
+ * drawn under that message id is then removed: live and reload should agree,
+ * and the stored content is the version that could not be drawn.
+ */
+export type ActivityRenderer = (content: unknown) => Node | null;
+
+/** One `activity_type` a host can draw. See {@link AgUiChat.registerActivityRenderer}. */
+export interface ActivityRegistration {
+  /**
+   * The AG-UI `activity_type` this draws, matched exactly.
+   *
+   * An open string the protocol does not enumerate -- which is the whole reason
+   * this is a registry rather than a branch.
+   */
+  readonly type: string;
+  readonly render: ActivityRenderer;
+  /**
+   * Shown in the transcript when something already drawn under this type stops
+   * being renderable. Omit for an activity whose disappearance needs no
+   * explanation.
+   */
+  readonly removedNotice?: string;
+}
+
+/** `detail` shape of the {@link CUSTOM_AGENT_EVENT} CustomEvent. */
+export interface CustomAgentDetail {
+  /** The `CUSTOM` event's `name`, verbatim. An open string; never interpreted here. */
+  readonly name: string;
+  /** Its `value`, verbatim and unparsed. `unknown` because the protocol says nothing about it. */
+  readonly value: unknown;
+}
+
+/** `detail` shape of the {@link INVALIDATE_EVENT} CustomEvent. */
+export interface InvalidateDetail {
+  /**
+   * The resources that moved, as the server named them.
+   *
+   * **Opaque strings, and matching is exact.** `orders/42` does not imply
+   * `orders` -- a prefix rule would be this component guessing at a scheme it
+   * does not own, and `orders/1` would match `orders/11`. A server that wants
+   * the collection refreshed names it. Your own matching may be hierarchical,
+   * because in your vocabulary the scheme is known.
+   */
+  readonly keys: readonly string[];
+  /** What caused the write -- usually the tool's name. `null` when unstated. */
+  readonly reason: string | null;
 }
 
 /** `detail` shape of the {@link TOGGLE_EVENT} CustomEvent. */
@@ -190,6 +299,9 @@ const SIZE_KEY = "ag-ui-chat:size";
 /** Per-tab persistence key for the built-in theme toggle. */
 const THEME_KEY = "ag-ui-chat:theme";
 
+/** Pixels between a selection and the offer to quote it. */
+const QUOTE_GAP = 6;
+
 /**
  * Storage namespaces already spoken for in this document.
  *
@@ -263,6 +375,23 @@ export class AgUiChat extends HTMLElement {
    */
   allowImages = false;
 
+  /**
+   * Replace the relative timestamps in the thread drawer and the checkpoint
+   * panel -- `"5m ago"`, `"2d ago"` -- with the host's own formatting.
+   *
+   * The built-in is locale-neutral on purpose: there is no `Intl` anywhere in
+   * this component, so it never disagrees with the page it is embedded in by
+   * guessing a locale. That is a good default and a bad requirement, which is
+   * what this is for.
+   *
+   * ```js
+   * const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
+   * chat.formatRelativeTime = (ts) =>
+   *   rtf.format(Math.round((ts - Date.now()) / 60000), "minute");
+   * ```
+   */
+  formatRelativeTime: RelativeTimeFormatter | null = null;
+
   /** When true, destructive tools execute without a confirmation modal. */
   autoConfirm = false;
 
@@ -290,6 +419,23 @@ export class AgUiChat extends HTMLElement {
    */
   approvalRenderer: ApprovalRenderer | null = null;
 
+  /**
+   * Let the user edit a gated call's arguments before approving it.
+   *
+   * Off by default and **an assertion about your server**, not a negotiation:
+   * AG-UI carries `editedArgs` in the resume payload and gates it on the
+   * agent's own `approveWithEdits` capability, which this component never sees
+   * -- capabilities are not on the wire it reads. So the host says whether its
+   * agent honours them. Turned on against a server that does not, the user
+   * would edit arguments it silently discards, which is worse than not
+   * offering.
+   *
+   * Only affects calls whose arguments are known here: an interrupt names a
+   * `toolCallId`, and the tool card for that call is where the arguments still
+   * are. An interrupt naming no card gets the plain approve/deny.
+   */
+  approveWithEdits = false;
+
   /**
    * Optional per-call confirmation predicate. When set it is authoritative,
    * deciding from the tool name and args whether this particular call needs
@@ -395,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
@@ -449,13 +620,32 @@ 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
    * the real output with the generic "executed on the server" fallback.
    */
   /** Whether a server-pushed chart activity is drawn. Off unless asked for. */
-  #chartActivity = false;
+  /**
+   * Which `activity_type`s this element can draw, by name.
+   *
+   * A registry rather than a branch because `activity_type` is an open string
+   * the protocol does not enumerate. The two built-ins go through it like any
+   * host registration, which is the test that the seam is real.
+   */
+  readonly #activityRenderers = new Map<string, ActivityRegistration>();
+  /** Types that arrived with nobody registered to draw them. See {@link unhandledActivityTypes}. */
+  readonly #unhandledActivityTypes = new Set<string>();
 
   /** Card elements by call id, so a rendering handler can find its own card. */
   readonly #cardElements = new Map<string, HTMLElement>();
@@ -470,7 +660,77 @@ export class AgUiChat extends HTMLElement {
    * Spans tool rounds and an approval interrupt; cleared when the event fires.
    */
   #runTools: { readonly id: string; readonly name: string }[] = [];
+  /**
+   * Keys announced during this interaction, de-duplicated in first-seen order.
+   *
+   * Per element, never module-level: a second mounted chat is a second run, and
+   * sharing this would tell one page to refetch on the other's writes. Reset by
+   * {@link AgUiChat.#dispatchRunFinished}, which is the one place that has read
+   * it.
+   */
+  /**
+   * Tool names the user waived confirmation for, for the life of this element.
+   *
+   * Per instance and never persisted: a session decision that outlived the tab
+   * would be a permanent grant made by one click, which is the thing
+   * `autoConfirm` already exists to say deliberately. Cleared with the element.
+   */
+  readonly #sessionApproved = new Set<string>();
+
+  /**
+   * The one action row currently carrying Retry, if any.
+   *
+   * Retry belongs to the **last** turn only: re-running an older one is
+   * branching, and for a page-driving agent editing a past turn is not neutral
+   * -- those turns clicked buttons, and re-running turn 3 does not un-save what
+   * turn 5 saved. Holding a single owner is what keeps exactly one offer on
+   * screen without per-bubble bookkeeping.
+   */
+  #retryOwner: HTMLElement | null = null;
+
+  #runInvalidated = new Set<string>();
   readonly #root: ShadowRoot;
+  /** Screen-reader-only status region -- see {@link AgUiChat.#announce}. */
+  readonly #announcer = document.createElement("div");
+  /** Return-to-foot affordance, shown only once something has been missed. */
+  readonly #jumpButton = document.createElement("button");
+  /**
+   * Offer to quote the current selection, floated beside it.
+   *
+   * Shares {@link AgUiChat.#messagesWrap} with the jump button for the same
+   * reason: it is positioned against the transcript, and must not scroll away
+   * with the words it is pointing at.
+   */
+  readonly #quoteButton = document.createElement("button");
+  /** What {@link AgUiChat.#quoteButton} would quote, while it is showing. */
+  #quoting = "";
+  /** The host-page offer, while one is attached; see {@link AgUiChat.offerQuoteInPage}. */
+  #pageQuote: PageQuoteOffer | null = null;
+  /**
+   * Positioning context for {@link AgUiChat.#jumpButton}.
+   *
+   * The button cannot live in the scrolling list -- it would scroll away with
+   * the content it is offering to scroll to -- and it cannot be positioned
+   * against the panel either: the panel's foot is below the composer, the skill
+   * chips and the footer, so `bottom` measured from there lands the button on
+   * top of the composer rather than over the transcript. This wrapper is the
+   * only box whose foot *is* the transcript's foot.
+   */
+  readonly #messagesWrap = document.createElement("div");
+  /** Follows the foot of the transcript, and stops when the reader scrolls away. */
+  #scroller!: StickToBottom;
+  /** Pending clear of {@link AgUiChat.#announcer}; see why it is cleared at all. */
+  #announceTimer: ReturnType<typeof setTimeout> | null = null;
+  /**
+   * Whether this turn already announced how it ended.
+   *
+   * `onSettled` is the terminal guarantee and fires however the run ended, so
+   * it is the only place that can promise the user hears *something*. But a
+   * stopped or failed run has already said the truer thing from `onCancelled`
+   * or `onError`, and "assistant answered" after "response stopped" is worse
+   * than silence.
+   */
+  #announcedOutcome = false;
   readonly #chat: HTMLDivElement;
   readonly #messages: HTMLDivElement;
   readonly #input: HTMLTextAreaElement;
@@ -590,6 +850,33 @@ export class AgUiChat extends HTMLElement {
     this.#launcher = document.createElement("button");
     this.#badge = document.createElement("span");
     this.#emptyWrap = document.createElement("div");
+    // The compaction notice is a registration, not a branch -- and going through
+    // the seam earns it two things it did not have: a reload puts it back (it is
+    // content, and content replays), and a server redrawing under the same id
+    // replaces it rather than adding a second notice for one event.
+    this.registerActivityRenderer({
+      type: COMPACTION_ACTIVITY_TYPE,
+      render: (content) => {
+        const removed = compactionRemoved(content);
+        return removed === null
+          ? null
+          : renderRunNotice(
+              "\u{1F5DC}",
+              this.#strings.historyCompacted.replace("{count}", String(removed)),
+              "compaction",
+            );
+      },
+    });
+    // Follow-up chips, registered through the same seam for the same reasons:
+    // a reload puts them back, and a server pushing a new set under a new id
+    // supersedes the old one rather than leaving two offers on screen.
+    this.registerActivityRenderer({
+      type: SUGGESTIONS_ACTIVITY_TYPE,
+      render: (content) =>
+        renderSuggestionChips(content, this.#strings, (prompt) => {
+          void this.sendMessage(prompt);
+        }),
+    });
     this.#skillsMenu = new SkillsMenu((skill) => this.#applySkill(skill));
     this.#drawer = new ThreadDrawer({
       onSelect: (threadId) => {
@@ -677,6 +964,9 @@ export class AgUiChat extends HTMLElement {
   /** Load the checkpoint panel with the runs that can actually be continued. */
   async #refreshCheckpoints(): Promise<void> {
     const index = this.#runs();
+    // Pushed at render rather than at connect: `formatRelativeTime` is a
+    // property, so a host may set it long after the element mounted.
+    this.#checkpoints.setRelativeTimeFormatter(this.formatRelativeTime);
     this.#checkpoints.setRuns(index === null ? [] : await index.continuable());
   }
 
@@ -930,7 +1220,7 @@ export class AgUiChat extends HTMLElement {
           });
     this.#confirmAbort = null;
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
     return answer;
   }
 
@@ -1242,8 +1532,17 @@ export class AgUiChat extends HTMLElement {
       this.#claimedNs = null;
     }
     this.#cancelRun();
+    // The page offer listens on the host's document, not on anything of ours,
+    // so nothing else would ever take it down.
+    this.#pageQuote?.detach();
+    this.#pageQuote = null;
     this.#attachTray?.dispose();
     this.#voice?.dispose();
+    this.#scroller.dispose();
+    if (this.#announceTimer !== null) {
+      clearTimeout(this.#announceTimer);
+      this.#announceTimer = null;
+    }
   }
 
   /**
@@ -1369,6 +1668,162 @@ export class AgUiChat extends HTMLElement {
     this.#input.focus();
   }
 
+  /**
+   * Put `text` into the composer as a markdown quotation, and focus it.
+   *
+   * Deliberately **not** a send. Quoting is how a question narrows to one part
+   * of an answer, so the quotation is the preamble and the question is what
+   * comes next -- the caret is left after it, on its own line.
+   *
+   * This is also the seam for the half of this feature the component cannot
+   * build: selection in the **host page**. A widget mounted beside a table can
+   * be asked about a row, and nothing in a chat's own transcript can offer
+   * that. A host reads its own selection, however it likes, and calls this.
+   *
+   * No-ops on text that is empty or only whitespace.
+   */
+  quote(text: string): void {
+    const quoted = asQuote(text);
+    if (quoted === "") {
+      return;
+    }
+    // Appended after whatever is already typed, on a fresh paragraph: a second
+    // quotation is a second thing being asked about, not a replacement for the
+    // first. Trailing blank lines are dropped so repeated quoting does not
+    // accumulate gaps.
+    const current = this.#input.value.replace(/\s+$/, "");
+    this.#input.value = current === "" ? quoted : `${current}\n\n${quoted}`;
+    this.#autoGrow();
+    this.#input.focus();
+    const end = this.#input.value.length;
+    this.#input.setSelectionRange(end, end);
+  }
+
+  /**
+   * Offer to quote what the user selects in the **host page**, not just in the
+   * transcript. Returns a function that stops offering.
+   *
+   * The same select-then-offer gesture, over a table, a diff, a report -- the
+   * surface the user actually works in, which is the half of quoting no hosted
+   * chat can reach. Opt-in, because it listens on the host's document and that
+   * is theirs to grant.
+   *
+   * Deliberately **not** a four-line recipe, which is how this shipped first
+   * and was wrong: a page listener that quotes every settled selection appends
+   * to the composer on every drag made to read, to copy or to fix a typo -- and
+   * it cannot tell a selection in the page's prose from one inside the user's
+   * own half-typed `<input>`, because Chrome reports a field's internal
+   * selection as an ordinary range over the field's *wrapper*. See
+   * {@link attachQuoteOffer} for the guards.
+   *
+   * Detached automatically when the element leaves the document; a host that
+   * re-mounts it calls this again.
+   */
+  offerQuoteInPage(within: HTMLElement = document.body): () => void {
+    this.#pageQuote?.detach();
+    const offer = attachQuoteOffer({
+      within,
+      label: this.#strings.quoteSelection,
+      exclude: this,
+      onQuote: (text) => this.quote(text),
+    });
+    this.#pageQuote = offer;
+    return () => {
+      offer.detach();
+      if (this.#pageQuote === offer) {
+        this.#pageQuote = null;
+      }
+    };
+  }
+
+  /** Whether the transcript offers to quote what the user selects. */
+  #quoteEnabled(): boolean {
+    return this.getAttribute("data-quote-selection") !== "false";
+  }
+
+  /**
+   * Offer to quote the settled selection, or retire the offer.
+   *
+   * `event` is passed for its coordinates and only those: they say which line
+   * of a selection spanning several messages the offer should hang from. A
+   * keyboard selection has none, and the first line is used instead.
+   */
+  #onSelectionSettled(event?: MouseEvent): void {
+    if (!this.#quoteEnabled()) {
+      return;
+    }
+    const near = event === undefined ? undefined : { x: event.clientX, y: event.clientY };
+    const selected = quotableSelection(this.#messages, [this.#root], near);
+    if (selected === null) {
+      this.#hideQuote();
+      return;
+    }
+    this.#quoting = selected.text;
+    this.#placeQuote(selected.rect);
+  }
+
+  /** Float the offer beside `rect`, kept inside the transcript's own box. */
+  #placeQuote(rect: DOMRect): void {
+    // Unhidden first: a hidden element measures zero, and its own size is what
+    // decides whether it fits above the selection and how far to pull it left.
+    this.#quoteButton.hidden = false;
+    const wrap = this.#messagesWrap.getBoundingClientRect();
+    const top = rect.top - wrap.top;
+    // Above the selection by default, below it when there is no room --
+    // selecting the first line of the transcript is the ordinary case, not an
+    // edge one, and an offer clipped by the header is an offer nobody takes.
+    const below = top < QUOTE_GAP + this.#quoteButton.offsetHeight;
+    this.#quoteButton.dataset["below"] = String(below);
+    this.#quoteButton.style.top = `${below ? rect.bottom - wrap.top + QUOTE_GAP : top - QUOTE_GAP}px`;
+    // Centred on the selection, then pulled back by its own half-width so a
+    // selection at either margin does not push the offer out of the panel.
+    const half = this.#quoteButton.offsetWidth / 2;
+    const centre = rect.left + rect.width / 2 - wrap.left;
+    this.#quoteButton.style.left = `${Math.min(Math.max(centre, half), wrap.width - half)}px`;
+  }
+
+  /** Retire the offer, and forget what it was pointing at. */
+  #hideQuote(): void {
+    this.#quoteButton.hidden = true;
+    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");
@@ -1986,6 +2441,18 @@ export class AgUiChat extends HTMLElement {
   /** Drop the in-memory run + transcript, leaving the thread id untouched. */
   #resetState(): void {
     this.#client = null;
+    this.#clearTranscript();
+    this.#initialMessages = [];
+  }
+
+  /**
+   * Wipe the rendered transcript and everything that indexes into it.
+   *
+   * Split from {@link #resetState} because a retry re-renders the transcript
+   * while keeping the *client*: dropping the client there would take the
+   * agent's message list with it, which is the thing being truncated.
+   */
+  #clearTranscript(): void {
     // Before the transcript goes: a render still queued would otherwise fire
     // against the wiped list and open a fresh bubble holding the discarded
     // conversation's last tokens.
@@ -1994,16 +2461,58 @@ 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();
-    this.#initialMessages = [];
+    this.#retryOwner = null;
     this.#attachTray?.clear();
     // Keep the empty-state region; everything else clears.
     this.#messages.replaceChildren(this.#emptyWrap);
     this.#updateEmptyState();
   }
 
+  /**
+   * Ask the same question again and replace the answer.
+   *
+   * History is truncated to the most recent user message inclusive and the run
+   * repeats, so the agent answers what it was asked rather than being told its
+   * last answer was wrong. Returns `false` when there is nothing to retry or a
+   * run is already in flight.
+   *
+   * Public because a host with its own message UI wants the same button, and
+   * because the failed-run notice reaches it from outside the action row.
+   *
+   * **A retried turn re-runs its tools**, which for a page-driving agent is not
+   * neutral: the previous attempt already clicked what it clicked, and this
+   * does not undo it. Confirmation still applies, so a destructive tool asks
+   * again -- unless the user waived it for this session.
+   */
+  async retryLastTurn(): Promise<boolean> {
+    if (this.#running) {
+      return false;
+    }
+    const client = this.#ensureClient();
+    const kept = client.truncateToLastUser();
+    if (kept === null) {
+      return false;
+    }
+    // Re-render between the truncation and the run: the kept turns replay as
+    // restored history (static, no entrance animation), and only the new answer
+    // arrives live. Streaming into the old transcript would put the new answer
+    // underneath the one it replaces.
+    this.#clearTranscript();
+    for (const message of kept) {
+      this.#renderHistoricMessage(message);
+    }
+    await client.resume();
+    return true;
+  }
+
   /** Switch the active conversation to an existing thread and replay it. */
   async #switchThread(threadId: string): Promise<void> {
     if (threadId === this.#threadId) {
@@ -2034,6 +2543,7 @@ export class AgUiChat extends HTMLElement {
 
   /** Reload the drawer's thread list, marking the active thread. */
   async #refreshDrawer(): Promise<void> {
+    this.#drawer.setRelativeTimeFormatter(this.formatRelativeTime);
     this.#drawer.setThreads(await this.conversationStore.listThreads(), this.#threadId);
   }
 
@@ -2139,7 +2649,9 @@ export class AgUiChat extends HTMLElement {
         // transcript mounts at once, so animating every bubble's text in
         // parallel looks wrong. Mark it so the fade CSS skips it, and don't
         // wrap words.
-        this.appendMessage(MESSAGE_ROLE.ASSISTANT, text).classList.add("message--restored");
+        const restoredBubble = this.appendMessage(MESSAGE_ROLE.ASSISTANT, text);
+        restoredBubble.classList.add("message--restored");
+        this.#attachActions(restoredBubble);
       }
       // Narrowed rather than trusted, for the same reason `messageAttachments`
       // narrows the neighbouring field: anything that throws in this loop aborts
@@ -2178,8 +2690,8 @@ export class AgUiChat extends HTMLElement {
       // chart's data is in the transcript already and survives a reload. Only
       // the drawing had to be put back.
       const activity = message as unknown as { activityType?: unknown; content?: unknown };
-      if (activity.activityType === CHART_ACTIVITY_TYPE && this.#chartActivity) {
-        this.#drawActivityChart(message.id, activity.content);
+      if (typeof activity.activityType === "string") {
+        this.#drawActivity(message.id, activity.activityType, activity.content);
       }
       return;
     }
@@ -2254,7 +2766,14 @@ export class AgUiChat extends HTMLElement {
       this.#messages.appendChild(bubble);
     }
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    // A user bubble means someone just pressed Send, which is as deliberate as
+    // pressing the jump button -- so it goes to the bottom even if they had
+    // scrolled away to re-read something before typing.
+    if (role === MESSAGE_ROLE.USER) {
+      this.#scroller.jump();
+    } else {
+      this.#scroller.follow();
+    }
     return bubble;
   }
 
@@ -2278,9 +2797,6 @@ export class AgUiChat extends HTMLElement {
   }
 
   #render(): void {
-    const style = document.createElement("style");
-    style.textContent = STYLES;
-
     this.#chat.className = "chat";
     this.#chat.setAttribute("part", "panel");
 
@@ -2355,11 +2871,68 @@ export class AgUiChat extends HTMLElement {
 
     this.#messages.className = "messages";
     this.#messages.setAttribute("part", "messages");
-    // Screen readers announce streamed messages as they arrive.
     this.#messages.setAttribute("role", "log");
-    this.#messages.setAttribute("aria-live", "polite");
+    // NOT a live region. The streaming bubble's innerHTML is replaced inside
+    // this element on every animation frame, and `role="log"` already implies
+    // polite announcement whose default `aria-relevant` includes text
+    // additions -- so a screen reader was asked to re-announce the whole answer
+    // tens of times as it streamed. `aria-live="off"` is an explicit override
+    // of the role's implicit value, which is why the role can stay: the log
+    // semantics are what let the transcript be navigated as one, and only the
+    // announcing is the defect. Status goes to #announcer instead.
+    this.#messages.setAttribute("aria-live", "off");
     this.#messages.setAttribute("aria-label", this.#strings.conversation);
 
+    this.#jumpButton.className = "jump-latest";
+    this.#jumpButton.type = "button";
+    this.#jumpButton.setAttribute("part", "jump-latest");
+    this.#jumpButton.textContent = this.#strings.jumpToLatest;
+    this.#jumpButton.addEventListener("click", () => {
+      this.#scroller.jump();
+    });
+
+    this.#quoteButton.className = "quote-selection";
+    this.#quoteButton.type = "button";
+    this.#quoteButton.setAttribute("part", "quote-selection");
+    this.#quoteButton.textContent = this.#strings.quoteSelection;
+    this.#quoteButton.hidden = true;
+    // `mousedown` rather than `click`: pressing anywhere else collapses the
+    // selection first, and by the time a click lands there is nothing left to
+    // quote. Preventing the default keeps the selection alive long enough to
+    // read it.
+    this.#quoteButton.addEventListener("mousedown", (event) => {
+      event.preventDefault();
+    });
+    this.#quoteButton.addEventListener("click", () => {
+      this.quote(this.#quoting);
+      window.getSelection()?.removeAllRanges();
+      this.#hideQuote();
+    });
+
+    // A settled selection, by either input. `mouseup` rather than
+    // `selectionchange` so the offer does not chase the pointer mid-drag; the
+    // second half of the same gesture, `mousedown`, retires the previous offer
+    // before the new selection exists.
+    this.#messages.addEventListener("mouseup", (event) => this.#onSelectionSettled(event));
+    this.#messages.addEventListener("keyup", () => this.#onSelectionSettled());
+    this.#messages.addEventListener("mousedown", () => this.#hideQuote());
+
+    // Built here rather than at field initialisation: the viewport has to exist
+    // and the observer has to have something to observe.
+    this.#scroller = createStickToBottom({
+      viewport: this.#messages,
+      onMissedContent: (missed) => {
+        this.#jumpButton.dataset["missed"] = String(missed);
+      },
+    });
+
+    this.#announcer.className = "sr-only";
+    this.#announcer.setAttribute("role", "status");
+    this.#announcer.setAttribute("aria-live", "polite");
+    // Atomic: each announcement replaces the last and is read whole. Without
+    // it a reader may announce only the changed words between two statuses.
+    this.#announcer.setAttribute("aria-atomic", "true");
+
     // Empty-state region: a host slot at the top of the list, hidden as soon as
     // anything renders.
     this.#emptyWrap.className = "empty";
@@ -2450,9 +3023,14 @@ export class AgUiChat extends HTMLElement {
     inputRow.append(composer, this.#fileInput);
     // Skill surfaces sit just above the input: palette (opens on `/`), chips,
     // the missing-placeholder hint, and the pending-attachments tray.
+    this.#messagesWrap.className = "messages-wrap";
+    // Sibling of the list inside a shared box, not a child of it: the
+    // affordance offering to scroll must not scroll away with the content.
+    this.#messagesWrap.append(this.#messages, this.#jumpButton, this.#quoteButton);
+
     this.#chat.append(
       header,
-      this.#messages,
+      this.#messagesWrap,
       this.#skillsMenu.palette,
       this.#skillsMenu.chips,
       this.#skillHint,
@@ -2517,7 +3095,68 @@ export class AgUiChat extends HTMLElement {
         label: this.#strings.resizePanel,
       }),
     );
-    this.#root.append(style, this.#chat, this.#launcher);
+    this.#adoptStyles();
+    this.#root.append(this.#announcer, this.#chat, this.#launcher);
+  }
+
+  /**
+   * Attach the stylesheet without an inline `<style>` element.
+   *
+   * A host with a strict `style-src` and no `'unsafe-inline'` drops an injected
+   * `<style>` silently: the component mounts, functions, and renders completely
+   * unstyled, with nothing in the console to point at. `adoptedStyleSheets`
+   * carries no inline-style origin, so it is unaffected by that policy.
+   *
+   * The sheet is constructed **per instance** rather than shared at module
+   * scope. A shared sheet would additionally avoid re-parsing the stylesheet
+   * once per mounted element, which is what `adoptedStyleSheets` is usually
+   * reached for -- but a module-level singleton is exactly what this package
+   * forbids, and the CSP defect is fixed either way. Per instance is no worse
+   * than the `<style>` element it replaces, which also parsed once per mount.
+   *
+   * No fallback: constructible `CSSStyleSheet` is Chrome 73, Firefox 101 and
+   * Safari 16.4, all below this package's declared Safari 17 runtime target. A
+   * guard here would be code no supported browser can reach, and the only way
+   * to keep it would be to exempt it from the coverage gate.
+   */
+  /**
+   * Say one short thing to a screen reader, without touching the transcript.
+   *
+   * The transcript cannot do this job. It is rewritten on every animation
+   * frame while an answer streams, so as a live region it re-announced the
+   * whole answer tens of times per turn -- not merely unhelpful but actively
+   * hostile. The published fix for this exact bug (Microsoft's Bot Framework
+   * WebChat #3236) is architectural rather than a matter of tuning attributes:
+   * demote the visible transcript out of live-region duty and put one
+   * synthesised status per event into a separate invisible region. MDN and
+   * Scott O'Hara prescribe the same empty-region-then-inject shape.
+   *
+   * Roughly four calls land per turn -- responding, answered, a card is waiting,
+   * stopped or failed -- so the user is told what happened and reads the answer
+   * itself by navigating the log, at their own pace, rather than having it
+   * shouted at them a token at a time.
+   *
+   * **The clear is load-bearing, twice.** A reader announces a live region when
+   * its content *changes*, so setting the same string twice running -- two turns
+   * in a row both starting -- is not a change and is silently not announced.
+   * Emptying first makes the next set a change again. It also stops a stale
+   * status being read out when a reader later lands on the region.
+   */
+  #announce(message: string): void {
+    if (this.#announceTimer !== null) {
+      clearTimeout(this.#announceTimer);
+    }
+    this.#announcer.textContent = message;
+    this.#announceTimer = setTimeout(() => {
+      this.#announceTimer = null;
+      this.#announcer.textContent = "";
+    }, ANNOUNCE_CLEAR_MS);
+  }
+
+  #adoptStyles(): void {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(STYLES);
+    this.#root.adoptedStyleSheets = [sheet];
   }
 
   /**
@@ -2860,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;
@@ -2877,15 +3517,88 @@ export class AgUiChat extends HTMLElement {
     );
   }
 
-  /** Whether ``call`` should be gated behind the confirmation card. */
-  async #needsConfirmation(call: AgUiToolCall, tool: ClientTool): Promise<boolean> {
+  /**
+   * Give a finished assistant bubble its action row, and hand it Retry.
+   *
+   * 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 {
+    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. */
+  #moveRetryTo(bar: HTMLElement): void {
+    this.#retryOwner?.querySelector(".message-action--retry")?.remove();
+    const retry = messageActionButton("retry", this.#strings.retryMessage, "\u21BB");
+    retry.addEventListener("click", () => {
+      void this.retryLastTurn();
+    });
+    // First in the row: it is the action a reader reaches for when the answer
+    // was wrong, which is when they are least inclined to hunt for a control.
+    bar.prepend(retry);
+    this.#retryOwner = bar;
+  }
+
+  /**
+   * Which rule gates `call`, or `null` when it runs straight through.
+   *
+   * The rule, rather than a bare boolean, because it decides whether the user
+   * may *waive* the prompt for the rest of the session. Only the default
+   * `x-destructive` gate is waivable: `confirmPredicate` is documented as
+   * authoritative, so letting one click retire it would silently defeat a host
+   * policy — and the session allowlist is consulted on the same path it can
+   * be added from, so the button is never offered where honouring it would be
+   * refused.
+   */
+  async #confirmationRule(call: AgUiToolCall, tool: ClientTool): Promise<ConfirmationRule | null> {
     if (this.autoConfirm) {
-      return false;
+      return null;
     }
     if (this.confirmPredicate !== null) {
-      return (await this.confirmPredicate(call.name, call.args)) === true;
+      return (await this.confirmPredicate(call.name, call.args)) === true ? "predicate" : null;
+    }
+    if (this.#sessionApproved.has(call.name)) {
+      return null;
     }
-    return isDestructive(tool.parameters);
+    return isDestructive(tool.parameters) ? "destructive" : null;
   }
 
   async #executeTool(call: AgUiToolCall): Promise<ToolExecution | null> {
@@ -2944,7 +3657,8 @@ export class AgUiChat extends HTMLElement {
       this.#showPending();
       return { content: `Error: ${message}`, error: message };
     }
-    if (await this.#needsConfirmation(call, tool)) {
+    const rule = await this.#confirmationRule(call, tool);
+    if (rule !== null) {
       const request: ConfirmationRequest = { toolName: call.name, args: call.args };
       const confirmText = tool.parameters[X_CONFIRM_KEY];
       if (typeof confirmText === "string") {
@@ -2960,9 +3674,13 @@ export class AgUiChat extends HTMLElement {
       const decision = requestConfirmation(this.#ensureGroup(), request, {
         signal: this.#confirmAbort.signal,
         strings: this.#strings,
+        // Offered only where it can be honoured -- see `#confirmationRule`.
+        ...(rule === "destructive"
+          ? { onAlwaysAllow: () => this.#sessionApproved.add(call.name) }
+          : {}),
       });
       this.#updateEmptyState();
-      this.#messages.scrollTop = this.#messages.scrollHeight;
+      this.#scroller.follow();
       const accepted = await decision;
       this.#confirmAbort = null;
       card.recordDecision(accepted ? "approved" : "declined");
@@ -3044,6 +3762,13 @@ export class AgUiChat extends HTMLElement {
   ): Promise<Record<string, InterruptResponse>> {
     // One controller covers the whole batch: a single Stop denies all of them.
     this.#confirmAbort = new AbortController();
+    // The run has stopped and is waiting on a person. Nothing else on screen
+    // says so to a screen reader: the cards appear inside the transcript, which
+    // is deliberately not a live region, so without this the run simply goes
+    // quiet and the user has no reason to go looking.
+    this.#announce(
+      this.#strings.announceAwaitingDecision.replace("{count}", String(interrupts.length)),
+    );
     this.#hidePending();
     const signal = this.#confirmAbort.signal;
     const answered = await Promise.all(
@@ -3061,6 +3786,14 @@ export class AgUiChat extends HTMLElement {
         if (toolName !== null && toolName !== undefined) {
           request.toolName = toolName;
         }
+        // Offered only where it can be honoured: the host has said its agent
+        // accepts `editedArgs`, and this interrupt named a call whose arguments
+        // we still hold.
+        let editedArgs: Record<string, unknown> | undefined;
+        const editable = this.approveWithEdits && card !== undefined;
+        if (editable) {
+          request.args = card.args;
+        }
         card?.mark(TOOL_CALL_STATUS.DEFERRED);
         // A host-supplied renderer takes full control of the approval UI. The
         // built-in card renders into the gated call's own card, falling back to
@@ -3071,6 +3804,13 @@ export class AgUiChat extends HTMLElement {
             : await requestApproval(card?.approvalSlot ?? this.#ensureGroup(), request, {
                 signal,
                 strings: this.#strings,
+                ...(editable
+                  ? {
+                      onEdit: (args: Record<string, unknown>) => {
+                        editedArgs = args;
+                      },
+                    }
+                  : {}),
               });
         // Same annotation as the client-side confirmation gate. Without it the
         // two gates read differently for the same act: a locally-confirmed call
@@ -3085,16 +3825,21 @@ export class AgUiChat extends HTMLElement {
           // now rather than leaving it hanging until the onSettled sweep.
           card?.settle(TOOL_CALL_STATUS.DECLINED, this.#strings.declinedAction);
         }
-        return { id: interrupt.id, approved };
+        return { id: interrupt.id, approved, editedArgs };
       }),
     );
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
     this.#confirmAbort = null;
     const responses: Record<string, InterruptResponse> = {};
-    for (const { id, approved } of answered) {
+    for (const { id, approved, editedArgs } of answered) {
+      // `editedArgs` rides only when the user actually changed something, so a
+      // server can tell "approved as proposed" from "approved, but like this".
       responses[id] = approved
-        ? { status: "resolved", payload: { approved: true } }
+        ? {
+            status: "resolved",
+            payload: editedArgs === undefined ? { approved: true } : { approved: true, editedArgs },
+          }
         : { status: "cancelled" };
     }
     return responses;
@@ -3103,6 +3848,12 @@ export class AgUiChat extends HTMLElement {
   #handlers(): AgUiClientHandlers {
     return {
       onRunStart: () => {
+        // Per *round*, so guard on the turn: a run that calls three tools fires
+        // this three times and the user needs telling once.
+        if (!this.#running) {
+          this.#announcedOutcome = false;
+          this.#announce(this.#strings.announceResponding);
+        }
         this.#setRunning(true);
         // Open the answer group on the turn's first run so the pending
         // indicator (and everything after) lands inside the well. Idempotent:
@@ -3143,6 +3894,7 @@ export class AgUiChat extends HTMLElement {
           this.#revealWords(bubble);
         }
         attachCopyButtons(bubble, this.#strings);
+        this.#attachActions(bubble);
         this.#endStream();
         this.#noteUnread();
       },
@@ -3162,25 +3914,51 @@ export class AgUiChat extends HTMLElement {
         this.#cardFor(call);
       },
       onActivity: (activityType, content, messageId) => {
-        if (activityType === CHART_ACTIVITY_TYPE) {
-          if (this.#chartActivity) {
-            this.#drawActivityChart(messageId, content);
-          }
-          return;
-        }
-        if (activityType !== COMPACTION_ACTIVITY_TYPE) {
+        this.#drawActivity(messageId, activityType, content);
+      },
+      onCustomEvent: (name, value) => {
+        if (name === INVALIDATE_CUSTOM_NAME) {
+          this.#dispatchInvalidation(value);
           return;
         }
-        const removed = compactionRemoved(content);
-        if (removed === null) {
+        if (name === SUBAGENT_CUSTOM_NAME) {
+          this.#reportSubAgent(value);
           return;
         }
-        this.#appendNotice(
-          "🗜",
-          this.#strings.historyCompacted.replace("{count}", String(removed)),
-          "compaction",
+        // 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,
+        // persisted or replayed. A host that does not know the name simply has
+        // no listener, which is the graceful outcome the open field is for.
+        this.dispatchEvent(
+          new CustomEvent<CustomAgentDetail>(CUSTOM_AGENT_EVENT, {
+            detail: { name, value },
+            bubbles: true,
+            composed: true,
+          }),
         );
       },
+      onMessagesSnapshot: () => {
+        // Honoured for persistence and announced, not re-rendered.
+        //
+        // The store follows the server, because the server is authoritative
+        // about what the conversation *is* -- and it would follow it anyway:
+        // `@ag-ui/client` replaces `agent.messages` before any subscriber runs,
+        // and the run loop persists `agent.messages`. What was wrong was that
+        // it happened in silence, so the screen and the store disagreed and
+        // nobody found out until a reload served a transcript they had never
+        // seen. That is not reportable as a bug; it is reportable as "the chat
+        // lost my messages".
+        //
+        // Re-rendering from the snapshot was the other candidate and is
+        // declined: a snapshot can land mid-run, and rebuilding the transcript
+        // then would destroy the in-flight run's own UI state -- the streaming
+        // bubble, the open answer group, and every tool card keyed by call id,
+        // some of which are still waiting on results. Telling the reader costs
+        // none of that, and this is the same answer the same question already
+        // got for compaction, one handler up.
+        this.#appendNotice("\u{1F504}", this.#strings.historyReplaced, "history-replaced");
+      },
       onToolResult: (toolCallId, content) => {
         const card = this.#toolCards.get(toolCallId);
         if (card === undefined) {
@@ -3204,9 +3982,7 @@ export class AgUiChat extends HTMLElement {
         this.#showPending();
       },
       onActivityChanged: (messageId, activityType, content) => {
-        if (activityType === CHART_ACTIVITY_TYPE && this.#chartActivity) {
-          this.#drawActivityChart(messageId, content);
-        }
+        this.#drawActivity(messageId, activityType, content);
       },
       onRunEnd: () => {
         // Per-round end; the button stays on Stop until the whole interaction
@@ -3215,19 +3991,38 @@ export class AgUiChat extends HTMLElement {
         this.#endStream();
       },
       onError: (message) => {
+        this.#announcedOutcome = true;
+        this.#announce(this.#strings.announceFailed);
         this.#hidePending();
-        this.#revealWords(this.appendMessage(MESSAGE_ROLE.ASSISTANT, `⚠️ ${message}`));
+        const bubble = this.appendMessage(MESSAGE_ROLE.ASSISTANT, `⚠️ ${message}`);
+        bubble.classList.add("message--failed");
+        // A failure is the one message whose action row is only worth having
+        // for Retry: there is nothing here worth copying and nothing to rate.
+        // A dropped connection with no way back was the whole of the gap --
+        // uploads had a retry and runs did not.
+        //
+        // Not a `run-notice`: that element's contract is that it "never
+        // settles, takes no action, and carries no controls", and is explicitly
+        // "distinct from an error, which is a failure". This is a failure, so
+        // it stays an error and gains the control instead.
+        this.#attachActions(bubble, { rateable: false });
+        this.#revealWords(bubble);
         this.#endStream();
       },
       onCancelled: () => {
         // Deliberate stop, not a failure: keep whatever partial text already
         // streamed and add a muted note instead of an error bubble.
+        this.#announcedOutcome = true;
+        this.#announce(this.#strings.announceStopped);
         this.#hidePending();
         this.#appendStoppedNote();
         this.#endStream();
       },
       onSettled: () => {
         // Terminal guarantee: whatever path ended the run, return to rest.
+        if (!this.#announcedOutcome) {
+          this.#announce(this.#strings.announceAnswerReady);
+        }
         this.#hidePending();
         this.#setRunning(false);
         this.#endStream();
@@ -3268,15 +4063,100 @@ export class AgUiChat extends HTMLElement {
       side: this.#serverSettled.has(id) ? "server" : "client",
     }));
     this.#runTools = [];
+    const invalidated = [...this.#runInvalidated];
+    this.#runInvalidated = new Set<string>();
     this.dispatchEvent(
       new CustomEvent<RunFinishedDetail>(RUN_FINISHED_EVENT, {
-        detail: { tools },
+        detail: { tools, invalidated },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  /**
+   * Route one invalidation to the host, and remember it for the run summary.
+   *
+   * Dispatched immediately rather than only at the end, because that is what
+   * makes a long multi-step run feel live -- the list refreshes as the third of
+   * eight writes lands. The accumulated set rides
+   * {@link RUN_FINISHED_EVENT} as well, so a host that would rather refetch once
+   * upgrades by reading one extra field instead of adding a listener.
+   *
+   * Nothing is rendered, persisted or replayed. An invalidation is an
+   * imperative: it has no place in the transcript and no meaning once acted on,
+   * and replaying one on every thread load would be a refetch storm. That is the
+   * whole reason the server sends it as `CUSTOM` rather than as an activity.
+   */
+  #dispatchInvalidation(value: unknown): void {
+    const payload = (value ?? {}) as { keys?: unknown; reason?: unknown };
+    // Defensive about the payload, not about the name: `value` is typed
+    // `unknown` by the protocol, so a server can put anything there, and a
+    // malformed announcement must not take the run down with it.
+    const keys = Array.isArray(payload.keys)
+      ? payload.keys.filter((key): key is string => typeof key === "string")
+      : [];
+    if (keys.length === 0) {
+      return;
+    }
+    for (const key of keys) {
+      this.#runInvalidated.add(key);
+    }
+    this.dispatchEvent(
+      new CustomEvent<InvalidateDetail>(INVALIDATE_EVENT, {
+        detail: { keys, reason: typeof payload.reason === "string" ? payload.reason : null },
         bubbles: true,
         composed: true,
       }),
     );
   }
 
+  /**
+   * 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");
@@ -3286,7 +4166,7 @@ export class AgUiChat extends HTMLElement {
     note.textContent = this.#strings.stopped;
     this.#ensureGroup().appendChild(note);
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
   }
 
   /**
@@ -3311,7 +4191,7 @@ export class AgUiChat extends HTMLElement {
     this.#pending = pending;
     this.#ensureGroup().appendChild(pending);
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
   }
 
   /** Remove the pending indicator if shown. */
@@ -3331,7 +4211,7 @@ export class AgUiChat extends HTMLElement {
       const group = this.#ensureGroup();
       group.insertBefore(this.#thoughts.element, group.firstChild);
       this.#updateEmptyState();
-      this.#messages.scrollTop = this.#messages.scrollHeight;
+      this.#scroller.follow();
     }
     return this.#thoughts;
   }
@@ -3388,7 +4268,7 @@ export class AgUiChat extends HTMLElement {
     this.#streamBuffer = buffer;
     const bubble = this.#openStream();
     bubble.innerHTML = renderMarkdown(buffer, { allowImages: this.allowImages });
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
     return bubble;
   }
 
@@ -3439,7 +4319,7 @@ export class AgUiChat extends HTMLElement {
   #appendNotice(icon: string, text: string, kind: string): void {
     this.#ensureGroup().appendChild(renderRunNotice(icon, text, kind));
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
   }
 
   /**
@@ -3461,9 +4341,20 @@ export class AgUiChat extends HTMLElement {
    * arrives is not something to switch on for everybody.
    */
   enableCharts(routes: readonly ("tool" | "activity")[] = ["tool", "activity"]): void {
-    const first = !this.#chartActivity && !this.#toolRegistry.has(CHART_TOOL_NAME);
+    const first =
+      !this.#activityRenderers.has(CHART_ACTIVITY_TYPE) && !this.#toolRegistry.has(CHART_TOOL_NAME);
     if (routes.includes("activity")) {
-      this.#chartActivity = true;
+      // The chart is a registration like any host's, not a privileged branch.
+      // If the built-in cannot be expressed through the seam, the seam is not
+      // one -- so this is the test as much as the feature.
+      this.registerActivityRenderer({
+        type: CHART_ACTIVITY_TYPE,
+        render: (content) => {
+          const spec = chartSpecFrom(content);
+          return spec === null ? null : renderChart(spec);
+        },
+        removedNotice: this.#strings.chartUndrawable,
+      });
     }
     if (routes.includes("tool")) {
       this.registerTool(createChartTool());
@@ -3511,37 +4402,140 @@ export class AgUiChat extends HTMLElement {
     this.#afterTranscriptGrew();
   }
 
-  /** Draw, or redraw in place, the chart for one activity message. */
-  #drawActivityChart(messageId: string, content: unknown): void {
-    const spec = chartSpecFrom(content);
-    const block = spec === null ? null : renderChart(spec);
-    if (block === null) {
-      // The server superseded this chart with something undrawable. Leaving the
-      // old one up is the worst available answer: it shows numbers that have
-      // been retracted, reading as current, and a reload then drops the chart
-      // entirely because the *stored* content is the version we could not draw.
-      // Live and reload should agree, and both should say "gone" rather than
-      // one of them lying.
-      this.#activityBlocks.get(messageId)?.remove();
-      this.#activityBlocks.delete(messageId);
+  /**
+   * Teach this element to draw one kind of AG-UI activity.
+   *
+   * `activity_type` is one of exactly two fields the protocol leaves an open
+   * string, and it is the **content** one: an activity is materialised into a
+   * message, persisted with the thread, and replayed on every restore. Its
+   * sibling `CUSTOM` carries an imperative and is dispatched to the page
+   * instead ({@link CUSTOM_AGENT_EVENT}).
+   *
+   * That asymmetry decides which carrier a server should use. Content has a
+   * place in the conversation and should come back; an imperative has no place
+   * and no meaning once acted on.
+   *
+   * ```js
+   * chat.registerActivityRenderer({
+   *   type: "build_status",
+   *   render: (content) => {
+   *     const el = document.createElement("div");
+   *     el.textContent = `Build ${content.status}`;
+   *     return el;
+   *   },
+   * });
+   * ```
+   *
+   * Registering a type twice replaces the earlier renderer, so a host can
+   * override a built-in -- `chart` and `compaction` are registrations like any
+   * other, not privileged branches.
+   *
+   * ⚠ `render` runs again on every thread load. See {@link ActivityRenderer}
+   * for what that requires of it.
+   */
+  registerActivityRenderer(registration: ActivityRegistration): void {
+    this.#activityRenderers.set(registration.type, registration);
+    this.#unhandledActivityTypes.delete(registration.type);
+  }
+
+  /**
+   * Activity types that arrived with nobody registered to draw them.
+   *
+   * Deliberately the only trace an unhandled activity leaves. Ignoring an
+   * unknown name is the protocol's own answer and the whole point of an open
+   * field, so warning would fire on every forward-compatible server -- but
+   * "nothing happened and nothing was said" is impossible to debug, so the set
+   * is readable. Accumulates for the element's lifetime, across threads.
+   */
+  get unhandledActivityTypes(): readonly string[] {
+    return [...this.#unhandledActivityTypes];
+  }
+
+  /**
+   * Draw, replace or remove one activity, whatever kind it is.
+   *
+   * The single path for all three routes an activity arrives by -- pushed
+   * (`onActivity`), patched (`onActivityChanged`) and replayed from history --
+   * which is why the renderer contract has to be pure: the same content is
+   * drawn again on every thread load.
+   *
+   * An unregistered type draws nothing and says nothing. That is the protocol's
+   * own answer -- a client that does not know a name ignores the event -- and a
+   * warning here would fire on every well-behaved forward-compatible server,
+   * while a placeholder would put the protocol's growth in the user's face.
+   * {@link unhandledActivityTypes} is the way to find out what arrived.
+   */
+  #drawActivity(messageId: string, activityType: string, content: unknown): void {
+    const registration = this.#activityRenderers.get(activityType);
+    if (registration === undefined) {
+      this.#unhandledActivityTypes.add(activityType);
+      return;
+    }
+    let node: Node | null;
+    try {
+      node = registration.render(content);
+    } catch (error) {
+      // `render` is consumer code and this runs inside the history replay,
+      // where a throw abandons the loop and takes every later turn of the
+      // transcript with it -- silently, and again on every reload. One activity
+      // that fails to draw is worth losing; the rest of the conversation is not.
+      console.warn(`ag-ui-chat: render failed for activity ${activityType}`, error);
+      node = null;
+    }
+    if (node === null) {
+      this.#removeActivity(messageId, activityType, registration.removedNotice, content);
       return;
     }
     const existing = this.#activityBlocks.get(messageId);
     if (existing === undefined) {
-      this.#ensureGroup().appendChild(block);
+      this.#ensureGroup().appendChild(node as HTMLElement);
     } else {
-      // Replaced rather than appended: a server redrawing a chart under the same
-      // id means *this chart changed*, and a second copy below the first would
-      // read as two measurements instead of one that moved.
-      existing.replaceWith(block);
+      // Replaced rather than appended: a server redrawing under the same id
+      // means *this one changed*, and a second copy below the first would read
+      // as two measurements instead of one that moved.
+      existing.replaceWith(node);
     }
-    this.#activityBlocks.set(messageId, block);
+    this.#activityBlocks.set(messageId, node as HTMLElement);
     this.#afterTranscriptGrew();
   }
 
+  /**
+   * Take away an activity whose content stopped being drawable.
+   *
+   * Leaving the old one up is the worst available answer: it shows values that
+   * have been retracted, reading as current, and a reload drops it anyway
+   * because the *stored* content is the version that could not be drawn. Live
+   * and reload should agree, and both should say "gone".
+   *
+   * Removing is right; doing it in silence was not. A chart that had been drawn
+   * simply disappeared, with no `console` call anywhere on the path -- which
+   * nobody reports as a bug, they report as "the charts are flaky".
+   */
+  #removeActivity(
+    messageId: string,
+    activityType: string,
+    notice: string | undefined,
+    content: unknown,
+  ): void {
+    const had = this.#activityBlocks.has(messageId);
+    this.#activityBlocks.get(messageId)?.remove();
+    this.#activityBlocks.delete(messageId);
+    console.warn(
+      `ag-ui-chat: activity ${messageId} (${activityType}) was not drawable and has been ` +
+        "removed. A chart's points must each be a finite JSON number; a numeric column " +
+        "serialised as a string (a Decimal, typically) is rejected rather than coerced.",
+      content,
+    );
+    // Only when something was on screen: content that never drew has no
+    // disappearance to explain, and a notice for every rejected push is noise.
+    if (had && notice !== undefined) {
+      this.#appendNotice("\u{1F4C9}", notice, "chart-undrawable");
+    }
+  }
+
   #afterTranscriptGrew(): void {
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
   }
 
   #cardFor(call: AgUiToolCall): ToolCallCard {
@@ -3559,11 +4553,16 @@ 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();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
     return card;
   }
 }
@@ -3588,6 +4587,15 @@ function confirmPhrase(interrupt: Interrupt): string | undefined {
 }
 
 /** One tool call as a restored assistant message carries it. */
+/**
+ * Why a client tool call is gated behind the confirmation card.
+ *
+ * Only `"destructive"` -- the default `x-destructive` gate -- may be waived for
+ * the session. `confirmPredicate` is documented as authoritative, so a call it
+ * gates keeps asking.
+ */
+type ConfirmationRule = "destructive" | "predicate";
+
 interface RestoredToolCall {
   readonly id: string;
   readonly function: { readonly name: string; readonly arguments?: unknown };