@artooi/ag-ui-web-component 0.9.0 → 0.11.0

package/src/core/ag_ui_chat.ts

@@ -1,4 +1,4 @@
-import type { Context, Message, Tool } from "@ag-ui/core";
+import type { Context, Interrupt, Message, Tool } from "@ag-ui/core";
 import {
   DEFAULT_ATTACHMENT_MAX_BYTES,
   MESSAGE_ROLE,
@@ -20,10 +20,20 @@ import { createPageMapContext, type PageMap } from "../tools/page_map.js";
 import { parseToolCatalog } from "../tools/parse_tool_catalog.js";
 import { createRouteTools, type RouteMap } from "../tools/route_map.js";
 import { createStateHookTools, type StateHook } from "../tools/state_hook.js";
+import {
+  type ApprovalRenderer,
+  type ApprovalRequest,
+  requestApproval,
+} from "../ui/approval_card.js";
 import { renderAttachmentChips } from "../ui/attachment_chips.js";
 import { AttachmentTray } from "../ui/attachment_tray.js";
 import { type ConfirmationRequest, requestConfirmation } from "../ui/confirmation_card.js";
 import { prettifyToolName } from "../ui/prettify_tool_name.js";
+import {
+  type QuestionRenderer,
+  type QuestionRequest,
+  requestQuestion,
+} from "../ui/question_card.js";
 import { renderMarkdown } from "../ui/render_markdown.js";
 import { wrapWords } from "../ui/reveal_words.js";
 import { SkillsMenu } from "../ui/skills_menu.js";
@@ -37,6 +47,7 @@ import {
   AgUiClient,
   type AgUiClientHandlers,
   type AgUiToolCall,
+  type InterruptResponse,
   type ToolExecution,
 } from "./agui_client.js";
 import { type AttachmentRef, messageAttachments } from "./attachment.js";
@@ -68,7 +79,7 @@ export interface ToggleDetail {
 /** Per-tab persistence key for the collapsed state (survives MPA reloads). */
 const COLLAPSED_KEY = "ag-ui-chat:collapsed";
 
-/** Per-tab persistence key for the built-in theme toggle (THEME-1). */
+/** Per-tab persistence key for the built-in theme toggle. */
 const THEME_KEY = "ag-ui-chat:theme";
 
 /**
@@ -101,6 +112,36 @@ export class AgUiChat extends HTMLElement {
   /** When true, destructive tools execute without a confirmation modal. */
   autoConfirm = false;
 
+  /**
+   * 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.
+   */
+  askUser = false;
+
+  /**
+   * 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.
+   */
+  askUserRenderer: QuestionRenderer | null = 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.
+   */
+  approvalRenderer: ApprovalRenderer | null = null;
+
   /**
    * Optional per-call confirmation predicate. When set, it is authoritative:
    * given a tool name + args it decides whether *this* call needs confirmation
@@ -259,7 +300,7 @@ export class AgUiChat extends HTMLElement {
   readonly #attachButton: HTMLButtonElement;
   readonly #fileInput: HTMLInputElement;
   readonly #attachSlot: HTMLDivElement;
-  /** Optional built-in header theme toggle (THEME-1); shown only with `data-theme-toggle`. */
+  /** Optional built-in header theme toggle; shown only with `data-theme-toggle`. */
   readonly #themeToggle: HTMLButtonElement;
   /** The collapsed-sidebar rail (an expand affordance; shown only for `placement="sidebar"`). */
   readonly #rail: HTMLButtonElement;
@@ -288,18 +329,25 @@ export class AgUiChat extends HTMLElement {
   // it; ≤1 ⇒ it arrived at once and the word reveal is appropriate.
   #streamDeltas = 0;
   #pending: HTMLDivElement | null = null;
-  // The current assistant turn's grouping container (WELL-1). One `.answer`
+  // The current assistant turn's grouping container. One `.answer`
   // wraps everything a single answer produces — streamed text, tool cards, the
   // pending indicator — so it can be boxed as one "well" by CSS. Opened on the
   // turn's first run start, closed at settle, so it spans the whole multi-round
   // frontend-tool loop (which is several AG-UI runs), not one run. `null`
   // between turns; user bubbles never enter it.
   #currentGroup: HTMLDivElement | null = null;
-  // The current turn's streamed-reasoning region (THINK-1), shown at the top of
+  // The current turn's streamed-reasoning region, shown at the top of
   // the answer group while a reasoning model thinks and collapsed once the
   // answer's first text token arrives. `null` outside a reasoning turn.
   #thoughts: ThoughtsBlock | null = null;
   #threadId = "";
+  // Per-instance suffix for the origin-scoped storage keys (collapsed / theme /
+  // active thread), so two instances on one origin don't clobber each other.
+  // Empty ⇒ the pre-namespacing global keys (back-compat). Resolved on connect.
+  #storageNs = "";
+  // Bumped on every #rehydrate; a replay whose generation is stale (a newer
+  // thread switch started while it awaited a slow store) drops its result.
+  #rehydrateGeneration = 0;
   #initialMessages: readonly Message[] = [];
   // Skill catalog by source; merged backend → embed → client (later wins).
   #backendSkills: readonly Skill[] = [];
@@ -423,9 +471,84 @@ export class AgUiChat extends HTMLElement {
     return createPageActionTools(enabled, (target) => this.resolvePageTarget(target));
   }
 
-  /** All built-in (route + page + page-action) frontend tools. */
+  /** All built-in (route + page + page-action + ask_user) frontend tools. */
   #builtinTools(): ClientTool[] {
-    return [...this.#routeTools(), ...this.#pageTools(), ...this.#pageActionTools()];
+    return [
+      ...this.#routeTools(),
+      ...this.#pageTools(),
+      ...this.#pageActionTools(),
+      ...this.#askUserTool(),
+    ];
+  }
+
+  /**
+   * The built-in `ask_user` frontend tool, or `[]` when {@link askUser} is off.
+   *
+   * A generic "ask the user a typed question" primitive: the agent calls it, the
+   * client executes it locally via the normal frontend-tool path (rendering a
+   * {@link requestQuestion} card), and the chosen/typed answer flows back as the
+   * tool result — no new protocol, reusing the machinery already in place.
+   */
+  #askUserTool(): ClientTool[] {
+    if (!this.askUser) {
+      return [];
+    }
+    return [
+      {
+        name: "ask_user",
+        description:
+          "Ask the user a question and wait for their answer. Provide `options` for a " +
+          "multiple-choice prompt; set `allow_custom` to also accept a free-text answer.",
+        parameters: {
+          type: "object",
+          properties: {
+            question: { type: "string", description: "The question to ask the user." },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: "Preset choices offered as radio buttons.",
+            },
+            allow_custom: {
+              type: "boolean",
+              description: "Allow a free-text answer in addition to any options.",
+            },
+          },
+          required: ["question"],
+        },
+        handler: (args) => this.#askUser(args),
+      },
+    ];
+  }
+
+  /** Render the `ask_user` question card and resolve with the user's answer. */
+  async #askUser(args: Record<string, unknown>): Promise<string> {
+    const question = typeof args["question"] === "string" ? args["question"] : "";
+    const request: QuestionRequest = { question };
+    const rawOptions = args["options"];
+    if (Array.isArray(rawOptions)) {
+      request.options = rawOptions.filter((option): option is string => typeof option === "string");
+    }
+    if (args["allow_custom"] === true) {
+      request.allowCustom = true;
+    }
+    // The run is suspended on the card; a Stop aborts the controller, resolving
+    // it with an empty answer (the run is then cancelled).
+    this.#confirmAbort = new AbortController();
+    const signal = this.#confirmAbort.signal;
+    this.#hidePending();
+    // A host-supplied renderer takes full control of the UI; otherwise the
+    // built-in inline card renders into the current answer group.
+    const answer =
+      this.askUserRenderer !== null
+        ? await this.askUserRenderer(request, { signal })
+        : await requestQuestion(this.#ensureGroup(), request, {
+            signal,
+            strings: this.#strings,
+          });
+    this.#confirmAbort = null;
+    this.#updateEmptyState();
+    this.#messages.scrollTop = this.#messages.scrollHeight;
+    return answer;
   }
 
   /** Resolve a tool by name: built-in tools first, then the registry. */
@@ -470,25 +593,34 @@ export class AgUiChat extends HTMLElement {
   }
 
   connectedCallback(): void {
+    // Resolve the per-instance storage namespace (id, else endpoint) before any
+    // key read/write, so this instance doesn't share collapsed/theme/thread
+    // state with another on the same origin.
+    this.#storageNs = this.id !== "" ? this.id : this.endpoint;
     // Resolve the string table before rendering any chrome (defaults are the
     // floor; `data-strings` then the `strings` property layer over them).
     this.#strings = mergeUiStrings({ ...this.#readStringOverrides(), ...this.strings });
     // Restore a theme the built-in toggle persisted last visit (opt-in only, so
     // it never overrides a host that drives `theme` itself).
     if (this.getAttribute("data-theme-toggle") !== null) {
-      const saved = sessionStorage.getItem(THEME_KEY);
+      const saved = this.#readScopedItem(THEME_KEY);
       if (saved !== null) {
         this.setAttribute("theme", saved);
       }
     }
     this.#render();
     this.#drawer.setStrings(this.#strings);
-    if (sessionStorage.getItem(COLLAPSED_KEY) === "1") {
+    if (this.#readScopedItem(COLLAPSED_KEY) === "1") {
       this.setAttribute("collapsed", "");
     }
     this.#syncRail();
     this.#initSkills();
     void this.#fetchToolCatalog();
+    // Namespace the built-in default store too (a host-injected store is used
+    // verbatim). Must precede #wireThreadStore, which wraps the current store.
+    if (this.#storageNs !== "" && this.conversationStore instanceof SessionStorageStore) {
+      this.conversationStore = new SessionStorageStore(this.#storageNs);
+    }
     this.#wireThreadStore();
     this.#wireAttachments();
     this.#wireVoice();
@@ -496,6 +628,20 @@ export class AgUiChat extends HTMLElement {
     void this.#rehydrate();
   }
 
+  /**
+   * 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`.
+   */
+  disconnectedCallback(): void {
+    this.#cancelRun();
+    this.#attachTray?.dispose();
+    this.#voice?.dispose();
+  }
+
   /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
   #readStringOverrides(): Partial<UiStrings> {
     const raw = this.getAttribute("data-strings");
@@ -544,7 +690,10 @@ export class AgUiChat extends HTMLElement {
     if (url === null) {
       return null;
     }
-    return (file, onProgress) => uploadAttachment(file, { url, headers: this.headers, onProgress });
+    // Forward the tray's abort signal so removing a chip (or tearing the
+    // element down) cancels the XHR.
+    return (file, onProgress, signal) =>
+      uploadAttachment(file, { url, headers: this.headers, onProgress, signal });
   }
 
   /**
@@ -770,7 +919,7 @@ export class AgUiChat extends HTMLElement {
     } else {
       this.removeAttribute("collapsed");
     }
-    sessionStorage.setItem(COLLAPSED_KEY, collapsed ? "1" : "0");
+    sessionStorage.setItem(this.#storageKey(COLLAPSED_KEY), collapsed ? "1" : "0");
     this.#syncRail();
     this.dispatchEvent(
       new CustomEvent<ToggleDetail>(TOGGLE_EVENT, {
@@ -795,10 +944,28 @@ export class AgUiChat extends HTMLElement {
   toggleTheme(): void {
     const next = this.getAttribute("theme") === "dark" ? "light" : "dark";
     this.setAttribute("theme", next);
-    sessionStorage.setItem(THEME_KEY, next);
+    sessionStorage.setItem(this.#storageKey(THEME_KEY), next);
     this.#syncThemeGlyph();
   }
 
+  /** This instance's namespaced form of an origin-scoped storage key. */
+  #storageKey(base: string): string {
+    return this.#storageNs === "" ? base : `${base}:${this.#storageNs}`;
+  }
+
+  /**
+   * Read a namespaced origin-scoped value, falling back once to the legacy
+   * pre-namespacing global key (left in place) so an existing collapsed/theme
+   * preference survives the upgrade.
+   */
+  #readScopedItem(base: string): string | null {
+    const scoped = sessionStorage.getItem(this.#storageKey(base));
+    if (scoped !== null || this.#storageNs === "") {
+      return scoped;
+    }
+    return sessionStorage.getItem(base);
+  }
+
   /** Reflect the current theme on the toggle: show the destination's glyph. */
   #syncThemeGlyph(): void {
     const dark = this.getAttribute("theme") === "dark";
@@ -875,7 +1042,16 @@ export class AgUiChat extends HTMLElement {
    * result from the page we landed on.
    */
   async #rehydrate(): Promise<void> {
+    // Guard against a thread-switch race: with a slow remote store, picking
+    // thread B then C would interleave both replays into one transcript. Each
+    // rehydrate claims a generation before awaiting and bails if a newer one
+    // started meanwhile (its `#resetState` already cleared the transcript).
+    this.#rehydrateGeneration += 1;
+    const generation = this.#rehydrateGeneration;
     const messages = await this.conversationStore.loadMessages(this.#threadId);
+    if (generation !== this.#rehydrateGeneration) {
+      return;
+    }
     if (messages !== null) {
       this.#initialMessages = messages;
       for (const message of messages) {
@@ -973,7 +1149,7 @@ export class AgUiChat extends HTMLElement {
    * stays literal text (no need to parse what the user typed, and it avoids
    * rendering user-authored markup).
    *
-   * Assistant bubbles land in the current answer group (WELL-1), opening one if
+   * 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).
    */
@@ -1060,7 +1236,7 @@ export class AgUiChat extends HTMLElement {
     collapse.addEventListener("click", () => this.toggleCollapsed());
 
     controls.append(history, newChat);
-    // Optional built-in theme toggle (THEME-1): off unless the host opts in, so
+    // Optional built-in theme toggle: off unless the host opts in, so
     // it never competes with a host-supplied switch in `slot="header-actions"`.
     if (this.getAttribute("data-theme-toggle") !== null) {
       this.#themeToggle.type = "button";
@@ -1120,6 +1296,7 @@ export class AgUiChat extends HTMLElement {
     });
 
     this.#skillHint.className = "skill-hint";
+    this.#skillHint.setAttribute("part", "skill-hint");
     this.#skillHint.hidden = true;
 
     // File-upload affordance: a 📎 button (hidden until `data-attachments-url`
@@ -1269,6 +1446,14 @@ export class AgUiChat extends HTMLElement {
   }
 
   async #submit(): Promise<void> {
+    // Ignore a submit while a run is in flight — the single choke point for
+    // both Enter and the Send button. The button already turns into Stop, but
+    // Enter has no such guard; without this it would start a second concurrent
+    // SSE run that orphans the first (unabortable) and lets the second run's
+    // settle sweep corrupt the first's still-pending tool cards.
+    if (this.#running) {
+      return;
+    }
     const content = this.#input.value.trim();
     const attachments = this.#attachTray?.readyRefs() ?? [];
     // Allow an attachments-only message (no typed text), but nothing empty.
@@ -1320,6 +1505,7 @@ export class AgUiChat extends HTMLElement {
         getTools: () => this.getTools(),
         getContext: () => this.getContext(),
         executeTool: (call) => this.#executeTool(call),
+        resolveInterrupts: (interrupts) => this.#resolveInterrupts(interrupts),
         onPersist: (messages) => this.conversationStore.saveMessages(this.#threadId, messages),
         connectionLostMessage: this.#strings.connectionLost,
       });
@@ -1410,6 +1596,57 @@ export class AgUiChat extends HTMLElement {
     }
   }
 
+  /**
+   * Render an approval card per server-side-tool interrupt and collect the
+   * user's decisions (approve → run it, deny → decline it).
+   *
+   * The run is suspended on these cards; a Stop while any is open aborts the
+   * shared {@link #confirmAbort} controller, resolving every still-open card as
+   * denied (and the client loop then sees the cancellation and stops). An
+   * approved tool runs on the follow-up (resume) run and streams its result
+   * back into the same pending card; a denied one is settled here, since no
+   * result will ever arrive for it.
+   */
+  async #resolveInterrupts(
+    interrupts: readonly Interrupt[],
+  ): Promise<Record<string, InterruptResponse>> {
+    const responses: Record<string, InterruptResponse> = {};
+    // One controller covers the whole batch: a single Stop denies all of them.
+    this.#confirmAbort = new AbortController();
+    this.#hidePending();
+    for (const interrupt of interrupts) {
+      const request: ApprovalRequest = {};
+      if (interrupt.message !== undefined) {
+        request.message = interrupt.message;
+      }
+      const card =
+        interrupt.toolCallId !== undefined ? this.#toolCards.get(interrupt.toolCallId) : undefined;
+      const toolName = card?.element.getAttribute("data-tool-name");
+      if (toolName !== null && toolName !== undefined) {
+        request.toolName = toolName;
+      }
+      const signal = this.#confirmAbort.signal;
+      // A host-supplied renderer takes full control of the approval UI;
+      // otherwise the built-in inline card renders into the current answer group.
+      const approved =
+        this.approvalRenderer !== null
+          ? await this.approvalRenderer(request, { signal })
+          : await requestApproval(this.#ensureGroup(), request, { signal, strings: this.#strings });
+      this.#updateEmptyState();
+      this.#messages.scrollTop = this.#messages.scrollHeight;
+      if (approved) {
+        responses[interrupt.id] = { status: "resolved", payload: { approved: true } };
+      } else {
+        responses[interrupt.id] = { status: "cancelled" };
+        // No TOOL_CALL_RESULT will stream for a denied tool — settle its pending
+        // card now rather than leaving it hanging until the onSettled sweep.
+        card?.settle(TOOL_CALL_STATUS.DECLINED, this.#strings.declinedAction);
+      }
+    }
+    this.#confirmAbort = null;
+    return responses;
+  }
+
   #handlers(): AgUiClientHandlers {
     return {
       onRunStart: () => {

package/src/core/agui_client.ts

@@ -1,5 +1,11 @@
-import { type AbstractAgent, type AgentSubscriber, randomUUID } from "@ag-ui/client";
-import type { Context, Message, Tool } from "@ag-ui/core";
+import {
+  type AbstractAgent,
+  type AgentSubscriber,
+  buildResumeArray,
+  type RunAgentParameters,
+  randomUUID,
+} from "@ag-ui/client";
+import type { Context, Interrupt, Message, ResumeEntry, Tool } from "@ag-ui/core";
 import { MAX_TOOL_ROUNDS } from "../constants.js";
 import type { AttachmentRef } from "./attachment.js";
 
@@ -33,6 +39,27 @@ export interface ToolExecution {
  */
 export type ExecuteTool = (call: AgUiToolCall) => Promise<ToolExecution | null>;
 
+/**
+ * One user decision for a server-side-tool approval interrupt. Structurally
+ * matches `@ag-ui/client`'s (non-exported) `ResumeResponse`, the payload
+ * {@link buildResumeArray} turns into a `ResumeEntry`: `resolved` approves (with
+ * an optional `payload`, e.g. `{ approved: true }`), `cancelled` denies.
+ */
+export type InterruptResponse = { status: "resolved"; payload?: unknown } | { status: "cancelled" };
+
+/**
+ * Resolves the approval interrupts a run finished on, keyed by interrupt id.
+ *
+ * When a gated **server-side** tool defers instead of executing, the run
+ * finishes on an AG-UI interrupt outcome; the host renders an approval card per
+ * interrupt and returns each decision here, and the loop resumes the run with
+ * the answers. Omit for agents that never gate server-side tools — an
+ * unresolved interrupt then simply ends the loop.
+ */
+export type ResolveInterrupts = (
+  interrupts: readonly Interrupt[],
+) => Promise<Record<string, InterruptResponse>>;
+
 /**
  * Callbacks the {@link AgUiClient} invokes as a run progresses. The host
  * (the `<ag-ui-chat>` element) implements these to render streaming text and
@@ -93,6 +120,11 @@ export interface AgUiClientConfig extends AgUiRunInputs {
   handlers: AgUiClientHandlers;
   /** Executes frontend tool calls. Omit for server-only tool sets. */
   executeTool?: ExecuteTool;
+  /**
+   * Resolves server-side-tool approval interrupts. Omit when no server-side
+   * tool is gated for approval — an interrupt then ends the loop unanswered.
+   */
+  resolveInterrupts?: ResolveInterrupts;
   /**
    * Invoked with the latest history whenever it changes, so the host can
    * persist it for durability across page reloads. Omit to keep the
@@ -134,6 +166,7 @@ export class AgUiClient {
   readonly #getTools: () => Tool[];
   readonly #getContext: () => Context[];
   readonly #executeTool: ExecuteTool | null;
+  readonly #resolveInterrupts: ResolveInterrupts | null;
   readonly #onPersist: (messages: readonly Message[]) => void;
   readonly #connectionLostMessage: string;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
@@ -146,6 +179,7 @@ export class AgUiClient {
     this.#getTools = config.getTools ?? (() => []);
     this.#getContext = config.getContext ?? (() => []);
     this.#executeTool = config.executeTool ?? null;
+    this.#resolveInterrupts = config.resolveInterrupts ?? null;
     this.#onPersist = config.onPersist ?? (() => {});
     this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
   }
@@ -241,6 +275,11 @@ export class AgUiClient {
   }
 
   async #runLoop(): Promise<void> {
+    // Carries the resolved approval answers into the *next* run when a round
+    // finished on a server-side-tool interrupt. Distinct from the public
+    // resume() navigation-reload path (which continues an unfinished
+    // frontend-tool round after a page load) — this stays inside one #run().
+    let resume: ResumeEntry[] | undefined;
     for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
       // A cancel during the previous round's frontend-tool execution lands
       // here: the running handler completed, but no further round starts.
@@ -248,11 +287,16 @@ export class AgUiClient {
         return;
       }
       const pending: AgUiToolCall[] = [];
-      const runState = { terminal: false };
-      await this.#agent.runAgent(
-        { tools: this.#getTools(), context: this.#getContext() },
-        this.#buildSubscriber(pending, runState),
-      );
+      const runState: RunState = { terminal: false, errored: false, interrupts: [] };
+      const params: RunAgentParameters = {
+        tools: this.#getTools(),
+        context: this.#getContext(),
+      };
+      if (resume !== undefined) {
+        params.resume = resume;
+      }
+      await this.#agent.runAgent(params, this.#buildSubscriber(pending, runState));
+      resume = undefined;
       this.#onPersist(this.#agent.messages);
       // Cancelled mid-stream: the user said stop — don't execute the tool
       // calls collected before the abort.
@@ -265,6 +309,29 @@ export class AgUiClient {
       if (!runState.terminal) {
         throw new ConnectionLostError(this.#connectionLostMessage);
       }
+      // RUN_ERROR is terminal: the agent already reported the failure via
+      // onError. Don't execute the tool calls collected before it or start
+      // another round — that would run into a broken context and surface a
+      // confusing second error. Any pending tool card is swept at onSettled.
+      if (runState.errored) {
+        return;
+      }
+      // A gated server-side tool deferred instead of executing: the run finished
+      // on an interrupt outcome. Ask the host to resolve each interrupt, then
+      // re-enter the loop carrying the answers — the follow-up run runs or denies
+      // the tool (its result streams back as TOOL_CALL_RESULT). Takes precedence
+      // over the frontend-tool sweep below: a server-side tool isn't ours to run.
+      if (runState.interrupts.length > 0) {
+        if (this.#resolveInterrupts === null) {
+          return;
+        }
+        const responses = await this.#resolveInterrupts(runState.interrupts);
+        if (this.#cancelled) {
+          return;
+        }
+        resume = buildResumeArray(runState.interrupts, responses);
+        continue;
+      }
       if (this.#executeTool === null || pending.length === 0) {
         return;
       }
@@ -294,7 +361,7 @@ export class AgUiClient {
     }
   }
 
-  #buildSubscriber(pending: AgUiToolCall[], runState: { terminal: boolean }): AgentSubscriber {
+  #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
     return {
       onRunInitialized() {
@@ -318,7 +385,7 @@ export class AgUiClient {
       onToolCallResultEvent({ event }) {
         h.onToolResult(event.toolCallId, event.content);
       },
-      // Reasoning (THINK-1). `@ag-ui/client` already maps the deprecated
+      // Reasoning. `@ag-ui/client` already maps the deprecated
       // THINKING_* events onto these REASONING_* callbacks, so handling the
       // reasoning family alone covers both protocol versions.
       onReasoningStartEvent() {
@@ -330,8 +397,19 @@ export class AgUiClient {
       onReasoningEndEvent() {
         h.onReasoningEnd();
       },
+      onRunFinishedEvent(params) {
+        // RUN_FINISHED is terminal for both a normal finish and an interrupt.
+        // Capturing the interrupts here (rather than reading the agent's
+        // `pendingInterrupts` field afterwards) keeps the loop self-contained
+        // and independent of that field's cross-run clearing semantics.
+        runState.terminal = true;
+        if (params.outcome === "interrupt") {
+          runState.interrupts = params.interrupts;
+        }
+      },
       onRunErrorEvent({ event }) {
         runState.terminal = true;
+        runState.errored = true;
         h.onError(event.message);
       },
       onRunFinalized() {
@@ -342,6 +420,14 @@ export class AgUiClient {
   }
 }
 
+/** Per-run mutable flags the subscriber writes and {@link AgUiClient} reads. */
+interface RunState {
+  terminal: boolean;
+  errored: boolean;
+  /** Approval interrupts a run finished on (empty for a normal finish). */
+  interrupts: Interrupt[];
+}
+
 /**
  * Whether a rejection came from aborting the run's fetch. Belt-and-suspenders
  * with the `#cancelled` flag: some `@ag-ui/client` versions re-throw the

package/src/core/attachment.ts

@@ -32,8 +32,28 @@ export interface AttachmentRef {
  * restored conversation re-renders its attachment chips. The server's strict
  * `RunAgentInput` validation ignores the unknown field — the model learns the
  * ids from the run context manifest instead.
+ *
+ * The persisted array is untrusted (it can be hand-edited, truncated, or
+ * corrupted in storage), so every entry is validated and malformed ones are
+ * dropped — a `null` or shapeless entry would otherwise throw in `iconFor` and
+ * abort the whole history replay.
  */
 export function messageAttachments(message: Message): readonly AttachmentRef[] {
   const refs = (message as { attachments?: unknown }).attachments;
-  return Array.isArray(refs) ? (refs as readonly AttachmentRef[]) : [];
+  return Array.isArray(refs) ? refs.filter(isAttachmentRef) : [];
+}
+
+/** Whether an unknown value is a structurally valid {@link AttachmentRef}. */
+function isAttachmentRef(value: unknown): value is AttachmentRef {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const ref = value as Record<string, unknown>;
+  return (
+    typeof ref["id"] === "string" &&
+    typeof ref["name"] === "string" &&
+    typeof ref["mime"] === "string" &&
+    typeof ref["size"] === "number" &&
+    (ref["url"] === undefined || typeof ref["url"] === "string")
+  );
 }