@artooi/ag-ui-web-component 0.39.0 → 0.41.0

package/src/core/agui_client.ts

@@ -5,7 +5,14 @@ import {
   type RunAgentParameters,
   randomUUID,
 } from "@ag-ui/client";
-import type { Context, Interrupt, Message, ResumeEntry, Tool } from "@ag-ui/core";
+import {
+  type Context,
+  contentToText,
+  type Interrupt,
+  type Message,
+  type ResumeEntry,
+  type Tool,
+} from "@ag-ui/core";
 import { MAX_TOOL_ROUNDS, TOOL_OUTCOME } from "../constants.js";
 import type { AttachmentRef } from "./attachment.js";
 import type { ToolOutcome } from "./tool_outcome.js";
@@ -91,11 +98,17 @@ export interface AgUiClientHandlers {
    * `TOOL_CALL_RESULT`). Frontend tools don't emit this — the client supplies
    * their result itself — so this is the channel for server-executed output.
    *
-   * `outcome` is the event's optional `outcome` field, forwarded raw. It is
-   * `unknown` rather than {@link ToolOutcome} because it comes off a
-   * `passthrough` zod schema: the protocol does not validate it, so neither can
-   * this signature honestly claim to. Read it with `toolStatusFromOutcome`,
-   * which treats `undefined` and anything unrecognised as a success.
+   * `outcome` is the `outcome` key of the event's `metadata`, forwarded raw.
+   * It is `unknown` rather than {@link ToolOutcome} because metadata is open by
+   * key: the protocol declares the object and validates nothing inside it, so
+   * neither can this signature honestly claim to. Read it with
+   * `toolStatusFromOutcome`, which treats `undefined` and anything unrecognised
+   * as a success.
+   *
+   * Only the metadata is read. A server written against `@ag-ui/client` 0.x
+   * states the outcome at the top level of the event, and 1.0 strips that key
+   * before any subscriber runs, so from such a server this is `undefined` and
+   * the card settles as done.
    *
    * Added as a third parameter rather than as a new callback, so an
    * implementation written against the two-parameter form still satisfies this
@@ -300,29 +313,6 @@ export class AgUiClient {
    * set would miss entirely.
    */
   readonly #closedMessageIds = new Set<string>();
-  /**
-   * How each tool call ended, keyed by call id, for the transcript this client
-   * persists.
-   *
-   * A side table rather than a field written onto the message, because neither
-   * producer of a tool message will carry it. `@ag-ui/client` builds the
-   * server-side one by destructuring five named fields off the event, so an
-   * `outcome` beside them is dropped before the message exists; and writing it
-   * back onto that message afterwards would put it in `agent.messages`, which is
-   * what the *next* request sends to the server. This keeps the annotation on
-   * the copy handed to the store and off the wire.
-   *
-   * Per client, not per run: `saveMessages` rewrites the whole transcript on
-   * every persist, so an outcome recorded in round one has to still be here in
-   * round five or the earlier card silently reverts to a green one. Bounded by
-   * the number of tool calls in the conversation, which the transcript beside it
-   * already is.
-   *
-   * Values are `unknown` because a restored seed fills it too (see
-   * {@link #adoptSeededOutcomes}), and a store is not trusted to hold only the
-   * words this class writes: whatever it held is written back as it was.
-   */
-  readonly #outcomes = new Map<string, unknown>();
   readonly #connectionLostMessage: string;
   readonly #unfinishedMessage: string;
   readonly #declinedMessage: string;
@@ -350,7 +340,7 @@ export class AgUiClient {
     // the agent zero times, which would look exactly like a broken endpoint.
     const rounds = config.maxToolRounds ?? MAX_TOOL_ROUNDS;
     this.#maxToolRounds = rounds >= 1 ? Math.floor(rounds) : MAX_TOOL_ROUNDS;
-    this.#adoptSeededOutcomes();
+    this.#moveSeededKeysIntoMetadata();
     const onStateChanged = config.onStateChanged;
     if (onStateChanged !== undefined) {
       // The agent applies STATE_SNAPSHOT / STATE_DELTA itself; subscribing is
@@ -392,18 +382,24 @@ export class AgUiClient {
    * tools (bounded by {@link AgUiClientConfig.maxToolRounds}, which defaults to
    * {@link MAX_TOOL_ROUNDS}).
    *
-   * `attachments` ride on the user message as a non-standard field so the
-   * default store round-trips them for history replay; see
+   * `attachments` ride in the user message's `metadata`, under
+   * `attachments`, which is how the server learns which files the agent can
+   * read and how the default store round-trips them for history replay; see
    * {@link messageAttachments}.
    */
   async send(content: string, attachments: readonly AttachmentRef[] = []): Promise<void> {
-    // Cast at the AG-UI boundary: `attachments` is a web-component augmentation
-    // the strict `Message` union doesn't declare, but `addMessage` /
-    // `structuredClone` preserve it verbatim.
-    const message = { id: randomUUID(), role: "user", content } as Message;
-    if (attachments.length > 0) {
-      (message as { attachments?: readonly AttachmentRef[] }).attachments = attachments;
-    }
+    // In `metadata` because it is the one field on a message `@ag-ui/client`
+    // declares open by key. 1.0 strips every undeclared key from the input it
+    // sends, so refs at the top level of the message -- where every release
+    // before 1.0 put them -- are removed with a console warning and the server
+    // is never told a file was attached. No metadata at all without refs: an
+    // empty object would put a field on every plain message that says nothing.
+    const message: Message = {
+      id: randomUUID(),
+      role: "user",
+      content,
+      ...(attachments.length > 0 ? { metadata: { attachments } } : {}),
+    };
     this.#agent.addMessage(message);
     this.#persist();
     await this.#run();
@@ -504,38 +500,31 @@ export class AgUiClient {
   }
 
   /**
-   * Move the outcome annotations a restored history carries off the agent's
-   * messages and into {@link #outcomes}.
+   * Move the keys a history stored by an earlier release carries at the top
+   * level of its messages into their `metadata`, where this release writes them.
    *
-   * A restore seeds the agent from the stored copy, and the stored copy is the
-   * annotated one {@link #persist} wrote. Left on `agent.messages`, the
-   * annotation went out on the very next request -- the one place it was
-   * promised never to go. Moved rather than dropped: the store keeps the whole
-   * transcript as one list, so the next save has to write each annotation back
-   * or a declined card turns green on the reload after.
+   * Earlier releases wrote a tool message's `outcome` and a user message's
+   * `attachments` beside the protocol's own fields. `@ag-ui/client` 1.0 strips
+   * every undeclared key from the input it sends, so a restored conversation
+   * sent as it was stored would lose both on its first request: the server
+   * would no longer be told about any file attached before the upgrade, and
+   * each strip would print a warning. Moved rather than dropped, so the next
+   * save writes the conversation in the shape this release reads first and a
+   * reload after it still replays a declined card as declined.
    *
-   * `ag_ui_chat_restored_outcome_wire.test.ts` holds the move, off the body of a
-   * real request. The early return only spares the copy for a seed with nothing
-   * to move, and the role check is held by the type checker: only a tool message
-   * has the `toolCallId` the annotation is keyed by.
+   * Merged into the metadata a message already has, with a key already there
+   * winning: a message carrying both was last written by the newer writer.
+   * `ag_ui_chat_restored_outcome_wire.test.ts` reads the result off the body of
+   * a real request. The check before `setMessages` only spares a copy when
+   * nothing moves, which is every restore of a store this release wrote;
+   * nothing observable depends on it.
    */
-  #adoptSeededOutcomes(): void {
+  #moveSeededKeysIntoMetadata(): void {
     const seeded = this.#agent.messages;
-    if (!seeded.some((message) => "outcome" in message)) {
-      return;
+    const moved = seeded.map(withTopLevelKeysInMetadata);
+    if (moved.some((message, index) => message !== seeded[index])) {
+      this.#agent.setMessages(moved);
     }
-    this.#agent.setMessages(
-      seeded.map((message) => {
-        if (message.role !== "tool") {
-          return message;
-        }
-        // An unannotated message records `undefined`, which `#persist` already
-        // reads as "nothing to write back".
-        const { outcome, ...wire } = message as typeof message & { outcome?: unknown };
-        this.#outcomes.set(message.toolCallId, outcome);
-        return wire;
-      }),
-    );
   }
 
   /**
@@ -553,17 +542,21 @@ export class AgUiClient {
    * approval runs or denies them server-side, and a result here would answer
    * them twice.
    *
-   * The labels go to {@link #outcomes}, never onto the messages, because these
-   * messages are the request.
+   * The outcome rides in the result's `metadata`, where the client folds a
+   * server's own, so the next request carries it and a reload replays it. A
+   * server that does not read it ignores it: `metadata` is a declared field.
    */
   #answerUnansweredCalls(resuming: ReadonlySet<string>): void {
     const messages = this.#agent.messages;
     const answered = answerUnansweredCalls(
       messages,
-      (toolCallId) => {
-        this.#outcomes.set(toolCallId, TOOL_OUTCOME.INTERRUPTED);
-        return { id: randomUUID(), role: "tool", content: this.#unfinishedMessage, toolCallId };
-      },
+      (toolCallId) => ({
+        id: randomUUID(),
+        role: "tool",
+        content: this.#unfinishedMessage,
+        toolCallId,
+        metadata: { outcome: TOOL_OUTCOME.INTERRUPTED },
+      }),
       resuming,
     );
     if (answered !== messages) {
@@ -594,12 +587,12 @@ export class AgUiClient {
     for (const interrupt of interrupts) {
       const toolCallId = interrupt.toolCallId;
       if (toolCallId !== undefined && responses[interrupt.id]?.status === "cancelled") {
-        this.#outcomes.set(toolCallId, TOOL_OUTCOME.DENIED);
         this.#agent.addMessage({
           id: randomUUID(),
           role: "tool",
           content: this.#declinedMessage,
           toolCallId,
+          metadata: { outcome: TOOL_OUTCOME.DENIED },
         });
       }
     }
@@ -607,35 +600,32 @@ export class AgUiClient {
   }
 
   /**
-   * Hand the transcript to the host's store, annotated with what {@link #outcomes}
-   * knows about how each tool call ended.
+   * Hand the transcript to the host's store.
    *
-   * Every persist in this class goes through here, because the store keeps only
-   * the most recent list: annotating one call site would mean the next
-   * unannotated save quietly threw the annotations away.
+   * The list as the agent holds it, with nothing added: how each tool call
+   * ended rides in its result's `metadata`, which the client folds in from a
+   * server's `TOOL_CALL_RESULT` and this class writes for the results it makes
+   * itself, so the store sees exactly what the next request sends.
    */
   #persist(): void {
-    const messages = this.#agent.messages;
-    if (this.#outcomes.size === 0) {
-      this.#onPersist(messages);
-      return;
-    }
-    // A copy, and only of the messages that gain something. `agent.messages` is
-    // the list the next `runAgent` sends back to the server, so writing an extra
-    // field into it would put a client-side annotation on the wire; a store is
-    // allowed to hold more than the protocol does.
-    this.#onPersist(
-      messages.map((message) => {
-        if (message.role !== "tool") {
-          return message;
-        }
-        const outcome = this.#outcomes.get(message.toolCallId);
-        // Cast at the AG-UI boundary, as the `attachments` augmentation on a
-        // user message already does: `Message` does not declare the field, and
-        // the default store round-trips it through `JSON.stringify` verbatim.
-        return outcome === undefined ? message : ({ ...message, outcome } as Message);
-      }),
-    );
+    this.#onPersist(this.#agent.messages);
+  }
+
+  /**
+   * The history in the form a save writes it, which is now {@link messages}
+   * itself.
+   *
+   * It differed while this client kept how each tool call ended in a side table
+   * and annotated a copy for the store, because `@ag-ui/client` 0.x kept nothing
+   * but five named fields of a result. 1.0 folds a result's `metadata` onto the
+   * message it appends, so the outcome is on the message and there is no copy
+   * left to make.
+   *
+   * @deprecated Read {@link messages}. Kept so a caller written against the
+   * getter keeps compiling and gets the same list.
+   */
+  get annotatedMessages(): readonly Message[] {
+    return this.messages;
   }
 
   async #runLoop(): Promise<void> {
@@ -722,19 +712,18 @@ export class AgUiClient {
           // next mount. Stop here rather than re-running into a dead context.
           return;
         }
-        // Recorded before the persist below, so the very first save of this
-        // message already carries how it ended. A frontend tool's refusal or
-        // failure never touches the wire's `outcome` field -- no server states
-        // it, because no server ran the call -- so this side table is the only
-        // record there is, and a reload reads a card off it.
-        if (result.outcome !== undefined) {
-          this.#outcomes.set(call.id, result.outcome);
-        }
+        // A frontend tool's refusal or failure is stated by no server, because
+        // no server ran the call, so the client writes it where the client
+        // folds a server's: the result's `metadata`. Written with the message,
+        // so the very first save of it already carries how it ended, and a
+        // reload reads the card off it. A success writes no metadata at all,
+        // as a server's success states none.
         this.#agent.addMessage({
           id: randomUUID(),
           role: "tool",
           content: result.content,
           toolCallId: call.id,
+          ...(result.outcome === undefined ? {} : { metadata: { outcome: result.outcome } }),
         });
         this.#persist();
         executed = true;
@@ -748,7 +737,6 @@ export class AgUiClient {
   #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
     const closed = this.#closedMessageIds;
-    const outcomes = this.#outcomes;
     // Read at event time, not captured now: the flag flips mid-run, and the
     // subscriber is built before the run that a later `cancel()` stops.
     const cancelled = (): boolean => this.#cancelled;
@@ -790,20 +778,22 @@ export class AgUiClient {
         h.onToolCall(call);
       },
       onToolCallResultEvent({ event }) {
-        // Bracket access because the field is not declared: `TOOL_CALL_RESULT`
-        // extends a `passthrough` schema, so an unknown key survives parsing and
-        // arrives here typed only by the catch-all index signature. That is the
-        // whole mechanism the outcome rides -- no schema change in `@ag-ui/core`
-        // is needed for a server to state one.
-        const outcome = event["outcome"];
-        // Recorded even when it is a word this client does not recognise, and
-        // even when it says "success": the store is a record of what the server
-        // said, and re-reading it through the same mapping as the live path is
-        // what keeps a reload agreeing with what the user watched happen.
-        if (typeof outcome === "string") {
-          outcomes.set(event.toolCallId, outcome);
-        }
-        h.onToolResult(event.toolCallId, event.content, outcome);
+        // In the event's `metadata`, the one place on it `@ag-ui/client` 1.0
+        // declares open by key. Its enforcement stage strips every undeclared
+        // key before a subscriber runs, so an `outcome` stated at the top level
+        // of the event -- where servers wrote it for 0.x -- never gets here.
+        //
+        // Nothing is recorded for the transcript: after this returns, the
+        // client builds the tool message and folds the event's metadata onto
+        // it, so the outcome is already on the message a save writes, word for
+        // word as the server said it. A reload reads it back through the same
+        // mapping as the live path, which is what keeps the two agreeing.
+        const outcome: unknown = event.metadata?.["outcome"];
+        // Content may arrive as parts since the protocol's 1.0, so a tool can
+        // return an image beside its text. A card shows text, so the text parts
+        // are joined and the rest left to the host store, which keeps the
+        // message whole; a plain string passes through unchanged.
+        h.onToolResult(event.toolCallId, contentToText(event.content), outcome);
       },
       onActivitySnapshotEvent({ event, messages }) {
         // A snapshot for an id already in the list is a replacement, not a new
@@ -864,9 +854,11 @@ export class AgUiClient {
         }
         pendingDeltas.clear();
       },
-      // `@ag-ui/client` maps the deprecated THINKING_* events onto these
-      // REASONING_* callbacks, so the reasoning family alone covers both
-      // protocol versions.
+      // THINKING_* left the protocol in its 1.0, but `@ag-ui/client` still
+      // converts a server's THINKING_* events onto these REASONING_* callbacks,
+      // with a console warning, for a deprecation window it sets. Nothing in the
+      // family emits THINKING_*: pydantic-ai has sent REASONING_* at every
+      // protocol version django-ag-ui admits.
       onReasoningStartEvent() {
         h.onReasoningStart();
       },
@@ -946,3 +938,41 @@ function isAbortError(error: unknown): boolean {
     error.name === "AbortError" || (error instanceof TypeError && /abort/i.test(error.message))
   );
 }
+
+/**
+ * `message` with the keys an earlier release wrote at its top level -- a tool
+ * message's `outcome`, a user message's `attachments` -- moved into its
+ * `metadata`, or `message` itself when it carries neither.
+ *
+ * Both keys move whatever the role: no message the protocol defines declares
+ * either, so a top-level one can only be this component's own. A key already in
+ * the metadata wins over the one being moved, and a `metadata` that is not an
+ * object is replaced rather than spread -- a store is not trusted to hold the
+ * shape anything here wrote, and a spread string would scatter into numbered
+ * keys.
+ *
+ * Held by "carries history stored by an earlier release into metadata" in
+ * `agui_client.test.ts`, which seeds a message with only `attachments`, one
+ * with only `outcome`, one whose metadata already has the key, and one whose
+ * metadata is a string: deleting either half of the early return, or the
+ * object check, fails it.
+ */
+function withTopLevelKeysInMetadata(message: Message): Message {
+  const { outcome, attachments, ...wire } = message as Message & {
+    outcome?: unknown;
+    attachments?: unknown;
+  };
+  if (outcome === undefined && attachments === undefined) {
+    return message;
+  }
+  const existing = (wire as { metadata?: unknown }).metadata;
+  return {
+    ...wire,
+    metadata: {
+      ...(outcome === undefined ? {} : { outcome }),
+      ...(attachments === undefined ? {} : { attachments }),
+      // `null` passes the check and spreads as nothing, which is what it means.
+      ...(typeof existing === "object" ? existing : {}),
+    },
+  } as Message;
+}

package/src/core/attachment.ts

@@ -1,4 +1,5 @@
 import type { Message } from "@ag-ui/core";
+import { metadataOrTopLevel } from "./utils.js";
 
 /**
  * A durable, lightweight reference to one uploaded file — what an upload
@@ -24,17 +25,24 @@ export interface AttachmentRef {
 /**
  * The attachment refs a user message carries.
  *
- * Refs ride on the message as a non-standard `attachments` field, which the
- * default store round-trips and `@ag-ui/client` preserves through `addMessage`
- * / `structuredClone`, so a restored conversation re-renders its chips. The
- * server's strict `RunAgentInput` validation ignores the unknown field.
+ * `AgUiClient.send` writes them into the message's `metadata`, under
+ * `attachments`. That is the one place they survive the trip: `@ag-ui/client`
+ * 1.0 strips every key its schemas do not declare from the outgoing input, so
+ * refs written at the top level of the message never reach the server, while
+ * `metadata` is declared open by key and sent as it is. The server reads them
+ * from there to tell the agent which files it can read, and the default store
+ * round-trips them, so a restored conversation re-renders its chips.
+ *
+ * A conversation stored by an earlier release has them at the top level, so
+ * that is read when the metadata has none. An older server reads only the top
+ * level, so against one the agent is never told about a file at all.
  *
  * Storage is untrusted — hand-edited, truncated, or corrupted — so malformed
  * entries are dropped here; a shapeless one would throw in `iconFor` and abort
  * the whole history replay.
  */
 export function messageAttachments(message: Message): readonly AttachmentRef[] {
-  const refs = (message as { attachments?: unknown }).attachments;
+  const refs = metadataOrTopLevel(message, "attachments");
   return Array.isArray(refs) ? refs.filter(isAttachmentRef) : [];
 }
 

package/src/core/client_seed.ts

@@ -10,6 +10,18 @@ export interface ClientSeed {
   readonly endpoint: string;
   /** The history the agent starts from, and sends with its first run. */
   readonly initialMessages: readonly Message[];
-  /** Whether the client writes its messages to the conversation store. */
-  readonly persist: boolean;
+  /**
+   * The conversation this client's own history continues, which every save
+   * writes ahead of it.
+   *
+   * Empty for the conversation's own client, whose history is the whole
+   * conversation. A continuation's history is only the turn it adds and its
+   * answer -- the endpoint supplies the rest from its snapshot -- and a store
+   * keeps one list per thread, so a save of that history alone would replace
+   * the conversation with its last exchange, and not saving it lost the
+   * exchange on the next reload.
+   */
+  readonly follows: readonly Message[];
+  /** Handed the whole conversation each time the client saves it, as written. */
+  readonly onSaved?: (conversation: readonly Message[]) => void;
 }

package/src/core/tool_outcome.ts

@@ -13,9 +13,10 @@ export type ToolOutcome = (typeof TOOL_OUTCOME)[keyof typeof TOOL_OUTCOME];
  * The card status a wire outcome settles into.
  *
  * Takes `unknown` rather than {@link ToolOutcome} on purpose: both callers read
- * this off a boundary the type system does not police -- a `passthrough` field
- * on an AG-UI event, and a JSON blob out of the conversation store -- so the
- * narrowing belongs here, once, instead of at each of them.
+ * this off a boundary the type system does not police -- a key in an AG-UI
+ * event's `metadata`, which the protocol declares open and does not validate,
+ * and a JSON blob out of the conversation store -- so the narrowing belongs
+ * here, once, instead of at each of them.
  *
  * **Everything unrecognised maps to `DONE`.** Not because unknown values are
  * expected to be successes, but because the alternative is worse in the

package/src/core/utils.ts

@@ -205,3 +205,26 @@ function toolCallIds(value: unknown): string[] {
         .filter((id): id is string => typeof id === "string")
     : [];
 }
+
+/**
+ * A key a message carries in its `metadata`, or the same key at the message's
+ * top level when its metadata has none.
+ *
+ * Two keys are read this way, a tool message's `outcome` and a user message's
+ * `attachments`, and both for the same reason. `@ag-ui/client` 1.0 strips every
+ * key its schemas do not declare, off an inbound event and off the outgoing
+ * input, and `metadata` is the one place it declares open by key, so that is
+ * where this component writes them. A conversation stored by an earlier release
+ * has them at the top level instead, and a reload has to replay it as it
+ * settled.
+ *
+ * Metadata first, so a message carrying both says what the newer writer said.
+ * The result is `unknown` because it comes out of a store, which is not trusted
+ * to hold the shape anything here wrote; the caller narrows it. `Object()` boxes
+ * an absent, `null` or primitive `metadata` into an object with neither key,
+ * which reads as no metadata without a branch per shape.
+ */
+export function metadataOrTopLevel(message: Message, key: "outcome" | "attachments"): unknown {
+  const metadata = Object((message as { metadata?: unknown }).metadata) as Record<string, unknown>;
+  return metadata[key] ?? (message as unknown as Record<string, unknown>)[key];
+}

package/src/tools/tool_catalog.ts

@@ -264,13 +264,13 @@ export class ToolCatalog {
           },
           required: ["question"],
         },
-        handler: (args) => this.#askUser(args),
+        handler: (args, callId) => this.#askUser(args, callId),
       },
     ];
   }
 
   /** Render the `ask_user` question card and resolve with the user's answer. */
-  async #askUser(args: Record<string, unknown>): Promise<string> {
+  async #askUser(args: Record<string, unknown>, callId: string | undefined): Promise<string> {
     const question = typeof args["question"] === "string" ? args["question"] : "";
     const request: QuestionRequest = { question };
     const rawOptions = args["options"];
@@ -284,20 +284,71 @@ export class ToolCatalog {
     // it with an empty answer (the run is then cancelled).
     const signal = this.#host.decision.open();
     this.#host.hidePending();
-    // A host-supplied renderer takes full control of the UI; otherwise the
-    // built-in inline card renders into the current answer group.
+    // The built-in inline card renders into the current answer group.
+    const builtIn = (): Promise<string> =>
+      requestQuestion(this.#host.ensureGroup(), request, {
+        signal,
+        strings: this.#host.strings(),
+      });
+    // A host-supplied renderer takes full control of the UI.
     const renderer = this.#host.askUserRenderer();
-    const answer =
-      renderer !== null
-        ? // Called on the element, as `this.askUserRenderer(...)` always was.
-          await renderer.call(this.#host.element, request, { signal })
-        : await requestQuestion(this.#host.ensureGroup(), request, {
-            signal,
-            strings: this.#host.strings(),
-          });
+    let answer: string;
+    if (renderer === null) {
+      answer = await builtIn();
+    } else {
+      // Awaited here rather than inside a helper, so an answering renderer
+      // takes exactly as many turns to be heard as it always did.
+      try {
+        // Called on the element, as `this.askUserRenderer(...)` always was.
+        answer = await renderer.call(this.#host.element, request, { signal });
+      } catch (error) {
+        answer = await this.#afterRendererFailed(error, signal, callId, builtIn);
+      }
+    }
     this.#host.decision.close();
     this.#host.updateEmptyState();
     this.#host.follow();
     return answer;
   }
+
+  /**
+   * Answer an `ask_user` call whose host renderer threw or rejected instead of
+   * answering: put the question to the built-in card.
+   *
+   * The same answer `approvalRenderer` gets for the same failure, and for the
+   * same reason: a renderer is presentation, not a policy. It decides how the
+   * question looks, never whether the agent's question is put to the user.
+   * Uncaught, the throw escaped the handler, so the call's card settled as an
+   * error quoting the host's message, that message went on to the agent as the
+   * tool result -- a detail of the host's page, never written for the model --
+   * and the pending decision was never closed, so the next Stop, in whatever
+   * round, aborted the signal of a wait that had already ended rather than
+   * finding nothing open. The built-in card still asks,
+   * and the run carries on as if no renderer had been set. Reported the way a
+   * failed `render` is, and for the same reason: survived is not the same as
+   * findable.
+   *
+   * Except when the wait was already abandoned. A renderer honouring its signal
+   * rejects once a Stop fires it, which is the signal working rather than the
+   * renderer failing, and a card drawn then would ask about a run the user just
+   * ended. So it resolves with the empty answer the built-in card resolves with
+   * on the same abort, and says nothing.
+   */
+  #afterRendererFailed(
+    error: unknown,
+    signal: AbortSignal,
+    callId: string | undefined,
+    builtIn: () => Promise<string>,
+  ): Promise<string> {
+    if (signal.aborted) {
+      return Promise.resolve("");
+    }
+    // Named by call rather than by question: the model can ask the same thing
+    // twice in one turn, and the id is the one thing that tells them apart.
+    console.warn(
+      `ag-ui-chat: askUserRenderer failed for tool call ${callId}, so the built-in question card asks instead`,
+      error,
+    );
+    return builtIn();
+  }
 }