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

package/src/core/ag_ui_chat.ts

@@ -1,19 +1,26 @@
+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,
   MESSAGE_ROLE,
   READ_PAGE_TOOL,
   RUN_FINISHED_EVENT,
   STATE_EVENT,
   SUBMIT_EVENT,
+  SUGGESTIONS_ACTIVITY_TYPE,
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
@@ -31,7 +38,7 @@ import { isNavigates } from "../tools/is_navigates.js";
 import { createPageActionTools, type ResolvePageTarget } from "../tools/page_action_tools.js";
 import { createPageMapContext, type PageMap } from "../tools/page_map.js";
 import { createPageStateTools, type PageState } from "../tools/page_state.js";
-import { parseToolCatalog } from "../tools/parse_tool_catalog.js";
+import { parseToolCatalog, type ToolCatalogEntry } from "../tools/parse_tool_catalog.js";
 import { createRouteTools, type RouteMap } from "../tools/route_map.js";
 import {
   type ApprovalRenderer,
@@ -46,12 +53,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,
@@ -62,7 +77,9 @@ 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 { 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";
@@ -80,13 +97,14 @@ import {
   type ClientConversationStore,
   type NavigationCheckpoint,
   SessionStorageStore,
+  writeStoredItem,
 } from "./conversation_store.js";
 import { type AgentFactory, createHttpAgent } from "./create_http_agent.js";
 import { RemoteConversationStore } from "./remote_conversation_store.js";
 import { RunIndex } from "./run_index.js";
 import { type TranscribeHandler, transcribeAudio } from "./transcribe_audio.js";
 import { type UploadHandler, uploadAttachment } from "./upload_attachment.js";
-import { mintThread, withCredentials } from "./utils.js";
+import { mintThread, warnOnCrossOriginCredentials, withCredentials } from "./utils.js";
 
 /** The role a rendered chat message takes. */
 export type MessageRole = (typeof MESSAGE_ROLE)[keyof typeof MESSAGE_ROLE];
@@ -107,6 +125,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>>;
 }
@@ -126,6 +151,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. */
@@ -156,6 +258,7 @@ const CONNECT_TIME_ATTRIBUTES = [
   "data-attachment-max-bytes",
   "data-transcribe-url",
   "data-threads-url",
+  "data-threads-cache",
   "data-tools-url",
   "data-skills-url",
   "data-skills",
@@ -187,6 +290,20 @@ 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.
+ *
+ * Per document rather than per origin, and released on disconnect, because the
+ * question it answers is "is another element on this page using these keys right
+ * now" — not "has anything ever used them". A registry that never released would
+ * turn every remount, and every framework re-render that moves the node, into a
+ * false collision that costs the element its own conversation.
+ */
+const CLAIMED_NAMESPACES = new Set<string>();
+
 /**
  * `<ag-ui-chat>` — a framework-free chat sidebar Web Component over AG-UI.
  *
@@ -224,6 +341,23 @@ export class AgUiChat extends HTMLElement {
    */
   getHeaders: (() => Record<string, string>) | null = null;
 
+  /**
+   * Origins, besides the page's own, that this element may send {@link headers}
+   * and {@link getHeaders} credentials to without saying so on the console.
+   *
+   * Seven attributes name a URL, and every one of them carries these headers.
+   * They are plain HTML, so a page that builds one from a query parameter or
+   * from tenant-authored configuration has handed an attacker the destination,
+   * and the token leaves on the element's first request. Naming the origins you
+   * expect turns that from silent into either confirmed or reported.
+   *
+   * A notice rather than a refusal: a cross-origin agent is a documented
+   * deployment, so refusing would break working installations to defend against
+   * a page that is already interpolating untrusted data into its own markup.
+   * Leaving this empty costs nothing but one console line per foreign origin.
+   */
+  trustedOrigins: readonly string[] = [];
+
   /**
    * Permit `<img>` in rendered assistant markdown. **Off by default**: a
    * model-controlled image URL is fetched with no user interaction, which
@@ -232,6 +366,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;
 
@@ -259,6 +410,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
@@ -381,14 +549,40 @@ export class AgUiChat extends HTMLElement {
   resolvePageTarget: ResolvePageTarget = (target) => document.querySelector<HTMLElement>(target);
 
   /**
-   * Card labels fetched from a server tool catalog (`data-tools-url`), keyed by
-   * tool name. The base layer behind {@link toolSummaries}: an explicit entry in
-   * `toolSummaries` wins, this fills the rest. Populated once on connect.
+   * The server tool catalog fetched from `data-tools-url`, keyed by tool
+   * name. Cards label themselves from each entry's `summary`, the base
+   * layer behind {@link toolSummaries}: an explicit entry in `toolSummaries`
+   * wins, this fills the rest. Held as whole entries rather than labels so a
+   * field the server sent is not lost on the way in. Populated once on connect.
    */
-  #toolCatalog: Record<string, string> = {};
+  #toolCatalog: Record<string, ToolCatalogEntry> = {};
+
+  /**
+   * Foreign origins already reported, so the notice is once per origin per
+   * element rather than once per request. Per-element rather than module-level,
+   * because two elements on one page are two separate configurations.
+   */
+  #warnedOrigins = new Set<string>();
   /** The resolved string table (defaults ← `data-strings` ← `strings`). */
   #strings: UiStrings = DEFAULT_UI_STRINGS;
 
+  /**
+   * The tool names the current round handed the agent, captured as the catalog
+   * went out.
+   *
+   * The registry is mount-wide but {@link getTools} is per-run, so a host is
+   * free to scope what a given page offers — and a call naming a tool this run
+   * withheld must not reach the handler that is merely still registered.
+   * Snapshotted rather than re-asked at dispatch: a provider is a function, and
+   * calling it again asks a question the run already answered, which is exactly
+   * the window a scoped catalog exists to close.
+   *
+   * Empty until the first round advertises, which cannot precede a call: the
+   * client builds `RunAgentInput.tools` at the top of every round, before the
+   * calls that round produces are executed.
+   */
+  #advertisedTools: ReadonlySet<string> = new Set();
+
   readonly #toolRegistry = new ClientToolRegistry();
   /** Tool-call cards awaiting execution, keyed by call id. */
   readonly #toolCards = new Map<string, ToolCallCard>();
@@ -398,7 +592,16 @@ export class AgUiChat extends HTMLElement {
    * 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>();
@@ -413,7 +616,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;
@@ -470,6 +743,12 @@ export class AgUiChat extends HTMLElement {
   // revealed progressively as it streamed, so the word reveal must not re-animate
   // it; ≤1 ⇒ it arrived at once and the word reveal is appropriate.
   #streamDeltas = 0;
+  // The accumulated answer the next render will draw. Deltas overwrite it
+  // (each one carries the whole answer), so a frame always draws the latest.
+  #streamBuffer = "";
+  // The frame that render is queued on, or `null` when nothing is queued —
+  // also the flag saying a delta is still undrawn.
+  #streamFrame: number | null = null;
   #pending: HTMLDivElement | null = null;
   // The current assistant turn's grouping container. One `.answer`
   // wraps everything a single answer produces — streamed text, tool cards, the
@@ -484,9 +763,23 @@ export class AgUiChat extends HTMLElement {
   #thoughts: ThoughtsBlock | null = null;
   #threadId = "";
   // Per-instance suffix for the origin-scoped storage keys (collapsed / theme /
-  // active thread), so two instances on one origin don't clobber each other.
-  // Empty ⇒ the pre-namespacing global keys (back-compat). Resolved on connect.
+  // size), so two instances on one origin don't clobber each other. Empty ⇒ the
+  // pre-namespacing global keys (back-compat). Resolved on connect; the
+  // conversation adds `user-key` on top of it, see #conversationNs.
   #storageNs = "";
+  // The entry this element put in CLAIMED_NAMESPACES, to take back out on
+  // disconnect. `null` when it claimed nothing (no id, no endpoint, or it lost
+  // the claim to an element that mounted first).
+  #claimedNs: string | null = null;
+  // The fallback namespace minted when the preferred one was already claimed,
+  // with the preferred value it was minted for — so the element keeps it across
+  // remounts, but re-resolves if the host answers the warning with an `id`.
+  #generatedNs = "";
+  #generatedFor = "";
+  // The `sessionStorage`-backed store, which the element may therefore re-scope
+  // on a principal change. `null` when the host injected a store of its own
+  // kind, whose keying the element does not know and must not guess at.
+  #builtinStore: SessionStorageStore | null = null;
   // Bumped on every #rehydrate; a replay whose generation is stale (a newer
   // thread switch started while it awaited a slow store) drops its result.
   #rehydrateGeneration = 0;
@@ -513,6 +806,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) => {
@@ -544,7 +864,7 @@ export class AgUiChat extends HTMLElement {
     if (this.#runIndex === null) {
       this.#runIndex = new RunIndex(
         url,
-        () => this.#requestHeaders(),
+        () => this.#headersFor(url),
         () => this.#requestCredentials(),
       );
     }
@@ -579,6 +899,7 @@ export class AgUiChat extends HTMLElement {
       endpoint,
       headers: this.#requestHeaders(),
       getHeaders: () => this.#requestHeaders(),
+      trustedOrigins: this.trustedOrigins,
       ...this.#credentialsOption(),
       threadId: this.#threadId,
       // The seed the endpoints assume: nothing. The snapshot is the history.
@@ -587,7 +908,7 @@ export class AgUiChat extends HTMLElement {
     const client = new AgUiClient({
       agent,
       handlers: this.#handlers(),
-      getTools: () => this.getTools(),
+      getTools: () => this.#advertiseTools(),
       getContext: () => this.#buildContext(),
       executeTool: (call) => this.#executeTool(call),
       resolveInterrupts: (interrupts) => this.#resolveInterrupts(interrupts),
@@ -599,12 +920,15 @@ 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());
   }
 
   /** Attributes the element reacts to after it has been connected. */
   static get observedAttributes(): string[] {
-    return ["title-text", "placement", "credentials", ...CONNECT_TIME_ATTRIBUTES];
+    return ["title-text", "placement", "credentials", "user-key", ...CONNECT_TIME_ATTRIBUTES];
   }
 
   attributeChangedCallback(name: string, previous: string | null, value: string | null): void {
@@ -638,6 +962,16 @@ export class AgUiChat extends HTMLElement {
       this.#title.textContent = value ?? this.#strings.title;
       return;
     }
+    if (name === "user-key") {
+      // Before connect there is nothing to move: connectedCallback resolves the
+      // namespace from the attribute as it stands by then. An absent attribute
+      // and an empty one name the same (unnamed) principal, so neither is a
+      // change worth acting on.
+      if (this.#connected && (previous ?? "") !== (value ?? "")) {
+        this.#changePrincipal(previous ?? "", value ?? "");
+      }
+      return;
+    }
     // Everything else here is read once, in connectedCallback, to build chrome
     // that then exists or does not. A later change is silently ignored and the
     // symptom is an affordance that never appears, which reads as a broken
@@ -657,7 +991,18 @@ export class AgUiChat extends HTMLElement {
     );
   }
 
-  /** Declare a frontend tool the agent may call. */
+  /**
+   * Declare a frontend tool the agent may call.
+   *
+   * **A handler's thrown message leaves the browser.** When a handler rejects,
+   * its `Error.message` is posted back as that call's tool result — into the
+   * conversation, on to the AG-UI endpoint, persisted server-side, and
+   * forwarded to the model provider on every later round. That is deliberate,
+   * since it is what lets the agent recover from a failure it caused; but it
+   * means an internal hostname, a signed URL or a stack-derived path in a
+   * rethrown error is disclosed to parties the host never chose. Throw the
+   * message you would be content for the model to read, and log the detail.
+   */
   registerTool(tool: ClientTool): void {
     this.#toolRegistry.register(tool);
   }
@@ -831,10 +1176,23 @@ export class AgUiChat extends HTMLElement {
           });
     this.#confirmAbort = null;
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
     return answer;
   }
 
+  /**
+   * The catalog for the round about to start, remembering what it offered.
+   *
+   * Every path to a frontend tool goes through here first — the client asks
+   * for `RunAgentInput.tools` at the top of each round — so this is the one
+   * place that can know what the agent was actually told about.
+   */
+  #advertiseTools(): Tool[] {
+    const tools = this.getTools();
+    this.#advertisedTools = new Set(tools.map((tool) => tool.name));
+    return tools;
+  }
+
   /** Resolve a tool by name: built-in tools first, then the registry. */
   #resolveTool(name: string): ClientTool | null {
     const builtin = this.#builtinTools().find((t) => t.name === name);
@@ -856,6 +1214,39 @@ export class AgUiChat extends HTMLElement {
     this.setAttribute("endpoint", value);
   }
 
+  /**
+   * Who the stored conversation belongs to, from the `user-key` attribute.
+   *
+   * Set it to whatever identifies the signed-in principal — a user id, an
+   * account id, a hash of one. The value joins the storage namespace, so two
+   * principals in the same tab cannot read each other's transcript, and
+   * **changing it purges what the previous one left behind**.
+   *
+   * That purge is the reason this is a live attribute rather than a
+   * connect-time one. `sessionStorage` survives same-tab navigation, so it
+   * survives a logout; and a single-page app signs out through its own router
+   * without remounting anything, so there is no other moment at which the
+   * element could find out. The host naming the new principal — or dropping the
+   * attribute — is the signal.
+   *
+   * Absent means exactly today's behaviour, which is why nothing breaks by
+   * leaving it off: the conversation is scoped to the element and to nobody in
+   * particular, and on a shared workstation it carries into whoever signs in
+   * next in the same tab.
+   *
+   * The first value to arrive is treated as a host naming the user who was
+   * already there, not as a handover: the conversation in progress moves into
+   * the principal's namespace rather than being destroyed, so an element
+   * configured by an async auth handshake keeps what is on screen.
+   */
+  get userKey(): string {
+    return this.getAttribute("user-key") ?? "";
+  }
+
+  set userKey(value: string) {
+    this.setAttribute("user-key", value);
+  }
+
   /**
    * Cookie policy for **every** request this element makes, as `fetch`'s own
    * `credentials` mode (`"omit"` / `"same-origin"` / `"include"`). Mirrored to
@@ -907,6 +1298,25 @@ export class AgUiChat extends HTMLElement {
     return { ...this.headers, ...this.getHeaders?.() };
   }
 
+  /**
+   * The request headers, having first reported the destination if it is foreign.
+   *
+   * Every caller that sends these headers knows its URL, and `#requestHeaders`
+   * does not -- so the check lives here, on the path that has both, rather than
+   * being repeated at each call site with a chance to be forgotten at the next
+   * one added.
+   */
+  #headersFor(url: string): Record<string, string> {
+    const headers = this.#requestHeaders();
+    warnOnCrossOriginCredentials(
+      url,
+      Object.keys(headers),
+      this.trustedOrigins,
+      this.#warnedOrigins,
+    );
+    return headers;
+  }
+
   /** The configured cookie policy as `fetch` spells it; `undefined` when unset. */
   #requestCredentials(): RequestCredentials | undefined {
     return this.credentials ?? undefined;
@@ -927,8 +1337,8 @@ export class AgUiChat extends HTMLElement {
   }
 
   /** The `fetch` init for the element's own plain GETs (catalogs). */
-  #fetchInit(): RequestInit | undefined {
-    return withCredentials({ headers: this.#requestHeaders() }, this.#requestCredentials());
+  #fetchInit(url: string): RequestInit | undefined {
+    return withCredentials({ headers: this.#headersFor(url) }, this.#requestCredentials());
   }
 
   /**
@@ -956,10 +1366,10 @@ export class AgUiChat extends HTMLElement {
   }
 
   connectedCallback(): void {
-    // Resolve the per-instance storage namespace (id, else endpoint) before any
-    // key read/write, so this instance doesn't share collapsed/theme/thread
-    // state with another on the same origin.
-    this.#storageNs = this.id !== "" ? this.id : this.endpoint;
+    // Resolve the per-instance storage namespace before any key read/write, so
+    // this instance doesn't share collapsed/theme/thread state with another on
+    // the same origin.
+    this.#storageNs = this.#claimNamespace();
     // Restore a dragged size before the panel paints, so it does not snap from
     // the placement default to the user's width on the first frame.
     this.#applySize(this.#readSize());
@@ -989,8 +1399,13 @@ export class AgUiChat extends HTMLElement {
     this.#initSkills();
     // Namespace the built-in default store too (a host-injected store is used
     // verbatim). Must precede #wireThreadStore, which wraps the current store.
-    if (this.#storageNs !== "" && this.conversationStore instanceof SessionStorageStore) {
-      this.conversationStore = new SessionStorageStore(this.#storageNs);
+    if (this.conversationStore instanceof SessionStorageStore) {
+      const namespace = this.#conversationNs();
+      // Remembered either way: this is the element's own store, so a later
+      // `user-key` change may move it to another namespace.
+      this.#builtinStore =
+        namespace === "" ? this.conversationStore : new SessionStorageStore(namespace);
+      this.conversationStore = this.#builtinStore;
     }
     this.#wireThreadStore();
     this.#wireAttachments();
@@ -1064,9 +1479,26 @@ export class AgUiChat extends HTMLElement {
    */
   disconnectedCallback(): void {
     this.#connected = false;
+    // Give the namespace back. A disconnect is not necessarily a farewell — a
+    // DOM move and a framework re-render both look like one — and an element
+    // that could not reclaim its own namespace on the way back in would lose
+    // its conversation to a false collision.
+    if (this.#claimedNs !== null) {
+      CLAIMED_NAMESPACES.delete(this.#claimedNs);
+      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;
+    }
   }
 
   /**
@@ -1143,7 +1575,7 @@ export class AgUiChat extends HTMLElement {
     return (file, onProgress, signal) =>
       uploadAttachment(file, {
         url,
-        headers: this.#requestHeaders(),
+        headers: this.#headersFor(url),
         ...this.#credentialsOption(),
         onProgress,
         signal,
@@ -1179,7 +1611,7 @@ export class AgUiChat extends HTMLElement {
     return (audio) =>
       transcribeAudio(audio, {
         url,
-        headers: this.#requestHeaders(),
+        headers: this.#headersFor(url),
         ...this.#credentialsOption(),
       });
   }
@@ -1192,6 +1624,126 @@ 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 client-side upload size cap from `data-attachment-max-bytes`. */
   #attachmentMaxBytes(): number {
     const attr = this.getAttribute("data-attachment-max-bytes");
@@ -1240,15 +1792,21 @@ export class AgUiChat extends HTMLElement {
    * delete through that server endpoint (wrapping the current store as the
    * client-only fallback), so the history drawer shows durable, cross-device
    * threads. Without it, the client store's per-tab threads are used.
+   *
+   * `data-threads-cache="false"` drops the local copy of the message bodies —
+   * for the deployment that pointed history at a server precisely so that
+   * transcripts do not sit in the browser. The client-only concerns (the active
+   * thread id, the navigation checkpoint) keep their local store either way.
    */
   #wireThreadStore(): void {
     const url = this.getAttribute("data-threads-url");
     if (url !== null) {
       this.conversationStore = new RemoteConversationStore(
         url,
-        () => this.#requestHeaders(),
+        () => this.#headersFor(url),
         this.conversationStore,
         () => this.#requestCredentials(),
+        this.getAttribute("data-threads-cache") !== "false",
       );
     }
   }
@@ -1260,7 +1818,7 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     try {
-      const response = await fetch(url, this.#fetchInit());
+      const response = await fetch(url, this.#fetchInit(url));
       this.#toolCatalog = parseToolCatalog(await response.json());
     } catch {
       // Network/parse failure: cards fall back to toolSummaries / raw names.
@@ -1308,7 +1866,7 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     try {
-      const response = await fetch(url, this.#fetchInit());
+      const response = await fetch(url, this.#fetchInit(url));
       this.#backendSkills = parseSkills(await response.json());
       this.#recomputeSkills();
     } catch {
@@ -1409,7 +1967,7 @@ export class AgUiChat extends HTMLElement {
     } else {
       this.removeAttribute("collapsed");
     }
-    sessionStorage.setItem(this.#storageKey(COLLAPSED_KEY), collapsed ? "1" : "0");
+    writeStoredItem(this.#storageKey(COLLAPSED_KEY), collapsed ? "1" : "0");
     // Expanding is what marks the waiting answers read; collapsing starts a
     // fresh count. Either way the badge is cleared and the host told.
     this.#setUnread(0);
@@ -1446,7 +2004,7 @@ export class AgUiChat extends HTMLElement {
   toggleTheme(): void {
     const next = this.getAttribute("theme") === "dark" ? "light" : "dark";
     this.setAttribute("theme", next);
-    sessionStorage.setItem(this.#storageKey(THEME_KEY), next);
+    writeStoredItem(this.#storageKey(THEME_KEY), next);
     this.#syncThemeGlyph();
   }
 
@@ -1557,7 +2115,7 @@ export class AgUiChat extends HTMLElement {
   /** Persist a dragged size per tab, alongside the collapsed/theme preferences. */
   #persistSize(size: ResizeSize): void {
     const stored = { ...this.#readSize(), ...size };
-    sessionStorage.setItem(this.#storageKey(SIZE_KEY), JSON.stringify(stored));
+    writeStoredItem(this.#storageKey(SIZE_KEY), JSON.stringify(stored));
   }
 
   /** The persisted size for this instance, or an empty record. */
@@ -1576,6 +2134,130 @@ export class AgUiChat extends HTMLElement {
     }
   }
 
+  /**
+   * Claim this element's storage namespace: its `id`, else its `endpoint`.
+   *
+   * The endpoint fallback exists so a lone widget restores its conversation
+   * across reloads with nothing asked of the page author. It stops working the
+   * moment there are two of them — a docked support panel and an inline page
+   * assistant against one agent mount, neither carrying an `id`, which nothing
+   * requires — because both resolve to the same string and then share a thread
+   * pointer, a drawer index and every message key. Whichever mounts second
+   * adopts the first's active thread and rehydrates its transcript into its own
+   * panel: one conversation's content inside another, on the same page.
+   *
+   * So the namespace is claimed by the first element to mount under it, and a
+   * second is given one of its own plus a warning naming the fix. The first
+   * element keeps the endpoint namespace, which is what leaves the ordinary
+   * single-element case exactly as it was.
+   *
+   * The generated namespace is random rather than derived from mount order.
+   * That costs the second element its history across reloads — the warning says
+   * so, and an `id` fixes it — which is the honest trade against an order-based
+   * name that would silently hand a stored conversation to whichever element
+   * happened to mount second on the next load.
+   */
+  #claimNamespace(): string {
+    const preferred = this.id !== "" ? this.id : this.endpoint;
+    // Nothing to key on. The pre-namespacing global keys, as before: an element
+    // with neither an id nor an endpoint cannot send anything, so what it would
+    // be claiming is an empty conversation.
+    if (preferred === "") {
+      return "";
+    }
+    // Already lost this claim once. Keep the fallback rather than drifting back
+    // onto a namespace the other element may since have released, which would
+    // swap this panel's conversation for that one's.
+    if (this.#generatedFor === preferred) {
+      return this.#generatedNs;
+    }
+    if (!CLAIMED_NAMESPACES.has(preferred)) {
+      CLAIMED_NAMESPACES.add(preferred);
+      this.#claimedNs = preferred;
+      return preferred;
+    }
+    this.#generatedFor = preferred;
+    this.#generatedNs = `${preferred}~${randomUUID()}`;
+    console.warn(
+      `<ag-ui-chat>: another element on this page already stores its ` +
+        `conversation under "${preferred}", so this one has been given a ` +
+        "throwaway namespace of its own — the two would otherwise share a " +
+        "thread pointer, a history drawer and every message. Give each " +
+        "<ag-ui-chat> its own id to keep them apart and let this one restore " +
+        "its conversation across reloads.",
+    );
+    return this.#generatedNs;
+  }
+
+  /**
+   * The conversation store's namespace: this element's, scoped to the principal
+   * {@link userKey} names.
+   *
+   * Only the conversation is principal-scoped. The panel's own collapsed / size
+   * / theme preferences stay on `#storageNs`, because they are this element's
+   * UI state rather than anyone's data — they carry no word of what was said —
+   * and because they are read once while connecting, so re-scoping them under a
+   * live element would rearrange the panel around a user who had only just
+   * signed in.
+   */
+  #conversationNs(key: string = this.userKey): string {
+    return key === "" ? this.#storageNs : `${this.#storageNs}#${key}`;
+  }
+
+  /**
+   * Move the element's client state from one principal to another.
+   *
+   * The whole reason {@link userKey} is live: `sessionStorage` outlives a
+   * logout, because a logout is a navigation (or, in a single-page app, not
+   * even that) rather than a tab close. Nothing remounts, so the host naming
+   * the new principal is the only signal the element will ever get.
+   */
+  #changePrincipal(previousKey: string, nextKey: string): void {
+    const previous = this.#conversationNs(previousKey);
+    const next = this.#conversationNs(nextKey);
+    if (previousKey === "") {
+      // Absent to present is not a handover. It is the documented late
+      // configuration shape — the element mounts, an auth handshake resolves,
+      // and only then is the user known — so the conversation already on screen
+      // belongs to this principal and moves with them. Moving rather than
+      // copying also matters: a copy left behind under the unscoped namespace
+      // is a transcript the next key-less mount would happily adopt.
+      SessionStorageStore.adopt(previous, next);
+      this.#rescopeStore(next);
+      return;
+    }
+    SessionStorageStore.purge(previous);
+    this.#rescopeStore(next);
+    // The transcript on screen, the run in flight and the replayed history all
+    // belong to the principal who just left. Purging storage without clearing
+    // these would leave the previous user's conversation visible to the new one.
+    this.#cancelRun();
+    this.#resetState();
+    this.#setRunning(false);
+    this.#setUnread(0);
+    this.#threadId = this.conversationStore.threadId();
+    void this.#rehydrate();
+    void this.#refreshDrawer();
+  }
+
+  /**
+   * Rebuild the `sessionStorage` store under `namespace`, re-wrapping it for
+   * `data-threads-url` exactly as connecting did.
+   *
+   * A store of the host's own kind is left alone: a store that holds its data
+   * somewhere the element cannot see has to scope itself. The transcript on
+   * screen is still cleared either way — the host swapped principals, and that
+   * much is the element's to act on.
+   */
+  #rescopeStore(namespace: string): void {
+    if (this.#builtinStore === null) {
+      return;
+    }
+    this.#builtinStore = new SessionStorageStore(namespace);
+    this.conversationStore = this.#builtinStore;
+    this.#wireThreadStore();
+  }
+
   /** This instance's namespaced form of an origin-scoped storage key. */
   #storageKey(base: string): string {
     return this.#storageNs === "" ? base : `${base}:${this.#storageNs}`;
@@ -1679,7 +2361,22 @@ export class AgUiChat extends HTMLElement {
   /** Drop the in-memory run + transcript, leaving the thread id untouched. */
   #resetState(): void {
     this.#client = null;
-    this.#streamingBubble = 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.
+    this.#endStream();
     this.#currentGroup = null;
     this.#thoughts = null;
     this.#hidePending();
@@ -1687,13 +2384,50 @@ export class AgUiChat extends HTMLElement {
     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) {
@@ -1724,6 +2458,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);
   }
 
@@ -1829,7 +2564,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
@@ -1868,8 +2605,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;
     }
@@ -1944,7 +2681,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;
   }
 
@@ -1968,9 +2712,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");
 
@@ -2045,11 +2786,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";
@@ -2140,9 +2938,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,
@@ -2207,7 +3010,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];
   }
 
   /**
@@ -2534,6 +3398,7 @@ export class AgUiChat extends HTMLElement {
         // token must still reach every request — the factory's fetch wrapper
         // re-reads this on each call.
         getHeaders: () => this.#requestHeaders(),
+        trustedOrigins: this.trustedOrigins,
         ...this.#credentialsOption(),
         threadId: this.#threadId,
         initialMessages: this.#initialMessages,
@@ -2542,7 +3407,7 @@ export class AgUiChat extends HTMLElement {
       this.#client = new AgUiClient({
         agent,
         handlers: this.#handlers(),
-        getTools: () => this.getTools(),
+        getTools: () => this.#advertiseTools(),
         getContext: () => this.#buildContext(),
         executeTool: (call) => this.#executeTool(call),
         resolveInterrupts: (interrupts) => this.#resolveInterrupts(interrupts),
@@ -2566,15 +3431,75 @@ 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.
+   */
+  #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));
+  }
+
+  /** 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> {
@@ -2590,7 +3515,15 @@ export class AgUiChat extends HTMLElement {
     // transcript places itself against its own card, and by the time it runs the
     // card is no longer reachable by id.
     this.#cardElements.set(call.id, card.element);
-    const tool = this.#resolveTool(call.name);
+    // Scoped out of this round's catalog ⇒ not a frontend tool of ours, for
+    // this round. A host that offers `delete_record` only on the page where
+    // deleting makes sense has said something about *this* run, and a call
+    // arriving anyway (a hallucinated name, or one steered by text the model
+    // just read) must not find the handler that happens to be registered
+    // mount-wide. Treated exactly as an unknown name rather than as a refusal:
+    // withholding a tool and never registering it are the same statement, and
+    // the branch below already says the honest thing for both.
+    const tool = this.#advertisedTools.has(call.name) ? this.#resolveTool(call.name) : null;
     if (tool === null) {
       // Not a client tool. A server-side tool's real output arrives via
       // `onToolResult` (TOOL_CALL_RESULT) and already settled the card — only
@@ -2625,7 +3558,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") {
@@ -2641,9 +3575,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");
@@ -2685,6 +3623,12 @@ export class AgUiChat extends HTMLElement {
         // The navigation never happened; drop the dangling checkpoint.
         this.conversationStore.saveCheckpoint(this.#threadId, null);
       }
+      // The handler's own message, verbatim, in two places at once: the card,
+      // which the user sees, and the tool result, which goes to the endpoint,
+      // is persisted there and is replayed to the model on every later round.
+      // Kept verbatim because a real reason is what lets the agent recover —
+      // and said out loud on `registerTool`, because the second destination is
+      // invisible from the host's side and is not one it can take back.
       const message = error instanceof Error ? error.message : String(error);
       card.settle(TOOL_CALL_STATUS.ERROR, message);
       this.#showPending();
@@ -2719,6 +3663,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(
@@ -2736,6 +3687,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
@@ -2746,6 +3705,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
@@ -2760,16 +3726,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;
@@ -2778,6 +3749,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:
@@ -2802,7 +3779,10 @@ export class AgUiChat extends HTMLElement {
         this.#hidePending();
         // The answer has begun — fold the thoughts away so they don't crowd it.
         this.#thoughts?.collapse();
-        this.#streamInto(buffer);
+        this.#queueStream(buffer);
+        // Counted per delta received, not per render: the word reveal asks
+        // whether the answer *arrived* progressively, which coalescing renders
+        // must not change the answer to.
         this.#streamDeltas += 1;
       },
       onTextEnd: (buffer) => {
@@ -2815,7 +3795,8 @@ export class AgUiChat extends HTMLElement {
           this.#revealWords(bubble);
         }
         attachCopyButtons(bubble, this.#strings);
-        this.#streamingBubble = null;
+        this.#attachActions(bubble);
+        this.#endStream();
         this.#noteUnread();
       },
       onToolCall: (call) => {
@@ -2834,25 +3815,47 @@ 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) {
-          return;
-        }
-        const removed = compactionRemoved(content);
-        if (removed === null) {
+        this.#drawActivity(messageId, activityType, content);
+      },
+      onCustomEvent: (name, value) => {
+        if (name === INVALIDATE_CUSTOM_NAME) {
+          this.#dispatchInvalidation(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) {
@@ -2876,33 +3879,50 @@ 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
         // settles — the user must be able to cancel between tool rounds.
         this.#hidePending();
-        this.#streamingBubble = null;
+        this.#endStream();
       },
       onError: (message) => {
+        this.#announcedOutcome = true;
+        this.#announce(this.#strings.announceFailed);
         this.#hidePending();
-        this.#revealWords(this.appendMessage(MESSAGE_ROLE.ASSISTANT, `⚠️ ${message}`));
-        this.#streamingBubble = null;
+        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.#streamingBubble = null;
+        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.#streamingBubble = null;
+        this.#endStream();
         // Belt-and-suspenders: a tool card still pending at settle (e.g. a
         // server tool whose result never streamed because the connection
         // dropped) would hang forever — settle it to the no-result fallback.
@@ -2940,9 +3960,48 @@ 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,
       }),
@@ -2958,7 +4017,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();
   }
 
   /**
@@ -2983,7 +4042,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. */
@@ -3003,21 +4062,83 @@ 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;
   }
 
-  #streamInto(buffer: string): HTMLDivElement {
+  /**
+   * The bubble the current answer streams into, opening it on first sight.
+   *
+   * Opened the moment a token arrives rather than on the frame that draws it,
+   * so the answer's container replaces the pending dots straight away and the
+   * turn never shows a gap while the first render waits for a frame.
+   */
+  #openStream(): HTMLDivElement {
     if (this.#streamingBubble === null) {
       this.#streamingBubble = this.appendMessage(MESSAGE_ROLE.ASSISTANT, "");
       this.#streamDeltas = 0;
     }
-    this.#streamingBubble.innerHTML = renderMarkdown(buffer, { allowImages: this.allowImages });
-    this.#messages.scrollTop = this.#messages.scrollHeight;
     return this.#streamingBubble;
   }
 
+  /**
+   * Queue a render of the answer so far, at most one per frame.
+   *
+   * Each `TEXT_MESSAGE_CONTENT` event carries the *whole* accumulated answer,
+   * and drawing it means marked + DOMPurify over the entire document and a
+   * wholesale replacement of the bubble's subtree. Once per token that is
+   * quadratic in the answer's length — a long answer is agent-controlled, so
+   * an ordinary run becomes a progressively stalling tab — and every rebuild
+   * takes any selection or focus inside the bubble with it.
+   *
+   * A frame is the right grain: it is the fastest anything on screen can
+   * change anyway, so a burst of tokens costs one parse and the text still
+   * appears to flow rather than in visible chunks.
+   */
+  #queueStream(buffer: string): void {
+    this.#streamBuffer = buffer;
+    this.#openStream();
+    if (this.#streamFrame !== null) {
+      return;
+    }
+    this.#streamFrame = requestAnimationFrame(() => {
+      this.#streamFrame = null;
+      this.#streamInto(this.#streamBuffer);
+    });
+  }
+
+  /** Render `buffer` into the streaming bubble now, dropping any queued frame. */
+  #streamInto(buffer: string): HTMLDivElement {
+    // A frame still queued would otherwise fire after this and repaint the
+    // bubble with whatever the last delta held — behind the buffer just drawn.
+    if (this.#streamFrame !== null) {
+      cancelAnimationFrame(this.#streamFrame);
+      this.#streamFrame = null;
+    }
+    this.#streamBuffer = buffer;
+    const bubble = this.#openStream();
+    bubble.innerHTML = renderMarkdown(buffer, { allowImages: this.allowImages });
+    this.#scroller.follow();
+    return bubble;
+  }
+
+  /**
+   * Close the current answer's streaming bubble.
+   *
+   * Draws a queued render first. A run that ends without a text end — a
+   * cancel, an error, a round boundary — leaves the last delta sitting in the
+   * queue, and simply dropping the bubble here would strand it: the partial
+   * answer the user stopped mid-sentence would lose its final tokens, or be an
+   * empty bubble above the stopped note.
+   */
+  #endStream(): void {
+    if (this.#streamFrame !== null) {
+      this.#streamInto(this.#streamBuffer);
+    }
+    this.#streamingBubble = null;
+  }
+
   /**
    * The card for ``call``, creating and appending it on first sight.
    *
@@ -3049,7 +4170,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();
   }
 
   /**
@@ -3071,9 +4192,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());
@@ -3121,37 +4253,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 {
@@ -3167,13 +4402,13 @@ export class AgUiChat extends HTMLElement {
       typeof labelled === "string"
         ? labelled
         : (this.toolSummaries[call.name] ??
-          this.#toolCatalog[call.name] ??
+          this.#toolCatalog[call.name]?.summary ??
           prettifyToolName(call.name));
     const card = new ToolCallCard(call.name, call.args, summary, this.#strings);
     this.#toolCards.set(call.id, card);
     this.#ensureGroup().appendChild(card.element);
     this.#updateEmptyState();
-    this.#messages.scrollTop = this.#messages.scrollHeight;
+    this.#scroller.follow();
     return card;
   }
 }
@@ -3198,6 +4433,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 };