@artooi/ag-ui-web-component 0.23.0 → 0.24.0

package/dist/constants.d.ts

@@ -1,88 +1,80 @@
 /** The Custom Element tag name registered by {@link defineAgUiChat}. */
 export declare const ELEMENT_TAG = "ag-ui-chat";
-/**
- * Event dispatched by `<ag-ui-chat>` when the user submits a message.
- * `detail` carries `{ content: string }`. Later phases wire this to the
- * AG-UI client; for now it is the public seam for host integration.
- */
+/** User submitted a message. `detail` is {@link SubmitDetail}. */
 export declare const SUBMIT_EVENT = "ag-ui-submit";
 /**
- * Event dispatched by `<ag-ui-chat>` when its collapsed state changes (via the
- * built-in toggle or {@link setCollapsed}). `detail` carries
- * `{ collapsed: boolean }`. A host can listen to drive its own chrome, or hide
- * the built-in toggle and drive the `collapsed` attribute itself.
+ * Collapsed state changed, via the built-in toggle or `setCollapsed`.
+ * `detail` is {@link ToggleDetail}.
  */
 export declare const TOGGLE_EVENT = "ag-ui-toggle";
 /**
- * Event dispatched by `<ag-ui-chat>` when the number of answers that arrived
- * while it was collapsed changes — one more finished, or expanding cleared them
- * all. `detail` carries `{ unread: number }`.
- *
- * The built-in badge on the launcher renders exactly this. A host driving its
- * own chrome can turn the badge off with `data-unread-badge="false"` and listen
- * here instead.
+ * The count of answers that arrived while collapsed changed. `detail` is
+ * {@link UnreadDetail}. The built-in launcher badge renders exactly this; a
+ * host driving its own chrome sets `data-unread-badge="false"` and listens.
  */
 export declare const UNREAD_EVENT = "ag-ui-unread";
 /**
- * Event dispatched by `<ag-ui-chat>` when AG-UI **shared state** changes — the
- * server streamed a `STATE_SNAPSHOT` / `STATE_DELTA`, or the host assigned
- * {@link AgUiChat.sharedState}. `detail` carries `{ state }`.
+ * AG-UI shared state changed — a streamed `STATE_SNAPSHOT` / `STATE_DELTA`, or
+ * a host assignment to `sharedState`. `detail` is {@link StateDetail}.
  *
- * This is the protocol's own state channel, distinct from `registerPageState`,
- * which exposes host state to the agent as ordinary *tools*.
+ * The protocol's own state channel, distinct from `registerPageState`, which
+ * exposes host state to the agent as ordinary tools.
  */
 export declare const STATE_EVENT = "ag-ui-state";
 /**
- * Event dispatched by `<ag-ui-chat>` whenever the attachment tray changes — a
- * file queued, an upload finishing or failing, a chip removed, the tray
- * cleared after a send. `detail` carries `{ attachments, pending }`:
- * the durable refs of everything that has finished uploading, and how many are
- * still in flight.
- *
- * This is the seam for a host that drives its own composer: without it the tray
- * only ever spoke to the built-in Send button, so a custom send had no way to
- * know whether a file was ready or still uploading.
+ * The attachment tray changed — a file queued, an upload finishing or failing,
+ * a chip removed, the tray cleared after a send. `detail` is
+ * {@link AttachmentsDetail}, carrying the refs that finished uploading and how
+ * many are still in flight. A host driving its own composer uses this to know
+ * whether a send would leave files behind.
  */
 export declare const ATTACHMENT_EVENT = "ag-ui-attachments";
+/**
+ * An interaction has finished, whatever ended it. `detail` is
+ * {@link RunFinishedDetail}, listing the tools that ran and which side ran them.
+ *
+ * For hosts that render data the agent can change. A server-side tool writes
+ * without the page's knowledge — nothing else the element dispatches implies
+ * "something may have moved underneath you", so a page showing that data has no
+ * reason to refetch and quietly goes stale. Shared state
+ * ({@link STATE_EVENT}) is the richer channel, but it needs the agent to emit
+ * state; this needs nothing of the agent at all.
+ *
+ * Fires once per interaction rather than once per tool round, on completion,
+ * error and cancellation alike, since a partial write is still a write.
+ */
+export declare const RUN_FINISHED_EVENT = "ag-ui-run-finished";
 /** Roles a chat message can take. */
 export declare const MESSAGE_ROLE: {
     readonly USER: "user";
     readonly ASSISTANT: "assistant";
 };
 /**
- * JSON-Schema extension key marking a tool as destructive. Mirrors the
- * `django-ag-ui` server side. When a tool's `parameters` carries
- * `{ "x-destructive": true }`, the element gates its execution behind the
- * confirmation modal (unless `autoConfirm` is set).
+ * Schema-root key marking a tool destructive: the element gates its execution
+ * behind the confirmation card unless `autoConfirm` is set. All four `x-*` keys
+ * below mirror the `django-ag-ui` server side.
  */
 export declare const X_DESTRUCTIVE_KEY = "x-destructive";
 /**
- * JSON-Schema extension key carrying a human-readable confirmation prompt for a
- * destructive tool (e.g. `"Activate this project?"`). Mirrors the `django-ag-ui`
- * server side. When present, the inline confirmation card shows this instead of
- * the generic `Run "<tool>"?`.
+ * Schema-root key holding a confirmation prompt (e.g. `"Activate this
+ * project?"`), shown instead of the generic `Run "<tool>"?`.
  */
 export declare const X_CONFIRM_KEY = "x-confirm";
 /**
- * JSON-Schema extension key carrying a short human-readable label for a tool
- * (e.g. `"Query orders"` for `query_model`). Mirrors the `django-ag-ui` server
- * side; the tool-call card shows it instead of the raw tool name when present.
+ * Schema-root key holding a short label for a tool (e.g. `"Query orders"` for
+ * `query_model`), shown on the card instead of the raw tool name.
  */
 export declare const X_SUMMARY_KEY = "x-summary";
 /**
- * JSON-Schema extension key marking a tool as navigating — its handler triggers
- * a full page reload (an MPA navigation). When a tool's `parameters` carries
- * `{ "x-navigates": true }`, the element checkpoints the call before the reload
- * and resumes the run loop once the next page mounts. Mirrors `x-destructive`.
+ * Schema-root key marking a tool as navigating — its handler triggers a full
+ * page reload. The element checkpoints the call before the reload and resumes
+ * the run loop once the next page mounts.
  */
 export declare const X_NAVIGATES_KEY = "x-navigates";
 /**
- * Name of the built-in tool that re-reads the current page.
- *
- * Registered only when a page-map provider is set. Named here because it is
- * also the documented recovery from a stale page, so the stale-page guard has
- * to exempt it — refusing the very call that would refresh the agent's view
- * would be a deadlock.
+ * The built-in tool that re-reads the current page, registered only when a
+ * page-map provider is set. Named here because the stale-page guard must exempt
+ * it: refusing the one call that would refresh the agent's view deadlocks.
  */
 export declare const READ_PAGE_TOOL = "read_page";
 /** Upper bound on frontend tool-call → re-run rounds within one send. */
@@ -109,22 +101,19 @@ export declare const ATTACHMENT_STATUS: {
 };
 /**
  * Default client-side upload size cap (10 MiB), matching django-ag-ui's
- * `ATTACHMENT_MAX_BYTES` default. Overridable per element via
- * `data-attachment-max-bytes`; the server stays authoritative.
+ * `ATTACHMENT_MAX_BYTES`. Overridable via `data-attachment-max-bytes`; the
+ * server stays authoritative.
  */
 export declare const DEFAULT_ATTACHMENT_MAX_BYTES: number;
 /**
- * How much detail a tool-call card shows. Set via the `data-tool-display`
- * attribute on `<ag-ui-chat>`; defaults to `full` (back-compatible).
+ * How much detail a tool-call card shows. Set via `data-tool-display`; the
+ * default is `full`.
  *
- * - `inline` — the lightest mode: a single status row (icon + summary) with no
- *   surrounding card chrome, the result tucked behind its own toggle. Reads as
- *   one line of the answer rather than a boxed card — pairs with the answer
- *   well (page mode).
- * - `minimal` — just the tool name + status pill. No args, no result body.
- * - `compact` — name + status, with args *and* result tucked behind a single
- *   collapsed "Details" toggle. The light default for dense UIs.
- * - `full` — args shown inline, result behind its own toggle (the original).
+ * - `inline` — one status row (icon + summary), no card chrome, result behind
+ *   its own toggle. Reads as a line of the answer rather than a boxed card.
+ * - `minimal` — tool name + status pill only. No args, no result body.
+ * - `compact` — name + status, args and result behind one "Details" toggle.
+ * - `full` — args inline, result behind its own toggle.
  */
 export declare const TOOL_DISPLAY: {
     readonly INLINE: "inline";
@@ -133,30 +122,30 @@ export declare const TOOL_DISPLAY: {
     readonly FULL: "full";
 };
 /**
- * `activityType` of the AG-UI `ACTIVITY_SNAPSHOT` event `django-ag-ui` emits
- * when a compaction capability trimmed the message history. Its `content`
- * carries `{ removed, before, after }`.
+ * `activityType` of the `ACTIVITY_SNAPSHOT` event django-ag-ui emits when a
+ * compaction capability trimmed the history. `content` carries
+ * `{ removed, before, after }`.
  */
 export declare const COMPACTION_ACTIVITY_TYPE = "compaction";
 /**
- * Pydantic-AI's built-in tool the model calls to load a *deferred* capability,
- * with `{ id }` naming it. Agent skills are deferred capabilities whose id is
- * the skill name, so a call to this tool is how "the agent picked skill X"
- * reaches the client — there is no separate event for it.
+ * Pydantic-AI's built-in tool for loading a deferred capability, with `{ id }`
+ * naming it. Agent skills are deferred capabilities keyed by skill name, so a
+ * call to this tool is the only signal that the agent picked a skill.
  *
- * Not to be confused with the host-provided {@link Skill} catalog, which is a
- * *human* affordance (a prompt the user launches from the `/`-palette).
+ * Distinct from the host-provided {@link Skill} catalog, which is a human
+ * affordance launched from the slash palette.
  */
 export declare const LOAD_CAPABILITY_TOOL = "load_capability";
 /**
  * The chrome's glyphs, as inline SVG markup.
  *
- * Static, author-written markup assigned to a `<slot>`'s fallback content, so
- * it never passes through the sanitiser — nothing here is user or server data.
- * Each icon is a 24x24 viewBox carrying the shared `glyph` class, which
- * `STYLES` sizes and paints from `currentColor`; `glyph--solid` fills instead
- * of stroking. A host that wants its own mark projects a matching
- * `slot="icon-…"` child rather than editing these.
+ * Static author-written markup assigned as a `<slot>`'s fallback content, so it
+ * never passes through the sanitiser — nothing here is user or server data, and
+ * nothing user-supplied may be interpolated into it. Each icon is a 24x24
+ * viewBox carrying the shared `glyph` class, which `STYLES` sizes and paints
+ * from `currentColor`; `glyph--solid` fills instead of stroking. A host wanting
+ * its own mark projects a matching `slot="icon-…"` child instead of editing
+ * these.
  */
 export declare const ICON_SEND = "<svg class=\"glyph\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M12 19.5V5m-6.5 6.5L12 5l6.5 6.5\"/></svg>";
 /** The Stop glyph the composer button wears while a run is in flight. */
@@ -168,13 +157,10 @@ export declare const ICON_VOICE = "<svg class=\"glyph\" viewBox=\"0 0 24 24\" ar
 /** The default launcher mark (a speech bubble), shown when the host slots none. */
 export declare const ICON_LAUNCHER = "<svg class=\"glyph\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M4 5.5A2.5 2.5 0 0 1 6.5 3h11A2.5 2.5 0 0 1 20 5.5v8a2.5 2.5 0 0 1-2.5 2.5H9l-5 4z\"/></svg>";
 /**
- * The attachment-chip type marks, one per coarse file family. Same contract as
- * the chrome's glyphs above: static author-written markup on a 24x24 viewBox
- * carrying the shared `glyph` class. A chip picks one by MIME family through
- * `iconFor`; the MIME string selects a constant and is never interpolated into
- * one, so nothing user- or server-supplied reaches the markup.
- *
- * The generic mark, for a family with nothing more specific to say.
+ * The generic attachment-chip mark, for a file family with nothing more
+ * specific to say. The chip marks share the contract of the chrome glyphs
+ * above; `iconFor` selects one by MIME family, never interpolating the MIME
+ * string into the markup.
  */
 export declare const ICON_FILE = "<svg class=\"glyph\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z\"/><path d=\"M14 3v5h5\"/></svg>";
 /** An image attachment: a framed picture with a horizon and a sun. */

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAGA,wEAAwE;AACxE,eAAO,MAAM,WAAW,eAAe,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD,qCAAqC;AACrC,eAAO,MAAM,YAAY;aACvB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,WAAW;CACd,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,cAAc,CAAC;AAE1C,yEAAyE;AACzE,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,gBAAgB;aAC3B,OAAO,EAAE,SAAS;aAClB,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,OAAO;aACd,QAAQ,EAAE,UAAU;CACZ,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;aAC5B,SAAS,EAAE,WAAW;aACtB,KAAK,EAAE,OAAO;aACd,KAAK,EAAE,OAAO;CACN,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY;aACvB,MAAM,EAAE,QAAQ;aAChB,OAAO,EAAE,SAAS;aAClB,OAAO,EAAE,SAAS;aAClB,IAAI,EAAE,MAAM;CACJ,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,yHAAiH,CAAC;AAExI,yEAAyE;AACzE,eAAO,MAAM,SAAS,qJAAqI,CAAC;AAE5J,2CAA2C;AAC3C,eAAO,MAAM,WAAW,wJAAgJ,CAAC;AAEzK,yDAAyD;AACzD,eAAO,MAAM,UAAU,0MAA8L,CAAC;AAEtN,mFAAmF;AACnF,eAAO,MAAM,aAAa,2KAAmK,CAAC;AAE9L;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,0KAAgK,CAAC;AAEvL,sEAAsE;AACtE,eAAO,MAAM,eAAe,kOAA0M,CAAC;AAEvO,sEAAsE;AACtE,eAAO,MAAM,aAAa,iQAA2O,CAAC;AAEtQ,gDAAgD;AAChD,eAAO,MAAM,cAAc,8MAAkM,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAGA,wEAAwE;AACxE,eAAO,MAAM,WAAW,eAAe,CAAC;AAExC,kEAAkE;AAClE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,qCAAqC;AACrC,eAAO,MAAM,YAAY;aACvB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,WAAW;CACd,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,cAAc,cAAc,CAAC;AAE1C,yEAAyE;AACzE,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,gBAAgB;aAC3B,OAAO,EAAE,SAAS;aAClB,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,OAAO;aACd,QAAQ,EAAE,UAAU;CACZ,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;aAC5B,SAAS,EAAE,WAAW;aACtB,KAAK,EAAE,OAAO;aACd,KAAK,EAAE,OAAO;CACN,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAE7D;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;aACvB,MAAM,EAAE,QAAQ;aAChB,OAAO,EAAE,SAAS;aAClB,OAAO,EAAE,SAAS;aAClB,IAAI,EAAE,MAAM;CACJ,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,yHAAiH,CAAC;AAExI,yEAAyE;AACzE,eAAO,MAAM,SAAS,qJAAqI,CAAC;AAE5J,2CAA2C;AAC3C,eAAO,MAAM,WAAW,wJAAgJ,CAAC;AAEzK,yDAAyD;AACzD,eAAO,MAAM,UAAU,0MAA8L,CAAC;AAEtN,mFAAmF;AACnF,eAAO,MAAM,aAAa,2KAAmK,CAAC;AAE9L;;;;;GAKG;AACH,eAAO,MAAM,SAAS,0KAAgK,CAAC;AAEvL,sEAAsE;AACtE,eAAO,MAAM,eAAe,kOAA0M,CAAC;AAEvO,sEAAsE;AACtE,eAAO,MAAM,aAAa,iQAA2O,CAAC;AAEtQ,gDAAgD;AAChD,eAAO,MAAM,cAAc,8MAAkM,CAAC"}

package/dist/core/ag_ui_chat.d.ts

@@ -34,6 +34,21 @@ export interface AttachmentsDetail {
 export interface StateDetail {
     readonly state: Readonly<Record<string, unknown>>;
 }
+/** One tool that ran during an interaction, as {@link RunFinishedDetail} lists it. */
+export interface ToolRun {
+    readonly name: string;
+    /**
+     * Where it executed. `"server"` is the one a data-rendering host cares about:
+     * a `"client"` tool ran in the host's own handler, so the host already knows
+     * whatever it did.
+     */
+    readonly side: "server" | "client";
+}
+/** `detail` shape of the {@link RUN_FINISHED_EVENT} CustomEvent. */
+export interface RunFinishedDetail {
+    /** In settle order. Empty when the interaction called no tools. */
+    readonly tools: readonly ToolRun[];
+}
 /** `detail` shape of the {@link TOGGLE_EVENT} CustomEvent. */
 export interface ToggleDetail {
     readonly collapsed: boolean;
@@ -46,42 +61,35 @@ export interface UnreadDetail {
  * `<ag-ui-chat>` — a framework-free chat sidebar Web Component over AG-UI.
  *
  * Owns the Shadow DOM shell (header, scrolling message list, input row),
- * builds an {@link AgUiClient} on first send (via the overridable
- * {@link agentFactory}), and renders streaming assistant text plus tool-call
+ * builds an {@link AgUiClient} on first send via the overridable
+ * {@link agentFactory}, and renders streaming assistant text plus tool-call
  * activity. Emits a {@link SUBMIT_EVENT} for host visibility.
  *
- * The per-run frontend tool catalog and context are supplied by
- * {@link getTools} / {@link getContext}, which later phases (the tool
- * registry, DOM driver) populate.
+ * The per-run frontend tool catalog and context come from {@link getTools} and
+ * {@link getContext}.
  */
 export declare class AgUiChat extends HTMLElement {
     #private;
     /** Agent factory; override to inject a custom or fake agent (tests). */
     agentFactory: AgentFactory;
     /**
-     * Static extra HTTP headers, sent with **every** request this element makes —
-     * the agent run, the thread index and its messages, the tool and skill
-     * catalogs, the run index, uploads and transcription.
+     * Static extra HTTP headers, sent with every request this element makes: the
+     * agent run, the thread index and its messages, the tool and skill catalogs,
+     * the run index, uploads and transcription.
      *
-     * Right for values fixed for the element's lifetime. A credential that
-     * rotates (a short-lived JWT, a re-issued CSRF token) belongs in
-     * {@link getHeaders} instead: this is read at request time, but only a
-     * re-assignment updates it, so a token captured here is pinned until the host
-     * remembers to assign again.
+     * For values fixed for the element's lifetime. A rotating credential belongs
+     * in {@link getHeaders} instead — only a re-assignment updates this, so a
+     * token captured here is pinned until the host assigns again.
      */
     headers: Record<string, string>;
     /**
-     * Live header source, consulted immediately before every request — the way to
-     * supply rotating credentials.
-     *
-     * Set it to a function and each request calls it afresh: a token refreshed by
-     * the host between two requests reaches the second one, with nothing to
-     * re-assign and nothing to keep in sync.
+     * Live header source, called afresh immediately before every request — the
+     * way to supply rotating credentials, with nothing to re-assign or keep in
+     * sync.
      *
-     * Composes with {@link headers} rather than replacing it: the two are merged
-     * per key with `getHeaders()` winning, so a static `X-Client` and a rotating
-     * `Authorization` can be configured independently and neither silently drops
-     * the other.
+     * Composes with {@link headers} rather than replacing it: merged per key with
+     * `getHeaders()` winning, so a static `X-Client` and a rotating
+     * `Authorization` are configured independently and neither drops the other.
      */
     getHeaders: (() => Record<string, string>) | null;
     /**
@@ -95,37 +103,31 @@ export declare class AgUiChat extends HTMLElement {
     autoConfirm: boolean;
     /**
      * When true, the built-in `ask_user` frontend tool is offered to the agent:
-     * calling it renders an inline question card (radio choices and/or a free-text
-     * field) and returns the user's answer. Off by default — like the other
-     * built-in tool groups (route / page-action), it is opt-in so it doesn't
-     * change the advertised catalog until a host asks for it.
+     * calling it renders an inline question card and returns the user's answer.
+     * Off by default, like the other built-in tool groups, so the advertised
+     * catalog does not change until a host asks for it.
      */
     askUser: boolean;
     /**
-     * Optional full replacement for the `ask_user` question UI. When set, calling
-     * `ask_user` invokes this instead of the built-in inline card: the host
-     * renders whatever it likes (a native modal, a framework component, …) and
-     * resolves with the answer. Unset (default) uses the built-in
-     * {@link requestQuestion} card — style that via the `strings` override and the
-     * `question*` CSS `::part()`s. Requires {@link askUser} to be enabled.
+     * Optional full replacement for the `ask_user` question UI, resolving with
+     * the answer; the same seam as {@link approvalRenderer}, styled via `strings`
+     * and the `question*` `::part()`s when left unset. Requires {@link askUser}.
      */
     askUserRenderer: QuestionRenderer | null;
     /**
-     * Optional full replacement for the server-side-tool approval UI. When set, an
-     * approval interrupt invokes this instead of the built-in inline approval
-     * card: the host renders whatever it likes and resolves `true` to approve /
-     * `false` to deny. Unset (default) uses the built-in {@link requestApproval}
-     * card — style that via the `strings` override and the `approval*` CSS
-     * `::part()`s. The gate itself is enabled server-side; this only changes how
-     * the decision is collected.
+     * Optional full replacement for the server-side-tool approval UI: an approval
+     * interrupt invokes this instead of the built-in {@link requestApproval}
+     * card, resolving `true` to approve or `false` to deny. Style the built-in
+     * card via `strings` and the `approval*` `::part()`s instead. The gate itself
+     * is enabled server-side; this only changes how the decision is collected.
      */
     approvalRenderer: ApprovalRenderer | null;
     /**
-     * Optional per-call confirmation predicate. When set, it is authoritative:
-     * given a tool name + args it decides whether *this* call needs confirmation
-     * (so one tool can be instant for some args and confirmed for others — what a
-     * static `x-destructive` flag can't express). When unset, the `x-destructive`
-     * schema flag is used. `autoConfirm` short-circuits both.
+     * Optional per-call confirmation predicate. When set it is authoritative,
+     * deciding from the tool name and args whether this particular call needs
+     * confirmation — so one tool can be instant for some args and confirmed for
+     * others, which a static `x-destructive` flag cannot express. When unset the
+     * `x-destructive` flag decides. `autoConfirm` short-circuits both.
      */
     confirmPredicate: ((toolName: string, args: Record<string, unknown>) => boolean | Promise<boolean>) | null;
     /**
@@ -139,11 +141,8 @@ export declare class AgUiChat extends HTMLElement {
      * Per-run context provider. Defaults to the compact page map, when a
      * {@link getPageMap} provider is set and {@link autoInjectPageMap} is on.
      *
-     * It used to append a one-line manifest of the message's attachments too.
-     * The server now derives that manifest from the refs riding the messages, so
-     * the client's copy only duplicated it, on exactly the turn a file was
-     * attached. Attachments still reach the agent; they reach it through the
-     * message, which is where they were already.
+     * Attachments are deliberately not restated here: the server derives its own
+     * manifest from the refs riding the messages.
      */
     getContext: () => Context[];
     /**
@@ -169,21 +168,17 @@ export declare class AgUiChat extends HTMLElement {
     conversationStore: ClientConversationStore;
     /**
      * How attached files are uploaded. `null` (default) uses the built-in
-     * multipart `POST` to `data-attachments-url`. Set a custom
-     * {@link UploadHandler} — `(file, onProgress) => Promise<AttachmentRef>` — to
-     * swap the transport (e.g. a `tus-js-client` resumable adapter or
-     * direct-to-S3 multipart) without changing the tray, the chips, or the AG-UI
-     * wire (refs are transport-agnostic). When set, the 📎 affordance appears even
-     * with no `data-attachments-url`; the handler owns its own endpoint + headers.
+     * multipart `POST` to `data-attachments-url`; a custom {@link UploadHandler}
+     * swaps the transport without changing the tray, the chips, or the AG-UI
+     * wire. When set, the 📎 affordance appears even with no
+     * `data-attachments-url`, and the handler owns its own endpoint and headers.
      */
     uploadHandler: UploadHandler | null;
     /**
      * How recorded voice clips are transcribed. `null` (default) POSTs the clip
-     * to `data-transcribe-url` (django-ag-ui's `TranscribeView`). Set a custom
-     * {@link TranscribeHandler} — `(audio: Blob) => Promise<string>` — to swap the
-     * transport (a different STT endpoint, a browser Web Speech adapter) without
-     * touching the mic button. When set, the 🎤 affordance appears even with no
-     * `data-transcribe-url`.
+     * to `data-transcribe-url`; a custom {@link TranscribeHandler} swaps the
+     * transport without touching the mic button. When set, the 🎤 affordance
+     * appears even with no `data-transcribe-url`.
      */
     transcribeHandler: TranscribeHandler | null;
     /**
@@ -199,12 +194,10 @@ export declare class AgUiChat extends HTMLElement {
      */
     skillContext: () => Record<string, unknown>;
     /**
-     * Friendly display labels for tool-call cards, keyed by tool name (e.g.
-     * `{ list_projects: "Search projects" }`). Used as a fallback when a tool has
-     * no `x-summary` in its own schema — chiefly **server-side tools** (drf-mcp,
-     * `@tool` registry), whose schema never reaches the browser (AG-UI streams
-     * only the tool-call name). Client tools should prefer `x-summary` on their
-     * schema; this map is the seam for everything else.
+     * Friendly display labels for tool-call cards, keyed by tool name. The
+     * fallback when a tool has no `x-summary` in its own schema, which chiefly
+     * means server-side tools: AG-UI streams only the tool-call name, so their
+     * schema never reaches the browser. Client tools should prefer `x-summary`.
      */
     toolSummaries: Record<string, string>;
     /**
@@ -233,21 +226,17 @@ export declare class AgUiChat extends HTMLElement {
      * when the server streams `STATE_SNAPSHOT` / `STATE_DELTA`. Assigning seeds
      * the next run; reading returns whatever the agent last applied.
      *
-     * Listen for {@link STATE_EVENT} to react to server-driven changes.
-     *
-     * Not to be confused with {@link registerPageState}, which exposes host
-     * state to the agent as ordinary *tools*.
+     * Listen for {@link STATE_EVENT} to react to server-driven changes. Distinct
+     * from {@link registerPageState}, which exposes host state as ordinary tools.
      */
     get sharedState(): Readonly<Record<string, unknown>>;
     set sharedState(state: Readonly<Record<string, unknown>>);
     /** Bind a piece of host page state to `read_<name>` / `set_<name>` tools. */
     registerPageState(binding: PageState): void;
     /**
-     * @deprecated Renamed to {@link registerPageState}. The old name read as
-     * AG-UI shared-state sync (`STATE_SNAPSHOT` / `STATE_DELTA`), which this
-     * component does not implement — these are ordinary client tools over host
-     * page state. Behaviour is unchanged; this alias will be removed in a future
-     * major.
+     * @deprecated Renamed to {@link registerPageState} — the old name read as
+     * AG-UI shared-state sync. Behaviour is unchanged; the alias will be removed
+     * in a future major.
      */
     registerStateHook(binding: PageState): void;
     /** The AG-UI endpoint URL, read from the `endpoint` attribute. */
@@ -258,19 +247,18 @@ export declare class AgUiChat extends HTMLElement {
      * `credentials` mode (`"omit"` / `"same-origin"` / `"include"`). Mirrored to
      * the `credentials` attribute, so markup embeds can set it without script.
      *
-     * `null` (the default) leaves the browser's default of `same-origin` in
-     * place. That default sends **no cookies at all** when the endpoints live on
-     * a different origin from the page — app.example.com calling
-     * api.example.com is cross-origin — and the request goes out anonymously
-     * rather than failing, so the symptom is a 401 from a server that looks
-     * correctly configured. A cookie-authenticated cross-origin deployment wants
-     * `"include"`, plus `Access-Control-Allow-Credentials: true` and a concrete
-     * (non-wildcard) `Access-Control-Allow-Origin` on the server.
+     * `null` (the default) leaves the browser's `same-origin` default in place,
+     * which sends no cookies at all to an endpoint on a different origin — and
+     * the request goes out anonymously rather than failing, so the symptom is a
+     * 401 from a server that looks correctly configured. A cookie-authenticated
+     * cross-origin deployment wants `"include"`, plus
+     * `Access-Control-Allow-Credentials: true` and a concrete, non-wildcard
+     * `Access-Control-Allow-Origin` on the server.
      *
      * Read per request, so a late assignment applies to everything after it.
-     * `"omit"` cannot be honoured by the built-in **upload** transport, which is
-     * an `XMLHttpRequest` and only has a two-state cookie switch; every other
-     * endpoint honours all three modes.
+     * `"omit"` cannot be honoured by the built-in upload transport, an
+     * `XMLHttpRequest` with only a two-state cookie switch; every other endpoint
+     * honours all three modes.
      */
     get credentials(): RequestCredentials | null;
     set credentials(value: RequestCredentials | null);
@@ -290,24 +278,20 @@ export declare class AgUiChat extends HTMLElement {
      * the backend skill catalog and the thread's history — with the transport
      * configuration as it stands now.
      *
-     * This is the answer for a host that can only configure the element after the
-     * fact (a token fetched in a passive effect, an async auth handshake): the
-     * startup requests already went out with whatever was set then, and this says
-     * "try again, properly authenticated" without removing and re-inserting the
-     * node.
+     * For a host that can only configure the element after the fact (a token
+     * fetched in a passive effect, an async auth handshake), this re-issues the
+     * startup requests authenticated, without removing and re-inserting the node.
      *
-     * A reload, not a merge — the in-flight run is cancelled and the transcript
-     * is rebuilt from the persisted history, so anything streamed since is
-     * dropped. Call it once, when configuration lands; not between turns.
+     * A reload, not a merge: the in-flight run is cancelled and the transcript is
+     * rebuilt from persisted history, so anything streamed since is dropped. Call
+     * it once, when configuration lands, not between turns.
      */
     reload(): Promise<void>;
     /**
-     * Tear down live resources when the element leaves the DOM (a removed node, a
-     * client-side route swap): cancel the in-flight run so its SSE stream closes,
-     * abort any in-flight uploads so they don't orphan server-side files, and
-     * release the mic so the browser's recording indicator clears. Without this a
-     * removed `<ag-ui-chat>` leaks a streaming request, uploads, and a live
-     * `MediaRecorder`.
+     * Tear down live resources when the element leaves the DOM: cancel the
+     * in-flight run so its stream closes, abort in-flight uploads so they do not
+     * orphan server-side files, and release the mic so the browser's recording
+     * indicator clears. Without this a removed element leaks all three.
      */
     disconnectedCallback(): void;
     /**
@@ -344,12 +328,10 @@ export declare class AgUiChat extends HTMLElement {
      * Open the thread-history drawer: the imperative route to the control that
      * renders as `::part(history-button)`.
      *
-     * A host that hides `::part(header)` to render its own title bar hides the
-     * history, new-chat and collapse buttons with it — and thread switching then
-     * has no route at all, because those controls live inside the header. Each of
-     * them has a method, so a host chrome can rebuild the set: this one,
-     * {@link openCheckpoints}, {@link newChat}, {@link toggleCollapsed} and
-     * {@link toggleTheme}.
+     * A host that hides `::part(header)` for its own title bar hides the history,
+     * new-chat and collapse buttons with it. Each has a method so that chrome can
+     * be rebuilt: this one, {@link openCheckpoints}, {@link newChat},
+     * {@link toggleCollapsed} and {@link toggleTheme}.
      */
     openThreads(): void;
     /**
@@ -368,32 +350,28 @@ export declare class AgUiChat extends HTMLElement {
     /**
      * Append a message bubble and return it.
      *
-     * Assistant content is rendered as sanitised markdown/HTML; user content
-     * stays literal text (no need to parse what the user typed, and it avoids
-     * rendering user-authored markup).
+     * Assistant content renders as sanitised markdown/HTML; user content stays
+     * literal text, which also avoids rendering user-authored markup.
      *
-     * Assistant bubbles land in the current answer group, opening one if
-     * needed; a user bubble closes the prior group and sits directly in the list
-     * (the well wraps the *assistant* turn, the user message precedes it).
+     * Assistant bubbles land in the current answer group, opening one if needed;
+     * a user bubble closes the prior group and sits directly in the list, the
+     * well wrapping only the assistant turn.
      */
     appendMessage(role: MessageRole, content: string): HTMLDivElement;
     /**
      * Send a message as if the user had typed it — renders the user bubble,
      * dispatches {@link SUBMIT_EVENT}, and starts the run.
      *
-     * The programmatic half of the composer, for a host driving its own input
-     * (a "Ask about this order" button, a command palette, a custom composer
-     * replacing the built-in one). Everything the built-in Send does happens
-     * here; Send itself now reads the composer, clears it, and calls this.
+     * The programmatic half of the composer, for a host driving its own input.
+     * Everything the built-in Send does happens here; Send reads the composer,
+     * clears it, and calls this.
      *
-     * `attachments` are durable {@link AttachmentRef}s — the shape
-     * {@link attachFile}'s upload resolves to, and the shape
-     * {@link ATTACHMENT_EVENT} reports. Pass them to attach files to the message.
+     * `attachments` are durable {@link AttachmentRef}s — what {@link attachFile}
+     * resolves to and what {@link ATTACHMENT_EVENT} reports.
      *
-     * No-ops while a run is in flight (a second concurrent run would orphan the
-     * first) and for an entirely empty message. Unlike the built-in Send, this
-     * does **not** consult the tray: what you pass is what is sent, so a host
-     * composer stays in charge of its own state.
+     * No-ops on an empty message, and while a run is in flight, since a second
+     * concurrent run would orphan the first. Unlike the built-in Send it does not
+     * consult the tray: what you pass is what is sent.
      */
     sendMessage(content: string, attachments?: readonly AttachmentRef[]): Promise<void>;
     /**
@@ -401,11 +379,11 @@ export declare class AgUiChat extends HTMLElement {
      * picker and drag-and-drop do — validation, progress chip, and all.
      *
      * Returns `false` when uploads are not configured (no `data-attachments-url`
-     * and no {@link uploadHandler}), which is the only way for a host to tell;
-     * the tray does not exist to report anything in that case.
+     * and no {@link uploadHandler}) — the only signal a host gets, since the tray
+     * does not exist to report anything then.
      *
      * Uploading is asynchronous: watch {@link ATTACHMENT_EVENT} for the resulting
-     * {@link AttachmentRef}, and pass it to {@link sendMessage} once `pending`
+     * {@link AttachmentRef} and pass it to {@link sendMessage} once `pending`
      * reaches zero.
      */
     attachFile(file: File): boolean;