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

package/dist/constants.d.ts

@@ -44,6 +44,66 @@ export declare const ATTACHMENT_EVENT = "ag-ui-attachments";
  * error and cancellation alike, since a partial write is still a write.
  */
 export declare const RUN_FINISHED_EVENT = "ag-ui-run-finished";
+/**
+ * The agent sent an AG-UI `CUSTOM` event. `detail` is {@link CustomAgentDetail}.
+ *
+ * `CUSTOM` is one of exactly two carriers whose payload name the protocol leaves
+ * an open string, and it is the **imperative** one: something for the host page
+ * to *do*, with no place in the transcript. Its sibling `ACTIVITY_SNAPSHOT`
+ * carries transcript **content**, which is why that one is materialised into a
+ * message, persisted, and replayed on restore while this one 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, so replaying it on a thread load would be a bug. Anything that
+ * must survive a reload belongs on the other carrier.
+ *
+ * The element takes no view of what a name means -- it forwards every one. A
+ * host that does not recognise a name ignores the event, which is the graceful
+ * outcome the open field exists for.
+ */
+export declare const CUSTOM_AGENT_EVENT = "ag-ui-custom";
+/**
+ * The agent named resources its write has moved. `detail` is
+ * {@link InvalidateDetail}.
+ *
+ * A convention on top of {@link CUSTOM_AGENT_EVENT}, not a second channel: the
+ * wire carries an ordinary AG-UI `CUSTOM` event whose `name` is
+ * {@link INVALIDATE_CUSTOM_NAME}, and this is that one name routed to its own
+ * DOM event so a host does not have to string-match. Every other name still
+ * arrives as `ag-ui-custom`.
+ *
+ * Fires **as each announcement arrives**, during the run, which is what makes a
+ * long multi-step run feel live: the list refreshes as the third of eight writes
+ * lands rather than when everything finishes. {@link RUN_FINISHED_EVENT} carries
+ * the same keys again at the end, de-duplicated, for a host that would rather
+ * refetch once.
+ */
+export declare const INVALIDATE_EVENT = "ag-ui-invalidate";
+/**
+ * Fired when the user rates an assistant message from its action row.
+ *
+ * `detail` is a {@link FeedbackDetail}: the rated message's text and the
+ * rating. **Nothing is stored** -- a rating belongs to whatever the host
+ * already uses to hold product signals, and a write-only table inside a chat
+ * widget is a schema nobody reads.
+ */
+export declare const FEEDBACK_EVENT = "ag-ui-feedback";
+/**
+ * The `activity_type` carrying server-pushed follow-up prompts.
+ *
+ * Matches django-ag-ui's `SUGGESTIONS_ACTIVITY_TYPE`. A convention inside the
+ * protocol's open `activity_type` field, not an extension of it -- so a client
+ * that has never heard of it ignores the event, and this one is not privileged.
+ */
+export declare const SUGGESTIONS_ACTIVITY_TYPE = "suggestions";
+/**
+ * The AG-UI `CUSTOM` event `name` that carries an invalidation.
+ *
+ * Matched exactly. Namespaced so it cannot collide with a host's own custom
+ * events, which share the field.
+ */
+export declare const INVALIDATE_CUSTOM_NAME = "ag_ui.invalidate";
 /** Roles a chat message can take. */
 export declare const MESSAGE_ROLE: {
     readonly USER: "user";
@@ -189,4 +249,13 @@ export declare const ICON_FILE_TEXT = "<svg class=\"glyph\" viewBox=\"0 0 24 24\
  * event, which is the graceful outcome.
  */
 export declare const CHART_ACTIVITY_TYPE = "chart";
+/**
+ * How long a screen-reader status stays in the announcer before it is emptied.
+ *
+ * Long enough for a reader to pick the change up, short enough that the region
+ * is empty again before the next status lands. Emptying is what makes an
+ * identical consecutive message announce at all -- a live region is read on
+ * *change*, and setting the same string twice is not one.
+ */
+export declare const ANNOUNCE_CLEAR_MS = 150;
 //# sourceMappingURL=constants.d.ts.map

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,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;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;aAC3B,OAAO,EAAE,SAAS;aAClB,QAAQ,EAAE,UAAU;aACpB,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;AAE9N;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/core/ag_ui_chat.d.ts

@@ -8,6 +8,7 @@ import { type PageState } from "../tools/page_state.js";
 import { type RouteMap } from "../tools/route_map.js";
 import { type ApprovalRenderer } from "../ui/approval_card.js";
 import { type QuestionRenderer } from "../ui/question_card.js";
+import type { RelativeTimeFormatter } from "../ui/relative_time.js";
 import { type ToolDisplayMode } from "../ui/tool_call_card.js";
 import { type UiStrings } from "../ui/ui_strings.js";
 import { type AttachmentRef } from "./attachment.js";
@@ -31,6 +32,12 @@ export interface AttachmentsDetail {
     readonly pending: number;
 }
 /** `detail` shape of the {@link STATE_EVENT} CustomEvent. */
+/** {@link FEEDBACK_EVENT} detail: what was rated, and how. */
+export interface FeedbackDetail {
+    /** The rated message's text, as rendered. */
+    readonly content: string;
+    readonly rating: "up" | "down";
+}
 export interface StateDetail {
     readonly state: Readonly<Record<string, unknown>>;
 }
@@ -48,6 +55,79 @@ export interface ToolRun {
 export interface RunFinishedDetail {
     /** In settle order. Empty when the interaction called no tools. */
     readonly tools: readonly ToolRun[];
+    /**
+     * Every key announced during the interaction, de-duplicated, first-seen order.
+     *
+     * **This is the field that makes adoption one line** for a host already
+     * listening here, and the `else` is the whole compatibility story:
+     *
+     * ```js
+     * if (detail.invalidated.length > 0) refetchOnly(detail.invalidated);
+     * else if (detail.tools.some((t) => t.side === "server")) refetchEverything();
+     * ```
+     *
+     * Empty against a server that announces nothing, so an old server and a new
+     * client fall through to the coarse refetch that shipped before either.
+     */
+    readonly invalidated: readonly string[];
+}
+/**
+ * Draw one activity, from its content alone.
+ *
+ * The contract is {@link ClientTool.render}'s, and for the same reason rather
+ * than by analogy. An activity is materialised into a `role: "activity"`
+ * message, persisted with the transcript, and re-fired on every restore -- so a
+ * renderer that writes to the page instead of returning DOM fires again on
+ * every thread load, which is exactly the bug the tool registry's purity rule
+ * was written to make unmakeable.
+ *
+ * - a pure function of `content` -- no host state, no network, no clock;
+ * - deterministic, so a reload reproduces what was there before;
+ * - free of effects outside the node it returns, which the component places.
+ *
+ * Return `null` for content that says nothing worth drawing. Anything already
+ * drawn under that message id is then removed: live and reload should agree,
+ * and the stored content is the version that could not be drawn.
+ */
+export type ActivityRenderer = (content: unknown) => Node | null;
+/** One `activity_type` a host can draw. See {@link AgUiChat.registerActivityRenderer}. */
+export interface ActivityRegistration {
+    /**
+     * The AG-UI `activity_type` this draws, matched exactly.
+     *
+     * An open string the protocol does not enumerate -- which is the whole reason
+     * this is a registry rather than a branch.
+     */
+    readonly type: string;
+    readonly render: ActivityRenderer;
+    /**
+     * Shown in the transcript when something already drawn under this type stops
+     * being renderable. Omit for an activity whose disappearance needs no
+     * explanation.
+     */
+    readonly removedNotice?: string;
+}
+/** `detail` shape of the {@link CUSTOM_AGENT_EVENT} CustomEvent. */
+export interface CustomAgentDetail {
+    /** The `CUSTOM` event's `name`, verbatim. An open string; never interpreted here. */
+    readonly name: string;
+    /** Its `value`, verbatim and unparsed. `unknown` because the protocol says nothing about it. */
+    readonly value: unknown;
+}
+/** `detail` shape of the {@link INVALIDATE_EVENT} CustomEvent. */
+export interface InvalidateDetail {
+    /**
+     * The resources that moved, as the server named them.
+     *
+     * **Opaque strings, and matching is exact.** `orders/42` does not imply
+     * `orders` -- a prefix rule would be this component guessing at a scheme it
+     * does not own, and `orders/1` would match `orders/11`. A server that wants
+     * the collection refreshed names it. Your own matching may be hierarchical,
+     * because in your vocabulary the scheme is known.
+     */
+    readonly keys: readonly string[];
+    /** What caused the write -- usually the tool's name. `null` when unstated. */
+    readonly reason: string | null;
 }
 /** `detail` shape of the {@link TOGGLE_EVENT} CustomEvent. */
 export interface ToggleDetail {
@@ -92,6 +172,22 @@ export declare class AgUiChat extends HTMLElement {
      * `Authorization` are configured independently and neither drops the other.
      */
     getHeaders: (() => Record<string, string>) | null;
+    /**
+     * Origins, besides the page's own, that this element may send {@link headers}
+     * and {@link getHeaders} credentials to without saying so on the console.
+     *
+     * Seven attributes name a URL, and every one of them carries these headers.
+     * They are plain HTML, so a page that builds one from a query parameter or
+     * from tenant-authored configuration has handed an attacker the destination,
+     * and the token leaves on the element's first request. Naming the origins you
+     * expect turns that from silent into either confirmed or reported.
+     *
+     * A notice rather than a refusal: a cross-origin agent is a documented
+     * deployment, so refusing would break working installations to defend against
+     * a page that is already interpolating untrusted data into its own markup.
+     * Leaving this empty costs nothing but one console line per foreign origin.
+     */
+    trustedOrigins: readonly string[];
     /**
      * Permit `<img>` in rendered assistant markdown. **Off by default**: a
      * model-controlled image URL is fetched with no user interaction, which
@@ -99,6 +195,22 @@ export declare class AgUiChat extends HTMLElement {
      * data. Enable only when the content source is trusted.
      */
     allowImages: boolean;
+    /**
+     * Replace the relative timestamps in the thread drawer and the checkpoint
+     * panel -- `"5m ago"`, `"2d ago"` -- with the host's own formatting.
+     *
+     * The built-in is locale-neutral on purpose: there is no `Intl` anywhere in
+     * this component, so it never disagrees with the page it is embedded in by
+     * guessing a locale. That is a good default and a bad requirement, which is
+     * what this is for.
+     *
+     * ```js
+     * const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });
+     * chat.formatRelativeTime = (ts) =>
+     *   rtf.format(Math.round((ts - Date.now()) / 60000), "minute");
+     * ```
+     */
+    formatRelativeTime: RelativeTimeFormatter | null;
     /** When true, destructive tools execute without a confirmation modal. */
     autoConfirm: boolean;
     /**
@@ -122,6 +234,22 @@ export declare class AgUiChat extends HTMLElement {
      * is enabled server-side; this only changes how the decision is collected.
      */
     approvalRenderer: ApprovalRenderer | null;
+    /**
+     * Let the user edit a gated call's arguments before approving it.
+     *
+     * Off by default and **an assertion about your server**, not a negotiation:
+     * AG-UI carries `editedArgs` in the resume payload and gates it on the
+     * agent's own `approveWithEdits` capability, which this component never sees
+     * -- capabilities are not on the wire it reads. So the host says whether its
+     * agent honours them. Turned on against a server that does not, the user
+     * would edit arguments it silently discards, which is worse than not
+     * offering.
+     *
+     * Only affects calls whose arguments are known here: an interrupt names a
+     * `toolCallId`, and the tool card for that call is where the arguments still
+     * are. An interrupt naming no card gets the plain approve/deny.
+     */
+    approveWithEdits: boolean;
     /**
      * Optional per-call confirmation predicate. When set it is authoritative,
      * deciding from the tool name and args whether this particular call needs
@@ -218,7 +346,18 @@ export declare class AgUiChat extends HTMLElement {
     /** Attributes the element reacts to after it has been connected. */
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, previous: string | null, value: string | null): void;
-    /** Declare a frontend tool the agent may call. */
+    /**
+     * Declare a frontend tool the agent may call.
+     *
+     * **A handler's thrown message leaves the browser.** When a handler rejects,
+     * its `Error.message` is posted back as that call's tool result — into the
+     * conversation, on to the AG-UI endpoint, persisted server-side, and
+     * forwarded to the model provider on every later round. That is deliberate,
+     * since it is what lets the agent recover from a failure it caused; but it
+     * means an internal hostname, a signed URL or a stack-derived path in a
+     * rethrown error is disclosed to parties the host never chose. Throw the
+     * message you would be content for the model to read, and log the detail.
+     */
     registerTool(tool: ClientTool): void;
     /**
      * AG-UI **shared state** for this conversation — the protocol's own state
@@ -242,6 +381,33 @@ export declare class AgUiChat extends HTMLElement {
     /** The AG-UI endpoint URL, read from the `endpoint` attribute. */
     get endpoint(): string;
     set endpoint(value: string);
+    /**
+     * Who the stored conversation belongs to, from the `user-key` attribute.
+     *
+     * Set it to whatever identifies the signed-in principal — a user id, an
+     * account id, a hash of one. The value joins the storage namespace, so two
+     * principals in the same tab cannot read each other's transcript, and
+     * **changing it purges what the previous one left behind**.
+     *
+     * That purge is the reason this is a live attribute rather than a
+     * connect-time one. `sessionStorage` survives same-tab navigation, so it
+     * survives a logout; and a single-page app signs out through its own router
+     * without remounting anything, so there is no other moment at which the
+     * element could find out. The host naming the new principal — or dropping the
+     * attribute — is the signal.
+     *
+     * Absent means exactly today's behaviour, which is why nothing breaks by
+     * leaving it off: the conversation is scoped to the element and to nobody in
+     * particular, and on a shared workstation it carries into whoever signs in
+     * next in the same tab.
+     *
+     * The first value to arrive is treated as a host naming the user who was
+     * already there, not as a handover: the conversation in progress moves into
+     * the principal's namespace rather than being destroyed, so an element
+     * configured by an async auth handshake keeps what is on screen.
+     */
+    get userKey(): string;
+    set userKey(value: string);
     /**
      * Cookie policy for **every** request this element makes, as `fetch`'s own
      * `credentials` mode (`"omit"` / `"same-origin"` / `"include"`). Mirrored to
@@ -294,6 +460,42 @@ export declare class AgUiChat extends HTMLElement {
      * indicator clears. Without this a removed element leaks all three.
      */
     disconnectedCallback(): void;
+    /**
+     * Put `text` into the composer as a markdown quotation, and focus it.
+     *
+     * Deliberately **not** a send. Quoting is how a question narrows to one part
+     * of an answer, so the quotation is the preamble and the question is what
+     * comes next -- the caret is left after it, on its own line.
+     *
+     * This is also the seam for the half of this feature the component cannot
+     * build: selection in the **host page**. A widget mounted beside a table can
+     * be asked about a row, and nothing in a chat's own transcript can offer
+     * that. A host reads its own selection, however it likes, and calls this.
+     *
+     * No-ops on text that is empty or only whitespace.
+     */
+    quote(text: string): void;
+    /**
+     * Offer to quote what the user selects in the **host page**, not just in the
+     * transcript. Returns a function that stops offering.
+     *
+     * The same select-then-offer gesture, over a table, a diff, a report -- the
+     * surface the user actually works in, which is the half of quoting no hosted
+     * chat can reach. Opt-in, because it listens on the host's document and that
+     * is theirs to grant.
+     *
+     * Deliberately **not** a four-line recipe, which is how this shipped first
+     * and was wrong: a page listener that quotes every settled selection appends
+     * to the composer on every drag made to read, to copy or to fix a typo -- and
+     * it cannot tell a selection in the page's prose from one inside the user's
+     * own half-typed `<input>`, because Chrome reports a field's internal
+     * selection as an ordinary range over the field's *wrapper*. See
+     * {@link attachQuoteOffer} for the guards.
+     *
+     * Detached automatically when the element leaves the document; a host that
+     * re-mounts it calls this again.
+     */
+    offerQuoteInPage(within?: HTMLElement): () => void;
     /**
      * Replace the host-supplied (client) skill catalog. Merged after the embedded
      * and fetched skills (so a client skill overrides a same-named server one).
@@ -360,6 +562,23 @@ export declare class AgUiChat extends HTMLElement {
      * starts something new must not be the button that destroys what was there.
      */
     newChat(): void;
+    /**
+     * Ask the same question again and replace the answer.
+     *
+     * History is truncated to the most recent user message inclusive and the run
+     * repeats, so the agent answers what it was asked rather than being told its
+     * last answer was wrong. Returns `false` when there is nothing to retry or a
+     * run is already in flight.
+     *
+     * Public because a host with its own message UI wants the same button, and
+     * because the failed-run notice reaches it from outside the action row.
+     *
+     * **A retried turn re-runs its tools**, which for a page-driving agent is not
+     * neutral: the previous attempt already clicked what it clicked, and this
+     * does not undo it. Confirmation still applies, so a destructive tool asks
+     * again -- unless the user waived it for this session.
+     */
+    retryLastTurn(): Promise<boolean>;
     /**
      * Append a message bubble and return it.
      *
@@ -419,5 +638,47 @@ export declare class AgUiChat extends HTMLElement {
      * arrives is not something to switch on for everybody.
      */
     enableCharts(routes?: readonly ("tool" | "activity")[]): void;
+    /**
+     * Teach this element to draw one kind of AG-UI activity.
+     *
+     * `activity_type` is one of exactly two fields the protocol leaves an open
+     * string, and it is the **content** one: an activity is materialised into a
+     * message, persisted with the thread, and replayed on every restore. Its
+     * sibling `CUSTOM` carries an imperative and is dispatched to the page
+     * instead ({@link CUSTOM_AGENT_EVENT}).
+     *
+     * That asymmetry decides which carrier a server should use. Content has a
+     * place in the conversation and should come back; an imperative has no place
+     * and no meaning once acted on.
+     *
+     * ```js
+     * chat.registerActivityRenderer({
+     *   type: "build_status",
+     *   render: (content) => {
+     *     const el = document.createElement("div");
+     *     el.textContent = `Build ${content.status}`;
+     *     return el;
+     *   },
+     * });
+     * ```
+     *
+     * Registering a type twice replaces the earlier renderer, so a host can
+     * override a built-in -- `chart` and `compaction` are registrations like any
+     * other, not privileged branches.
+     *
+     * ⚠ `render` runs again on every thread load. See {@link ActivityRenderer}
+     * for what that requires of it.
+     */
+    registerActivityRenderer(registration: ActivityRegistration): void;
+    /**
+     * Activity types that arrived with nobody registered to draw them.
+     *
+     * Deliberately the only trace an unhandled activity leaves. Ignoring an
+     * unknown name is the protocol's own answer and the whole point of an open
+     * field, so warning would fire on every forward-compatible server -- but
+     * "nothing happened and nothing was said" is impossible to debug, so the set
+     * is readable. Accumulates for the element's lifetime, across threads.
+     */
+    get unhandledActivityTypes(): readonly string[];
 }
 //# sourceMappingURL=ag_ui_chat.d.ts.map

package/dist/core/ag_ui_chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ag_ui_chat.d.ts","sourceRoot":"","sources":["../../src/core/ag_ui_chat.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ag_ui_chat.d.ts","sourceRoot":"","sources":["../../src/core/ag_ui_chat.ts"],"names":[],"mappings":"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"}

package/dist/core/agui_client.d.ts

@@ -87,11 +87,36 @@ export interface AgUiClientHandlers {
     onActivityChanged(messageId: string, activityType: string, content: unknown): void;
     /** Fired when a reasoning model starts emitting its chain-of-thought. */
     onReasoningStart(): void;
-    /** Fired on every reasoning token; ``buffer`` is the full reasoning text so far. */
+    /**
+     * Fired on every reasoning token, and once more when the block ends.
+     *
+     * ``buffer`` is the text accumulated *before* the token that triggered the
+     * call, which is what the protocol client passes -- so the stream trails by
+     * one delta and the final call, at the end of the block, is what completes
+     * it. Render the buffer wholesale rather than appending it.
+     */
     onReasoningDelta(buffer: string): void;
     /** Fired when the reasoning block ends (before the answer text streams). */
     onReasoningEnd(): void;
     onRunEnd(): void;
+    /**
+     * The server replaced the whole conversation with `MESSAGES_SNAPSHOT`.
+     *
+     * `@ag-ui/client` applies the event before any subscriber sees it, so by the
+     * time this fires `agent.messages` **is** the server's list -- and the run
+     * loop persists `agent.messages`. The replacement therefore reaches the
+     * conversation store whatever the host does; this hook exists so the host can
+     * stop that being invisible.
+     */
+    onMessagesSnapshot(messages: readonly Message[]): void;
+    /**
+     * The agent sent a `CUSTOM` event.
+     *
+     * Forwarded whole and uninterpreted: `name` is an open string the protocol
+     * does not enumerate, so a client that decided which names were legal would
+     * be the thing the open field exists to avoid.
+     */
+    onCustomEvent(name: string, value: unknown): void;
     onError(message: string): void;
     /**
      * Fired when the user cancelled the run ({@link AgUiClient.cancel}) — the
@@ -185,6 +210,26 @@ export declare class AgUiClient {
      * {@link messageAttachments}.
      */
     send(content: string, attachments?: readonly AttachmentRef[]): Promise<void>;
+    /**
+     * Drop everything after the most recent user message, so the same question
+     * can be asked again.
+     *
+     * Returns the retained history, or `null` when there is nothing to retry (no
+     * user message has been sent yet). **Truncates only** -- the caller re-renders
+     * from the returned list and then calls {@link resume}, because the transcript
+     * belongs to the element and a client that reached into it would own two
+     * things. Running here instead would stream the new answer in underneath the
+     * old one.
+     *
+     * Re-running answers the question the agent was last asked, rather than
+     * telling it its answer was wrong, which is what makes the result a
+     * *different* answer instead of a conversation about the previous one.
+     *
+     * **A retried turn re-runs its tools.** For a page-driving agent that is not
+     * neutral: the previous attempt already clicked what it clicked, and this
+     * does not undo it.
+     */
+    truncateToLastUser(): readonly Message[] | null;
     /**
      * Resume the run loop after a navigating tool's result was supplied
      * post-reload (via {@link addToolResult}). Unlike {@link send}, adds no user

package/dist/core/agui_client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agui_client.d.ts","sourceRoot":"","sources":["../../src/core/agui_client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agui_client.d.ts","sourceRoot":"","sources":["../../src/core/agui_client.ts"],"names":[],"mappings":"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"}

package/dist/core/conversation_store.d.ts

@@ -84,6 +84,23 @@ export interface ClientConversationStore {
      */
     isUnsent?(threadId: string): boolean;
 }
+/**
+ * `sessionStorage.setItem` that survives a store which refuses to write.
+ *
+ * `setItem` throws on an exhausted quota (a long conversation, or one turn
+ * carrying a large tool result) and in privacy modes that deny storage
+ * altogether. Every write here is a *durability* concern — surviving a reload —
+ * and none of them is worth an exception, because of where they are called
+ * from: the element persists the transcript from inside the run loop, so an
+ * unguarded throw escapes as a run error and tells the user the agent failed
+ * when nothing but the browser's storage did. On the cancel path it escapes as
+ * an unhandled rejection instead.
+ *
+ * So a failed write loses the reload, never the conversation on screen, and
+ * says so once. Recovery is in the user's hands already: deleting the oversized
+ * thread from the history drawer is a `removeItem`, which frees the quota.
+ */
+export declare function writeStoredItem(key: string, value: string): void;
 /**
  * Default {@link ClientConversationStore}: per-tab `sessionStorage`.
  *
@@ -95,11 +112,36 @@ export interface ClientConversationStore {
  * An optional `namespace` scopes every key to one element, so two
  * `<ag-ui-chat>` instances on the same origin keep separate active-thread
  * pointers and drawer indexes instead of clobbering each other. The default
- * empty namespace keeps the origin-global keys; see {@link #migrateLegacyKeys}.
+ * empty namespace keeps the origin-global keys, which a namespaced store adopts
+ * on construction; see {@link SessionStorageStore.adopt}.
  */
 export declare class SessionStorageStore implements ClientConversationStore {
     #private;
     constructor(namespace?: string);
+    /**
+     * Move every key a store owns out of `from`'s namespace and into `to`'s.
+     *
+     * Two callers, one move. The constructor adopts the pre-namespacing global
+     * keys (`from` = `""`); `<ag-ui-chat>` adopts an element-scoped conversation
+     * into a principal-scoped one the first time a `user-key` arrives, which is a
+     * host naming the user who was already there rather than a handover.
+     *
+     * Only this store's own suffixes move — the element's `collapsed` / `size` /
+     * `theme` keys share the global root and are deliberately left where they
+     * are. A value already present at the destination wins: the destination is
+     * the durable record and the source is the stray this move exists to clear.
+     */
+    static adopt(from: string, to: string): void;
+    /**
+     * Forget everything a store holds for `namespace`.
+     *
+     * The logout primitive: `<ag-ui-chat>` calls it when its `user-key` changes,
+     * and a host driving its own store can call it from its own sign-out path.
+     * Deliberately narrow — it removes only keys under this exact namespace whose
+     * suffix parses as one this store writes, so it can never reach another
+     * element's conversation or the host's own `sessionStorage` entries.
+     */
+    static purge(namespace: string): void;
     threadId(): string;
     newThread(): string;
     isUnsent(threadId: string): boolean;

package/dist/core/conversation_store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation_store.d.ts","sourceRoot":"","sources":["../../src/core/conversation_store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,QAAQ,IAAI,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,MAAM,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IACnE,8EAA8E;IAC9E,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IACnE,0EAA0E;IAC1E,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAAC;IAC9D,4EAA4E;IAC5E,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAAC;IAChF,+EAA+E;IAC/E,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,+EAA+E;IAC/E,WAAW,IAAI,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IAC9C,4EAA4E;IAC5E,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,gEAAgE;IAChE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CACtC;AAwBD;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,YAAW,uBAAuB;;IAGjE,YAAY,SAAS,SAAK,EAKzB;IAED,QAAQ,IAAI,MAAM,CAEjB;IAED,SAAS,IAAI,MAAM,CAKlB;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKlC;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC,CAEjE;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAIjE;IAED,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAE5D;IAED,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAO9E;IAED,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAW5B;IAED,WAAW,IAAI,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAK5C;IAED,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEtC;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CASlD;CAuFF"}
+{"version":3,"file":"conversation_store.d.ts","sourceRoot":"","sources":["../../src/core/conversation_store.ts"],"names":[],"mappings":"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"}

package/dist/core/create_http_agent.d.ts

@@ -30,6 +30,19 @@ export interface HttpAgentOptions {
      * server streams `STATE_SNAPSHOT` / `STATE_DELTA`.
      */
     initialState?: Readonly<Record<string, unknown>>;
+    /**
+     * Origins, besides the document's own, this agent may carry the host's
+     * credentials to.
+     *
+     * Running the agent on another subdomain is a normal deployment and stays
+     * supported, so a cross-origin endpoint is not refused — it is *announced*,
+     * once per origin, on the console. Listing an origin here says the
+     * destination was chosen deliberately and silences the notice for it.
+     *
+     * Entries are compared as serialized origins (`https://agent.example.com`,
+     * scheme and port included), which is what `URL.origin` produces.
+     */
+    trustedOrigins?: readonly string[];
 }
 /**
  * Build an AG-UI {@link HttpAgent} pointed at `endpoint`.

package/dist/core/create_http_agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_http_agent.d.ts","sourceRoot":"","sources":["../../src/core/create_http_agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CA4BxE;AAED,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,aAAa,CAAC"}
+{"version":3,"file":"create_http_agent.d.ts","sourceRoot":"","sources":["../../src/core/create_http_agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,eAAe,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAqCxE;AAED,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,aAAa,CAAC"}