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

package/README.md

@@ -50,9 +50,16 @@ No framework, no Django, no admin specifics live here. Downstream consumers (e.g
   - [Collapsing to the launcher](#collapsing-to-the-launcher)
 - [Tool-call display modes](#tool-call-display-modes)
 - [Markdown rendering](#markdown-rendering)
+- [Follow-up suggestions](#follow-up-suggestions)
+- [Editing a gated call before approving it](#editing-a-gated-call-before-approving-it)
+- [Localizing the timestamps](#localizing-the-timestamps)
+- [Message actions: copy, retry, feedback](#message-actions-copy-retry-feedback)
+- [Quoting a selection](#quoting-a-selection)
 - [Run notices: compaction and agent skills](#run-notices-compaction-and-agent-skills)
 - [Skills: prompt chips and slash palette](#skills-prompt-chips-and-slash-palette)
 - [MPA durability: surviving full page reloads](#mpa-durability-surviving-full-page-reloads)
+  - [Who the stored conversation belongs to (`user-key`)](#who-the-stored-conversation-belongs-to-user-key)
+  - [Mounting more than one chat on a page](#mounting-more-than-one-chat-on-a-page)
 - [Host seams: the SPA story](#host-seams-the-spa-story)
 - [Public API surface](#public-api-surface)
 - [Theming, density, and placement](#theming-density-and-placement)
@@ -162,7 +169,9 @@ another origin, add `credentials="include"` too; see
 | `data-skills` | — | Inline JSON skill catalog. |
 | `data-skills-url` | — | URL of a JSON skill catalog (fetched with the element's headers and cookie policy). |
 | `data-tools-url` | — | URL of a server tool-label catalog (`[{ name, summary, description? }]`), fetched with the element's headers and cookie policy; labels tool-call cards for server-side tools. |
+| `user-key` | `userKey` | Who the stored conversation belongs to — any string identifying the signed-in principal. Joins the storage namespace, and **changing it purges what the previous principal left behind**. Live (not connect-time): a logout is the host's to announce. See [Who the stored conversation belongs to](#who-the-stored-conversation-belongs-to-user-key). |
 | `data-threads-url` | — | URL of a server thread index (django-ag-ui's `ThreadsView`); enables durable, cross-device chat history. |
+| `data-threads-cache` | — | **On by default.** `="false"` stops mirroring message bodies into `sessionStorage` when `data-threads-url` is set, for a deployment that put history on the server so transcripts stay off the client. Only meaningful alongside `data-threads-url`. |
 | `data-runs-url` | — | URL of a server run index (django-ag-ui's `RunsView`); reveals the header's ⭯ *Continue a run* panel. See [Resuming a run](#resuming-a-run). |
 | `data-attachments-url` | — | URL of the file-upload endpoint (django-ag-ui's `AttachmentsView`); reveals the composer's paperclip picker + drag-and-drop. |
 | `data-attachment-accept` | — | `<input accept>` list for client-side type filtering (e.g. `image/*,.pdf`). The server stays authoritative. |
@@ -173,6 +182,7 @@ another origin, add `credentials="include"` too; see
 | `data-icon-url` | — | Header (and launcher) icon image URL. A slotted `slot="icon"` wins; see [Header & launcher icon](#header-and-launcher-icon). |
 | `data-launcher-icon-url` | — | Icon image URL for the collapsed launcher only, when it should differ from the header's. Falls back to `data-icon-url`; a slotted `slot="launcher"` wins over both. |
 | `data-unread-badge` | — | **On by default.** `="false"` hides the launcher's unread badge; the count and the `ag-ui-unread` event keep running. See [Collapsing to the launcher](#collapsing-to-the-launcher). |
+| `data-quote-selection` | — | **On by default.** `="false"` stops the transcript offering to quote a selection. `quote()` keeps working either way. See [Quoting a selection](#quoting-a-selection). |
 
 Each header control also takes its own icon slot — `icon-history`, `icon-checkpoints`,
 `icon-new`, `icon-collapse` — with the built-in glyph as the fallback, so a host can project a
@@ -196,7 +206,7 @@ same way: `icon-send`, `icon-stop`, `icon-attach`, `icon-voice`.
 `confirmPredicate`, `askUser`, `agentFactory`, `getTools`, `getContext`, `routeMap`, `navigate`,
 `getPageMap`, `autoInjectPageMap`, `conversationStore`, `uploadHandler`, `transcribeHandler`,
 `navigationResult`, `skillContext`, `toolSummaries`, `strings`, `resolvePageTarget`, plus the
-mirrors `endpoint` / `toolDisplay` / `collapsed` / `credentials`.
+mirrors `endpoint` / `userKey` / `toolDisplay` / `collapsed` / `credentials`.
 
 `headers` and `getHeaders` authenticate **every** request the element makes, not only the agent
 run; `getHeaders` is the one to use for a credential that rotates. See
@@ -332,6 +342,41 @@ One asymmetry: uploads use `XMLHttpRequest` for real progress events, and its co
 two-state. `include` turns it on; every other value leaves it off. `omit` therefore cannot suppress
 cookies on a *same-origin* upload — supply your own `uploadHandler` if that matters.
 
+### Where those credentials are allowed to go
+
+Every URL in the table above is a plain HTML attribute, and `headers` / `getHeaders` are attached to
+whatever they name. That is what makes a cross-origin agent work — and it is also why a page must
+never build one of those attributes out of a URL parameter, a CMS field, or anything else it did not
+choose itself. Whoever supplies the value chooses where the token goes: the browser preflights the
+custom header, any server willing to answer receives it, and it leaves on the element's first
+request, before the user has typed anything.
+
+Treat all seven as trusted configuration. When any of them resolves to another origin, the element
+says so on the console once per origin, naming the destination and the header names it is about to
+send. That covers all seven, not the agent endpoint alone: the tool catalog, the skills list, the
+thread index, the attachment upload and the transcription endpoint carry the same headers, and
+reporting only the agent would report the least interesting of them.
+
+To confirm destinations you chose on purpose and silence the notice, name their origins:
+
+```js
+chat.trustedOrigins = ["https://api.example.com"];
+```
+
+That covers every endpoint the element requests itself, and is forwarded to `createHttpAgent`, so a
+host that does not override `agentFactory` needs nothing else. A custom factory can also be given
+the option directly:
+
+```js
+chat.agentFactory = (options) =>
+  createHttpAgent({ ...options, trustedOrigins: ["https://api.example.com"] });
+```
+
+Origins are compared as `URL.origin` produces them — scheme, host and port. A notice is a notice,
+not a refusal: nothing is blocked, because a cross-origin agent is a supported deployment and
+refusing would break working installations to defend against a page that is already interpolating
+untrusted data into its own markup.
+
 ### Framework hosts: configure before you insert
 
 `headers`, `getHeaders` and `credentials` are read when a request is made, so they can be set at any
@@ -449,6 +494,13 @@ card (honouring `data-tool-display`), so server-side output is visible too. The
 and context are read **fresh on every run** (`getTools()` / `getContext()`), so they always reflect
 the current page state.
 
+The catalog a run advertises is also the set that run can execute. Override `getTools` to scope
+what a page offers — say, exposing `delete_record` only where deleting makes sense — and a call
+naming a tool you withheld is treated exactly as a call naming a tool you never registered: no
+handler runs, and the card settles with the no-result label. Withholding is per run, so the
+mount-wide registry can stay complete. Hosts that leave `getTools` alone advertise the built-ins
+plus everything registered, which is precisely what dispatch could reach anyway.
+
 ### Stopping a run
 
 While a run is in flight the **Send button becomes Stop** (same button, label/`aria-label` swap,
@@ -491,10 +543,19 @@ chat.registerTool({
 });
 ```
 
-Names must be unique (registering a duplicate throws). Each `<ag-ui-chat>` element owns its own
+Registering a name twice replaces the earlier handler rather than throwing, so a re-fired
+host ref or React StrictMode's double-invoke is harmless -- but two different tools sharing
+a name means the second silently wins. Each `<ag-ui-chat>` element owns its own
 registry, AG-UI client, and Shadow DOM, so **multiple instances on one page never interfere** —
 there is no module-level shared state anywhere in the package.
 
+**A handler's thrown message leaves the browser.** If 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
+there, and replayed to the model provider on every later round. That is deliberate — a real reason
+is what lets the agent recover — but it means an internal hostname, a signed URL or a
+stack-derived path in a rethrown error is disclosed to parties you never chose. Throw the message
+you would be content for the model to read, and log the detail instead.
+
 ### Inline confirmation (`x-destructive` / `x-confirm` / `confirmPredicate`)
 
 When a tool call needs confirmation, the element appends an **inline confirmation card** (a
@@ -506,6 +567,8 @@ transcript as a resolved record after the decision:
 - **Confirm** → the handler runs and the result is posted back.
 - **Cancel** → a `"User declined the action."` result is posted; the agent acknowledges on its
   next turn.
+- **Always allow** → the handler runs *and* this tool stops prompting for the rest of the
+  session. See below for when this button appears.
 
 Whether a call is gated is decided in this order:
 
@@ -513,9 +576,27 @@ Whether a call is gated is decided in this order:
 2. Else if `chat.confirmPredicate` is set, its boolean return is authoritative — given the tool
    name + parsed args it decides per-call (so one tool can be instant for some args and confirmed
    for others, which a static flag can't express).
-3. Else the element falls back to [`isDestructive(parameters)`](src/tools/is_destructive.ts),
+3. Else if the user has waived this tool name for the session, the call runs.
+4. Else the element falls back to [`isDestructive(parameters)`](src/tools/is_destructive.ts),
    which reads the `x-destructive` JSON-Schema flag.
 
+#### "Always allow", and why only sometimes
+
+A prompt that is approved nearly every time is not a decision, it is a speed bump — and the
+reflex it trains is what makes the rare refusal easy to miss. Anthropic published that users
+approve **~93%** of Claude Code permission prompts manually and called interactive confirmation
+*"behaviorally unreliable as a sole safety mechanism"* on that basis. The waiver exists so the
+prompts that remain still mean something.
+
+**The button is offered only on cards raised by step 4** — the `x-destructive` default. Where
+`confirmPredicate` is what gated the call, there is no button, because that predicate is
+documented as authoritative and letting one click retire it would silently defeat a host policy.
+The offer and the allowlist sit on the same path, so there is no dead button either.
+
+The waiver is **per tool name and per element**, held in memory and never persisted. A session
+decision that outlived the tab would be a permanent grant made by one click — which is what
+`autoConfirm` already exists to say deliberately. It is cleared when the element goes away.
+
 AG-UI has no built-in risk flag, so destructiveness is carried as a JSON-Schema extension at the
 **schema root**: `parameters["x-destructive"] = true` (use the exported `X_DESTRUCTIVE_KEY`
 constant). There is no parallel metadata channel and no name heuristic — destructiveness is exactly
@@ -525,6 +606,13 @@ the `x-destructive` flag (or `confirmPredicate`). The registry forwards the flag
 If the schema carries an `x-confirm` string (use `X_CONFIRM_KEY`), the card shows it as the prompt;
 otherwise it falls back to a generic `Run "<tool>"?`.
 
+**This gate covers frontend tools only.** A server-side tool's schema never reaches the browser —
+tool definitions travel client-to-server on `RunAgentInput.tools`, and the only channel coming back
+is the label catalog (`data-tools-url`), which carries `{ name, summary, description? }` and no
+flags. So marking a server tool destructive does not produce a card here; gate it server-side
+instead (see [Server-side tool approval](#server-side-tool-approval-interrupts)), which surfaces as
+an approval card in the same transcript.
+
 ```js
 // Per-call: confirm a delete only when it would remove more than one row.
 chat.confirmPredicate = (name, args) =>
@@ -947,6 +1035,67 @@ it runs again every time the conversation is restored.
 
 ---
 
+## Drawing other things the server pushes
+
+`activityType` is an open string the protocol does not enumerate — `"chart"` is
+just the one the component ships a renderer for. Register your own and the
+server can push anything it likes into the transcript:
+
+```js
+chat.registerActivityRenderer({
+  type: "build_status",
+  render: (content) => {
+    const el = document.createElement("div");
+    el.className = "build";
+    el.textContent = `Build ${content.status}`;
+    return el;   // return null for content not worth drawing
+  },
+});
+```
+
+**`render` runs again on every thread load**, so it carries the same contract as
+a client tool's `render`: a pure function of `content`, deterministic, and free
+of effects outside the node it returns. Activities are materialised into
+`role: "activity"` messages and persisted with the transcript, so a renderer that
+writes to the page instead of returning DOM fires again on every restore.
+
+The component places what you return, keyed by the activity's `messageId`, so a
+server repeating an id **replaces** your node rather than adding a second one —
+the same in-place update charts get. Returning `null` removes whatever was there:
+live and reload should agree, and the stored content is the version that could
+not be drawn.
+
+`chart` and `compaction` are registrations exactly like yours, not privileged
+branches, so registering either name **replaces the built-in**.
+
+### Which carrier should the server use?
+
+AG-UI leaves exactly two payload names open, and they are not
+interchangeable:
+
+| | Carrier | Reaches | Persisted | Replayed |
+| --- | --- | --- | --- | --- |
+| **Content** | `ACTIVITY_SNAPSHOT` | the transcript | yes | yes |
+| **Imperative** | `CUSTOM` | your page, as [`ag-ui-custom`](#events) | no | no |
+
+⇒ **Content has a place in the conversation and should come back. An imperative
+has no place and no meaning once acted on** — replaying "refetch the board" on
+every thread load is a bug, not a feature. If it has to survive a reload, it is
+content.
+
+### Finding out what arrived
+
+An activity nobody registered for draws nothing and logs nothing — that is the
+protocol's own answer, and warning would fire on every forward-compatible
+server. But silence is hard to debug, so the names are readable:
+
+```js
+chat.unhandledActivityTypes; // ["pydantic_ai_thinking", …]
+```
+
+Note `"chart"` appears there until you call `enableCharts(["activity"])`, which
+is the honest answer to "I pushed a chart and nothing happened".
+
 ## Tool-call display modes
 
 How much a tool-call card shows is set via the `data-tool-display` attribute (or `toolDisplay`
@@ -1042,9 +1191,12 @@ via the `resize-handle` part.
 Assistant bubbles render sanitized markdown/HTML via [`marked`](https://www.npmjs.com/package/marked)
 (GitHub-flavoured, single-newline line breaks) piped through
 [DOMPurify](https://www.npmjs.com/package/dompurify). User messages stay literal text. The
-allowlist permits emphasis, code, lists, quotes, headings, links, tables, and images (`img`); links
-are hardened with `target="_blank" rel="noopener noreferrer"`; `iframe`/`style`/scripting are
-excluded. The exported helper `renderMarkdown(text)` does this standalone. `marked` and `dompurify`
+allowlist permits emphasis, code, lists, quotes, headings, links, tables, and — when `allowImages`
+is set — images; links are hardened with `target="_blank" rel="noopener noreferrer"`;
+`iframe`/`style`/scripting are excluded, as are every `data-*` and `aria-*` attribute and every
+`class` but a code fence's `language-*` hint, so model output cannot dress itself up as the
+component's own approval or tool-call chrome. The exported helper `renderMarkdown(text)` does this
+standalone. `marked` and `dompurify`
 are runtime dependencies.
 
 An animated 3-dot "thinking" indicator (`role="status"`, with an aria-label) appears before the
@@ -1062,6 +1214,181 @@ reveal). It honours `prefers-reduced-motion` (collapsing to instant).
 
 ---
 
+## Follow-up suggestions
+
+The agent can offer the *next* question, not just answer this one. Registered
+skill chips are static and host-configured, so they can say "summarize this" but
+never "want me to update the shipping address too?" after a tool has run.
+
+The server pushes an `ACTIVITY_SNAPSHOT` under the `suggestions` type — with
+django-ag-ui, `suggestions_activity([...])`. The component draws each prompt as
+a chip; clicking one sends it as the user's message, exactly as if they had
+typed it.
+
+```json
+{ "activityType": "suggestions",
+  "content": { "prompts": ["Update the shipping address too"] } }
+```
+
+**Chips are content.** They ride the same activity envelope as charts, so they
+persist and a reload puts them back, and a set pushed under an id already on
+screen replaces that row rather than adding a second one.
+
+At most **4** prompts of **120** characters each — `MAX_SUGGESTIONS` and
+`MAX_SUGGESTION_CHARS`, both exported. The server-side helper *raises* past
+those bounds while this side silently drops: that asymmetry is deliberate, since
+the producer can report the problem and the client cannot.
+
+Nothing to enable. A `suggestions` activity from a server that pushes one is
+drawn; an `activity_type` this component does not know is ignored, which is what
+the open field is for.
+
+## Editing a gated call before approving it
+
+AG-UI's resume payload carries `editedArgs`, and the protocol gates it on the
+agent's own `approveWithEdits` capability. The approval card can offer it:
+
+```js
+chat.approveWithEdits = true; // your server accepts editedArgs
+```
+
+**Off by default, and an assertion about your server rather than a
+negotiation** — capabilities are not on the wire this component reads, so it
+cannot check. Turned on against a server that ignores `editedArgs`, a user would
+edit arguments it silently discards, which is worse than not offering.
+
+The card then shows the call's arguments as editable JSON. `editedArgs` rides
+the resume payload **only when something actually changed**, so a server can tell
+"approved as proposed" from "approved, but like this" without diffing what it
+already sent. Unparseable JSON, or JSON that is not an object, keeps the card
+open with the reason on it rather than approving the original behind the user's
+back.
+
+Only offered for an interrupt naming a tool call this component holds a card
+for — the card is where the arguments still are.
+
+## Localizing the timestamps
+
+There is **no `Intl` anywhere in this component**. The relative timestamps in the
+thread drawer and checkpoint panel (`"5m ago"`, `"2d ago"`) are deliberately
+locale-neutral: a component that guessed a locale would disagree with the page
+it is embedded in, and being wrong in a second language is worse than being
+neutral in one.
+
+That is a good default and a bad requirement, so it is replaceable:
+
+```js
+const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
+chat.formatRelativeTime = (ts) =>
+  rtf.format(Math.round((ts - Date.now()) / 60000), "minute");
+```
+
+`relativeTime` is exported too, for a host that wants to build on the built-in
+rather than replace it.
+
+## Message actions: copy, retry, feedback
+
+Every finished assistant message carries a small row of actions beneath it —
+a **sibling** of the bubble, never a child, so the buttons never join the
+message's own text.
+
+- **Retry** re-asks the question. 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.
+- **Copy** puts the message's text on the clipboard, and says so on the button.
+  A refused clipboard permission is reported there too, rather than thrown.
+- **Thumbs up / down** fire [`ag-ui-feedback`](#events) and **store nothing**.
+
+Retry sits on the **last** answer only. Re-running an older turn is branching,
+and for a page-driving agent editing a past turn is not neutral — those turns
+clicked buttons, and re-running turn 3 does not un-save what turn 5 saved.
+
+!!! note
+    A retried turn **re-runs its tools.** The previous attempt already did what
+    it did, and this does not undo it. Confirmation still applies, so a
+    destructive tool asks again — unless the user waived it for this session
+    with *Always allow*.
+
+A failed run gets the same row, with Retry and Copy and no rating: error text is
+what people paste into a bug report, but "the connection dropped" is not a
+statement about answer quality and mixing it into feedback makes that signal say
+less. This is why a dropped connection is still rendered as an **error** rather
+than demoted to a run notice — a notice "never settles, takes no action, and
+carries no controls", and a failure with a way back needs one.
+
+`retryLastTurn()` is public, for a host driving its own message UI.
+
+```js
+chat.addEventListener("ag-ui-feedback", (e) => {
+  analytics.track("assistant_rating", e.detail); // { content, rating }
+});
+
+await chat.retryLastTurn(); // false when there is nothing to ask again
+```
+
+## Quoting a selection
+
+Select any text in the transcript and a small **Quote** offer floats beside it.
+Taking it drops the selection into the composer as a markdown blockquote and
+leaves the caret on a fresh line under it — a quotation is how a question
+narrows to one part of an answer, so nothing is sent until you say what you are
+asking.
+
+Quoting **appends**, after whatever is already typed, so a second quotation is a
+second thing being asked about rather than a replacement for the first. Long
+selections are capped at 500 characters: select-all-then-quote is a gesture the
+transcript already answers, and pasting the whole conversation back costs tokens
+to say nothing.
+
+Set `data-quote-selection="false"` to turn the offer off. The `quote-selection`
+`part` styles it.
+
+### The half that matters: selection in **your** page
+
+The transcript is the easy half. A chat mounted beside a table, a diff or a
+report is sitting in the surface the user actually works in — and *that*
+selection is one no hosted chat can reach.
+
+`offerQuoteInPage()` extends the same select-then-offer gesture to the whole
+page. It is opt-in, because it listens on your document:
+
+```js
+const stop = chat.offerQuoteInPage();       // the whole page
+chat.offerQuoteInPage(document.querySelector("#report")); // or one region
+```
+
+For a deliberate trigger instead of a selection, `quote(text)` is the seam
+underneath:
+
+```js
+// "Ask about this row" — a button on each row of your own table.
+row.querySelector(".ask").addEventListener("click", () => {
+  chat.quote(row.innerText);
+});
+```
+
+`quote()` never sends — pair it with [`sendMessage()`](#sending-from-your-own-ui)
+if you want a one-click "explain this" that skips the composer entirely.
+
+> **Do not write the four-line version of `offerQuoteInPage()`.**
+> A `mouseup` listener that quotes every settled selection appends to the
+> composer on every drag the user made to *read*, to copy, or to fix a typo —
+> and it cannot tell a selection in your prose from one inside the user's own
+> half-typed `<input>`, because Chrome reports a field's internal selection
+> through `document.getSelection()` as an ordinary range over the field's
+> **wrapper**. The text reads back perfectly and nothing about the range says
+> where it came from; the only signal is `document.activeElement`. That guard,
+> plus skipping the widget's own transcript, plus retiring a fixed-position
+> affordance on scroll, is what the method is for.
+
+> **Reading a selection out of a shadow tree takes care too.**
+> Engines disagree about what `document.getSelection()` reports for a selection
+> made *inside* a shadow root: WebKit rescopes the endpoints to the host element,
+> so you get the whole widget and none of the words, while Chromium hands back
+> the shadow nodes directly. `getComposedRanges` settles it, and this component
+> uses it where it exists. `quotableSelection(container, roots)` is exported if
+> you have the same problem in your own component.
+
 ## Run notices: compaction and agent skills
 
 Some things a run does are neither text nor a tool the user asked for — the server condensed
@@ -1177,6 +1504,87 @@ triggers a full reload. Before the handler navigates, the element writes a check
 
 The MPA round-trip becomes a clean observation point instead of a dropped conversation.
 
+### Who the stored conversation belongs to (`user-key`)
+
+`sessionStorage` is scoped to a tab, not to a session. It survives every same-tab navigation,
+and a logout is a navigation — so on a shared workstation, one user's transcript is still sitting
+there when the next user signs in and the chat mounts again. Transcripts routinely quote record
+data, so treat that as the default and turn it off:
+
+```html
+<ag-ui-chat endpoint="/agent/" user-key="{{ request.user.pk }}"></ag-ui-chat>
+```
+
+The value is any string that identifies the principal — a user id, an account id, a hash of one.
+It joins the storage namespace, so two principals in the same tab cannot reach each other's
+conversation, and **changing it purges everything the previous principal stored**: transcript,
+history drawer index and navigation checkpoints, for this element's namespace only.
+
+Set it live, from script, as part of signing out or in:
+
+```js
+chat.userKey = String(session.userId); // or "" on sign-out
+```
+
+That is why it is a live attribute rather than a connect-time one. A single-page app signs a user
+out through its own router without remounting anything, so the host naming the new principal — or
+dropping the attribute — is the only signal the element will ever get. Removing the attribute
+purges too, so a sign-out that simply clears it is safe.
+
+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 instead of being
+destroyed. So an element configured by an async auth handshake — the shape described in
+[Framework hosts](#framework-hosts-configure-before-you-insert) — keeps what is on screen.
+
+Two things it deliberately does not do. It does not scope the panel's own collapsed / dragged-size
+/ theme preferences, which are this element's UI state and carry no conversation content. And it
+does not encrypt or hide anything from the page: any script on the origin can still read
+`sessionStorage`. It scopes and it purges.
+
+**Without it, nothing changes** — including the carry-over above. A conversation is scoped to the
+element and to nobody in particular, and on a shared workstation it will be there for whoever signs
+in next in the same tab.
+
+For a deployment that keeps history server-side, `data-threads-cache="false"` stops the local
+mirror of the message bodies as well, so choosing `data-threads-url` actually keeps transcripts off
+the client:
+
+```html
+<ag-ui-chat endpoint="/agent/" data-threads-url="/agent/threads/" data-threads-cache="false">
+</ag-ui-chat>
+```
+
+The client-only concerns (the active thread id, the navigation checkpoint) keep their local store
+either way, so reloads and navigating tools still work. What is lost is the offline fallback: when
+the thread endpoint is unreachable the transcript comes back empty rather than stale, and the
+drawer's offline list loses its previews — a preview being an excerpt of a message, which is the
+thing being kept off the client. Constructing the store yourself takes the same option:
+
+```js
+chat.conversationStore = new RemoteConversationStore(
+  "/agent/threads/",
+  () => ({ "X-CSRFToken": token }),
+  new SessionStorageStore(),
+  () => "same-origin",
+  false, // cacheMessages
+);
+```
+
+`SessionStorageStore.purge(namespace)` is the same primitive the element uses, for a host driving
+its own store from its own sign-out path.
+
+### Mounting more than one chat on a page
+
+Give each `<ag-ui-chat>` its own `id`. The storage namespace is the element's `id`, falling back to
+its `endpoint` — so two elements with no `id` against the same agent mount (a docked support panel
+and an inline page assistant, say) would resolve to the same namespace and share a thread pointer,
+a history drawer and every message key.
+
+They no longer do: the first element to mount keeps the namespace, and a second is given a
+throwaway one of its own plus a console warning. That keeps the two conversations apart, but the
+throwaway namespace is minted per mount, so the second element will not restore its conversation
+across a reload until it has an `id`.
+
 ---
 
 ## Host seams: the SPA story
@@ -1321,6 +1729,83 @@ substitute the other way round either, because shared state requires the *agent*
 `STATE_SNAPSHOT`, which is not the host's decision to make. Use state when the two ends edit one
 object; use this when your page owns the data and just needs to know it moved.
 
+**`ag-ui-custom`** *(event)* — the agent sent an AG-UI `CUSTOM` event.
+`detail: { name, value }` (typed `CustomAgentDetail`), both verbatim and uninterpreted.
+
+```js
+chat.addEventListener("ag-ui-custom", (e) => {
+  if (e.detail.name === "invalidate") {
+    void refetch(e.detail.value);
+  }
+  // Any other name: no listener, nothing happens. That is the intended outcome.
+});
+```
+
+`CUSTOM` is one of exactly two AG-UI carriers whose payload name is an open
+string the protocol does not enumerate, and it is the **imperative** one:
+something for your page to *do*. Its sibling `ACTIVITY_SNAPSHOT` carries
+transcript **content**, which is why an activity is materialised into a message,
+persisted with the thread and replayed on restore, and this is not.
+
+**That asymmetry is the rule for choosing between them.** Content has a place in
+the conversation and should replay. An imperative has no place and no meaning
+once acted on — replaying "refetch the board" on every thread load is a bug, not
+a feature. If it must survive a reload, it belongs on the other carrier.
+
+The element takes no view of what a name means and forwards every one, so a name
+it has never heard of reaches you unchanged. A host with no listener for a name
+simply ignores it, which is the graceful outcome an open field exists for.
+
+**`ag-ui-invalidate`** *(event)* — the agent named resources its write moved.
+`detail: { keys, reason }` (typed `InvalidateDetail`).
+
+One `CUSTOM` name routed to its own event so you do not have to string-match;
+every other name still arrives as `ag-ui-custom`. It fires **as each
+announcement arrives**, during the run, and the same keys ride
+`ag-ui-run-finished` again at the end as `invalidated`, de-duplicated.
+
+> **Do not reload the page on this.** The user was probably typing. An
+> agent-triggered reload or a blind refetch into a live form destroys unsaved
+> input, and from their side the page threw their work away on its own. Check
+> first, and offer rather than act:
+
+```js
+chat.addEventListener("ag-ui-invalidate", (e) => {
+  if (formIsDirty()) {
+    showBanner("This data changed. Refresh when you're ready.", e.detail.keys);
+    return;
+  }
+  refetch(e.detail.keys);   // e.detail.keys → ["orders", "orders/42"]
+});
+```
+
+**Keys are opaque and matching is exact.** `orders/42` does not imply `orders` —
+a prefix rule would be the 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; that is what TanStack query keys are built for.
+
+Already listening on `ag-ui-run-finished`? Upgrading is one line, 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();
+```
+
+| Server | Client | Result |
+| --- | --- | --- |
+| old | old | coarse refetch, as today |
+| new | old | the `CUSTOM` event is ignored; coarse refetch still fires |
+| old | new | `invalidated` is empty; the `else` branch runs |
+| new | new | precise, and live during the run |
+
+Nothing negotiates and nothing handshakes, which is what makes this shippable
+across repos with independent release cadences.
+
+**Note:** it reaches **the page that started the run**, during the run. There is one
+response stream per run and no channel to anybody else's browser.
+
 ## Resuming a run
 
 When the server persists run checkpoints (django-ag-ui's `step_store`), a run
@@ -1452,6 +1937,8 @@ re-export point. Internal modules import from leaf paths.
 | `SubmitDetail` | type | `detail` shape of the submit event. |
 | `ToggleDetail` | type | `detail` shape of the `ag-ui-toggle` event (`{ collapsed }`). |
 | `UnreadDetail` | type | `detail` shape of the `ag-ui-unread` event (`{ unread }`). |
+| `AttachmentsDetail` | type | `detail` shape of the `ag-ui-attachments` event (`{ attachments, pending }`). |
+| `StateDetail` | type | `detail` shape of the `ag-ui-state` event (`{ state }`). |
 
 ### AG-UI client & agent
 
@@ -1463,6 +1950,8 @@ re-export point. Internal modules import from leaf paths.
 | `ConnectionLostError` | class | Raised (→ `onError`) when a run's stream closes with no terminal AG-UI event. |
 | `createHttpAgent(options)` | function | Default agent factory (wraps `HttpAgent`). |
 | `AgentFactory` / `HttpAgentOptions` | type | Factory signature and its options. |
+| `ResolveInterrupts` | type | Resolver for server-side-tool approval interrupts (one decision per interrupt). |
+| `InterruptResponse` | type | One interrupt's answer: `resolved` (with an optional payload) or `cancelled`. |
 
 ### Tools & flags
 
@@ -1476,6 +1965,9 @@ re-export point. Internal modules import from leaf paths.
 | `PAGE_ACTIONS` | const | The page-action opt-in tokens (`scroll` / `drag`). |
 | `ResolvePageTarget` | type | `(target) => HTMLElement | null` — the page-target resolver. |
 | `X_DESTRUCTIVE_KEY` / `X_NAVIGATES_KEY` | const | The JSON-Schema extension keys. |
+| `parseToolCatalog(data)` | function | Parse a fetched `data-tools-url` catalog into a `name` → `summary` map. |
+| `ToolCatalogEntry` | type | One row of that catalog. |
+| `prettifyToolName(name)` | function | Last fallback of the tool-card label chain (`delete_record` reads as *Delete record*). |
 
 ### Host seams
 
@@ -1490,6 +1982,19 @@ re-export point. Internal modules import from leaf paths.
 | `PageState` | type | A page-state binding declaration. |
 | `Skill` | type | A launchable prompt (chip / `/`-command). |
 | `RunFinishedDetail` / `ToolRun` | type | `ag-ui-run-finished` detail: the tools an interaction ran, and which side ran them. |
+| `CustomAgentDetail` | type | `ag-ui-custom` detail: an AG-UI `CUSTOM` event's `name` and `value`, verbatim. |
+| `InvalidateDetail` | type | `ag-ui-invalidate` detail: the resource `keys` that moved, and the `reason`. |
+| `FeedbackDetail` | type | `ag-ui-feedback` detail: the rated message's `content` and the `rating`. |
+| `relativeTime` | function | The built-in locale-neutral timestamp formatter (`"5m ago"`), for a host building on it. |
+| `RelativeTimeFormatter` | type | What `formatRelativeTime` takes: an epoch-ms timestamp in, row text out. |
+| `renderSuggestionChips` | function | Draw a `suggestions` activity as chips that send themselves; `null` when nothing survives. |
+| `suggestionPrompts` | function | The usable prompts in a `suggestions` activity's content, bounded and trimmed. |
+| `attachMessageActions` | function | Give a finished bubble its action row (copy, and feedback when a handler is passed). |
+| `messageActionBar` | function | The empty action row for a bubble, created if it has none — the shared shell both callers use. |
+| `MessageActionsOptions` | type | What `attachMessageActions` takes: `strings`, a `text` source, an optional `onFeedback`. |
+| `ActivityRenderer` | type | Draws one activity from its `content`. Pure: it runs again on every restore. |
+| `ActivityRegistration` | type | What `registerActivityRenderer` takes: `type`, `render`, and an optional `removedNotice`. |
+| `createStateHookTools(binding)` / `StateHook` | deprecated | The former names for `createPageStateTools` / `PageState`. |
 
 ### Durability
 
@@ -1515,6 +2020,14 @@ re-export point. Internal modules import from leaf paths.
 | `AttachmentRef` | type | The durable upload ref (`{ id, name, mime, size, url? }`). |
 | `messageAttachments(message)` | function | Read the refs a restored user message carries. |
 
+### Voice input
+
+| Export | Kind | Summary |
+| --- | --- | --- |
+| `transcribeAudio(audio, options)` | function | The built-in transcription POST (multipart) → the transcript text. |
+| `TranscribeOptions` | type | `{ url, headers? }`. |
+| `TranscribeHandler` | type | `(audio) => Promise<string>` — the `transcribeHandler` swap seam (Web Speech, direct-to-provider). |
+
 ### UI & DOM primitives
 
 | Export | Kind | Summary |
@@ -1527,7 +2040,25 @@ re-export point. Internal modules import from leaf paths.
 | `UiStrings` | type | The flat table of every user-facing string. |
 | `DEFAULT_UI_STRINGS` | const | The English defaults (the override floor). |
 | `mergeUiStrings(overrides)` | function | Merge a partial override over the defaults. |
-| `renderMarkdown(text)` | function | Render sanitized markdown/HTML (marked + DOMPurify). |
+| `renderMarkdown(text, options?)` | function | Render sanitized markdown/HTML (marked + DOMPurify). |
+| `RenderMarkdownOptions` | type | `{ allowImages? }` — opt `<img>` back into the sanitized output. |
+| `requestApproval(host, request, options?)` | function | Append the inline approval card that gates a server-side tool. |
+| `ApprovalRequest` | type | What that card displays (`{ message?, toolName? }`). |
+| `ApprovalOptions` | type | `{ signal?, strings? }` — abort resolves the card as denied; `strings` localizes it. |
+| `ApprovalRenderer` | type | Replace the built-in approval card outright (`AgUiChat.approvalRenderer`). |
+| `requestQuestion(host, request, options?)` | function | Append the inline `ask_user` card (radios and/or free text). |
+| `QuestionRequest` | type | What that card asks. |
+| `QuestionOptions` | type | `{ signal?, strings? }` — abort resolves it with an empty answer. |
+| `QuestionRenderer` | type | Replace the built-in question card outright (`AgUiChat.questionRenderer`). |
+| `renderChart(spec)` | function | Draw one spec as a self-contained block, or `null` when it says nothing. |
+| `chartSpecFrom(value)` | function | Read an arbitrary payload into a `ChartSpec`, or `null` if it cannot be drawn honestly. |
+| `ChartSpec` / `ChartSeries` / `ChartKind` | type | A chart as data, one named series, and how it is drawn. |
+| `attachQuoteOffer(options)` | function | The page-side select-then-quote offer, with its guards. `AgUiChat.offerQuoteInPage()` is the one-line form. |
+| `PageQuoteOffer` / `PageQuoteOfferOptions` | type | The live offer (`{ element, detach }`) and what it takes. |
+| `quotableSelection(container, roots)` | function | The current selection when it lies inside `container`, read through the shadow-aware API where the engine has one. |
+| `QuotableSelection` | type | `{ text, rect }` — what was selected, and where it sits. |
+| `asQuote(text)` | function | Shape text as a markdown blockquote with a blank line after it. |
+| `MAX_QUOTE_CHARS` | const | The cap a quotation is truncated to (500). |
 | `typeInto` / `highlightThenClick` / `pressThenClick` / `selectOption` / `toggleControl` / `scrollIntoCenterView` / `flash` / `focusWithFlash` / `prefersReducedMotion` | function | Animation primitives. |
 | `fillField` / `clickElement` / `pressButton` / `selectControl` / `setControlValue` / `toggleCheckbox` | function | DOM-driver primitives. |
 | `setNativeValue` / `setNativeChecked` | function | Set a control via its native prototype setter (React-controlled inputs). |
@@ -1542,6 +2073,19 @@ re-export point. Internal modules import from leaf paths.
 | `TOGGLE_EVENT` | The collapse-toggle CustomEvent name (`ag-ui-toggle`). |
 | `UNREAD_EVENT` | The unread-count CustomEvent name (`ag-ui-unread`). |
 | `RUN_FINISHED_EVENT` | The interaction-finished CustomEvent name (`ag-ui-run-finished`). |
+| `CUSTOM_AGENT_EVENT` | The agent-`CUSTOM` CustomEvent name (`ag-ui-custom`). |
+| `INVALIDATE_EVENT` | The resource-invalidation CustomEvent name (`ag-ui-invalidate`). |
+| `FEEDBACK_EVENT` | The message-rating CustomEvent name (`ag-ui-feedback`). |
+| `SUGGESTIONS_ACTIVITY_TYPE` | The `activity_type` carrying follow-up prompts (`suggestions`). |
+| `MAX_SUGGESTIONS` | Most prompts one push draws (4). Mirrors the server's cap. |
+| `MAX_SUGGESTION_CHARS` | Longest one prompt may be (120). Mirrors the server's cap. |
+| `INVALIDATE_CUSTOM_NAME` | The AG-UI `CUSTOM` `name` that carries one (`ag_ui.invalidate`). |
+| `ATTACHMENT_EVENT` | The attachments-changed CustomEvent name (`ag-ui-attachments`). |
+| `STATE_EVENT` | The shared-state CustomEvent name (`ag-ui-state`). |
+| `CHART_ACTIVITY_TYPE` | The `ACTIVITY_SNAPSHOT` type a server sets to push a chart. |
+| `CHART_TOOL_NAME` | The name the built-in chart tool registers under (`render_chart`). |
+| `COMPACTION_ACTIVITY_TYPE` | The `ACTIVITY_SNAPSHOT` type reporting a trimmed history. |
+| `LOAD_CAPABILITY_TOOL` | The agent-side capability-loading tool's name. |
 | `MESSAGE_ROLE` | Message role constants. |
 | `TOOL_CALL_STATUS` | Tool-call card status constants. |
 | `TOOL_DISPLAY` | Tool-call display-mode constants (`minimal` / `compact` / `full`). |
@@ -1675,15 +2219,17 @@ component sets, so a new one cannot ship undocumented.
 
 | Feature | Parts |
 | --- | --- |
-| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `pending`, `stopped`, `resize-handle` |
+| Shell | `panel`, `header`, `title`, `icon`, `header-controls`, `messages`, `empty`, `pending`, `stopped`, `jump-latest`, `resize-handle` |
 | Header buttons | `header-button` on each, plus `history-button`, `checkpoints-button`, `new-button`, `collapse-button`, `theme-toggle` |
 | Collapsed widget | `launcher`, `launcher-icon`, `launcher-badge` |
 | Answers | `answer` (the per-turn group), `message` (plus `message-user`, `message-assistant`), `code-copy` |
 | Reasoning | `thoughts`, `thoughts-toggle`, `thoughts-body`, `thoughts-label` |
-| Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`), `run-notice-icon`, `run-notice-text` |
+| Follow-up suggestions | `suggestions`, `suggestion-chip` |
+| Message actions | `message-actions`, `message-action` (plus `message-action-retry`, `message-action-copy`, `message-action-up`, `message-action-down`) |
+| Run notices | `run-notice` (plus `run-notice-interrupted`, `run-notice-attachment-pending`, `run-notice-compaction`, `run-notice-skill`, `run-notice-history-replaced`, `run-notice-chart-undrawable`), `run-notice-icon`, `run-notice-text` |
 | Tool cards | `tool-card`, `tool-card-head`, `tool-card-icon`, `tool-card-name`, `tool-card-status`, `tool-card-decision`, `tool-card-toggle`, `tool-card-body`, `tool-card-section` (plus `tool-card-args-section`, `tool-card-result-section`), `tool-card-section-label` (plus `tool-card-args-label`, `tool-card-result-label`), `tool-card-args`, `tool-card-result`, `tool-card-approval` |
-| Client-side confirmation | `confirm`, `confirm-body`, `confirm-args`, `confirm-actions`, `confirm-button` (plus `confirm-confirm`, `confirm-cancel`) |
-| Server-side approval | `approval`, `approval-body`, `approval-actions`, `approval-button` (plus `approval-approve`, `approval-deny`) |
+| Client-side confirmation | `confirm`, `confirm-body`, `confirm-args`, `confirm-actions`, `confirm-button` (plus `confirm-confirm`, `confirm-cancel`, `confirm-always`) |
+| Server-side approval | `approval`, `approval-body`, `approval-actions`, `approval-button` (plus `approval-approve`, `approval-deny`), `approval-edit`, `approval-args`, `approval-error` |
 | Typed question | `question`, `question-body`, `question-options`, `question-choice`, `question-choice-text`, `question-radio`, `question-input`, `question-actions`, `question-button` |
 | Composer | `composer`, `composer-surface`, `composer-tools`, `input`, `send`, `attach-button`, `voice-button` |
 | Attachments | `attachment-tray`, `attachment-chips` (the read-only chips on sent bubbles), and the shared chip parts `attachment-chip`, `attachment-chip-icon`, `attachment-chip-name`, `attachment-chip-size`, `attachment-chip-bar`, `attachment-chip-bar-fill`, `attachment-chip-retry`, `attachment-chip-remove` |