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

package/README.md

@@ -50,6 +50,11 @@ 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)
@@ -177,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
@@ -561,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:
 
@@ -568,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
@@ -1009,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`
@@ -1127,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
@@ -1467,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
@@ -1643,6 +1982,18 @@ 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
@@ -1702,6 +2053,12 @@ re-export point. Internal modules import from leaf paths.
 | `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). |
@@ -1716,6 +2073,13 @@ 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. |
@@ -1855,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` |