@artooi/ag-ui-web-component 0.36.0 → 0.38.0

package/src/core/ag_ui_chat.ts

@@ -61,47 +61,45 @@ import { createPageMapContext, type PageMap } from "../tools/page_map.js";
 import { createPageStateTools, type PageState } from "../tools/page_state.js";
 import { parseToolCatalog, type ToolCatalogEntry } from "../tools/parse_tool_catalog.js";
 import { createRouteTools, type RouteMap } from "../tools/route_map.js";
+import { renderChart } from "../ui/charts/chart_block.js";
+import { chartSpecFrom } from "../ui/charts/chart_spec_from.js";
+import { CHART_TOOL_NAME, createChartTool } from "../ui/charts/chart_tool.js";
+import { AttachmentTray } from "../ui/composer/attachment_tray.js";
+import { SkillsMenu } from "../ui/composer/skills_menu.js";
+import { VoiceInput } from "../ui/composer/voice_input.js";
+import { attachCopyButtons } from "../ui/excerpts/attach_copy_buttons.js";
+import { copyPayload } from "../ui/excerpts/copy_payload.js";
+import { attachQuoteOffer, type PageQuoteOffer } from "../ui/excerpts/page_quote_offer.js";
+import { asQuote, quotableSelection } from "../ui/excerpts/quote_selection.js";
+import { CheckpointMenu, type CheckpointVerb } from "../ui/history/checkpoint_menu.js";
+import type { RelativeTimeFormatter } from "../ui/history/relative_time.js";
+import { ThreadDrawer } from "../ui/history/thread_drawer.js";
 import {
   type ApprovalRenderer,
   type ApprovalRequest,
   requestApproval,
-} from "../ui/approval_card.js";
-import { attachCopyButtons } from "../ui/attach_copy_buttons.js";
-import { renderAttachmentChips } from "../ui/attachment_chips.js";
-import { AttachmentTray } from "../ui/attachment_tray.js";
-import { renderChart } from "../ui/chart_block.js";
-import { chartSpecFrom } from "../ui/chart_spec_from.js";
-import { CHART_TOOL_NAME, createChartTool } from "../ui/chart_tool.js";
-import { CheckpointMenu, type CheckpointVerb } from "../ui/checkpoint_menu.js";
-import { clampLauncher } from "../ui/clamp_launcher.js";
-import { clampPanel } from "../ui/clamp_panel.js";
-import { type ConfirmationRequest, requestConfirmation } from "../ui/confirmation_card.js";
-import { copyPayload } from "../ui/copy_payload.js";
-import { enableLauncherDrag } from "../ui/launcher_drag.js";
+} from "../ui/interrupts/approval_card.js";
+import {
+  type ConfirmationRequest,
+  requestConfirmation,
+} from "../ui/interrupts/confirmation_card.js";
+import {
+  type QuestionRenderer,
+  type QuestionRequest,
+  requestQuestion,
+} from "../ui/interrupts/question_card.js";
+import { clampLauncher } from "../ui/placement/clamp_launcher.js";
+import { clampPanel } from "../ui/placement/clamp_panel.js";
+import { enableLauncherDrag } from "../ui/placement/launcher_drag.js";
 import {
   type ExpandCorner,
   type Extent,
   type LauncherBox,
   launcherPlacement,
   type ViewportBox,
-} from "../ui/launcher_placement.js";
-import {
-  attachMessageActions,
-  messageActionBar,
-  messageActionButton,
-} from "../ui/message_actions.js";
-import { attachQuoteOffer, type PageQuoteOffer } from "../ui/page_quote_offer.js";
-import { enablePanelDrag } from "../ui/panel_drag.js";
-import { placeWidget } from "../ui/place_widget.js";
-import { prettifyToolName } from "../ui/prettify_tool_name.js";
-import {
-  type QuestionRenderer,
-  type QuestionRequest,
-  requestQuestion,
-} from "../ui/question_card.js";
-import { asQuote, quotableSelection } from "../ui/quote_selection.js";
-import type { RelativeTimeFormatter } from "../ui/relative_time.js";
-import { renderMarkdown } from "../ui/render_markdown.js";
+} from "../ui/placement/launcher_placement.js";
+import { enablePanelDrag } from "../ui/placement/panel_drag.js";
+import { placeWidget } from "../ui/placement/place_widget.js";
 import {
   createResizeHandle,
   gripName,
@@ -110,24 +108,35 @@ import {
   type ResizeAxis,
   type ResizeGrip,
   type ResizeSize,
-} from "../ui/resize_handle.js";
-import { wrapWords } from "../ui/reveal_words.js";
-import { renderRunNotice } from "../ui/run_notice.js";
-import { SkillsMenu } from "../ui/skills_menu.js";
-import { createStickToBottom, type StickToBottom } from "../ui/stick_to_bottom.js";
-import { STYLES } from "../ui/styles.js";
-import { SubAgentPanel, type SubAgentPhase, type SubAgentUpdate } from "../ui/subagent_panel.js";
-import { subAgentUpdate } from "../ui/subagent_update.js";
-import { renderSuggestionChips } from "../ui/suggestion_chips.js";
-import { ThoughtsBlock } from "../ui/thoughts_block.js";
-import { ThreadDrawer } from "../ui/thread_drawer.js";
+} from "../ui/placement/resize_handle.js";
+import { prettifyToolName } from "../ui/progress/prettify_tool_name.js";
+import { renderRunNotice } from "../ui/progress/run_notice.js";
+import {
+  SubAgentPanel,
+  type SubAgentPhase,
+  type SubAgentUpdate,
+} from "../ui/progress/subagent_panel.js";
+import { subAgentUpdate } from "../ui/progress/subagent_update.js";
+import { ThoughtsBlock } from "../ui/progress/thoughts_block.js";
 import {
   ToolCallCard,
   type ToolDisplayMode,
   type ToolPayloadFormatter,
-} from "../ui/tool_call_card.js";
+} from "../ui/progress/tool_call_card.js";
+import { STYLES } from "../ui/styles.js";
+import { renderAttachmentChips } from "../ui/transcript/attachment_chips.js";
+import {
+  attachMessageActions,
+  messageActionBar,
+  messageActionButton,
+} from "../ui/transcript/message_actions.js";
+import { renderMarkdown } from "../ui/transcript/render_markdown.js";
+import { wrapWords } from "../ui/transcript/reveal_words.js";
+import { createStickToBottom, type StickToBottom } from "../ui/transcript/stick_to_bottom.js";
+import { renderSuggestionChips } from "../ui/transcript/suggestion_chips.js";
 import { DEFAULT_UI_STRINGS, mergeUiStrings, type UiStrings } from "../ui/ui_strings.js";
-import { VoiceInput } from "../ui/voice_input.js";
+import type { ActivityRegistration } from "./activity_registration.js";
+import type { ActivityRenderer } from "./activity_renderer.js";
 import {
   AgUiClient,
   type AgUiClientHandlers,
@@ -143,6 +152,17 @@ import {
   writeStoredItem,
 } from "./conversation_store.js";
 import { type AgentFactory, createHttpAgent } from "./create_http_agent.js";
+import type { AttachmentsDetail } from "./events/attachments_detail.js";
+import type { CustomAgentDetail } from "./events/custom_agent_detail.js";
+import type { FeedbackDetail } from "./events/feedback_detail.js";
+import type { InvalidateDetail } from "./events/invalidate_detail.js";
+import type { RunFinishedDetail } from "./events/run_finished_detail.js";
+import type { StateDetail } from "./events/state_detail.js";
+import type { SubmitDetail } from "./events/submit_detail.js";
+import type { ToggleDetail } from "./events/toggle_detail.js";
+import type { ToolRun } from "./events/tool_run.js";
+import type { UnreadDetail } from "./events/unread_detail.js";
+import type { MessageRole } from "./message_role.js";
 import { RemoteConversationStore } from "./remote_conversation_store.js";
 import { RunIndex } from "./run_index.js";
 import { toolStatusFromOutcome } from "./tool_outcome.js";
@@ -150,140 +170,6 @@ import { type TranscribeHandler, transcribeAudio } from "./transcribe_audio.js";
 import { type UploadHandler, uploadAttachment } from "./upload_attachment.js";
 import { mintThread, warnOnCrossOriginCredentials, withCredentials } from "./utils.js";
 
-/** The role a rendered chat message takes. */
-export type MessageRole = (typeof MESSAGE_ROLE)[keyof typeof MESSAGE_ROLE];
-
-/** `detail` shape of the {@link SUBMIT_EVENT} CustomEvent. */
-export interface SubmitDetail {
-  readonly content: string;
-  /** Durable refs for the files attached to this message (empty when none). */
-  readonly attachments: readonly AttachmentRef[];
-}
-
-/** `detail` shape of the {@link ATTACHMENT_EVENT} CustomEvent. */
-export interface AttachmentsDetail {
-  /** Durable refs for every file that has finished uploading. */
-  readonly attachments: readonly AttachmentRef[];
-  /** How many files are still uploading; a send now would leave these behind. */
-  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>>;
-}
-
-/** One tool that ran during an interaction, as {@link RunFinishedDetail} lists it. */
-export interface ToolRun {
-  readonly name: string;
-  /**
-   * Where it executed. `"server"` is the one a data-rendering host cares about:
-   * a `"client"` tool ran in the host's own handler, so the host already knows
-   * whatever it did.
-   */
-  readonly side: "server" | "client";
-}
-
-/** `detail` shape of the {@link RUN_FINISHED_EVENT} CustomEvent. */
-export interface RunFinishedDetail {
-  /** In settle order. Empty when the interaction called no tools. */
-  readonly tools: readonly ToolRun[];
-  /**
-   * 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 {
-  readonly collapsed: boolean;
-}
-
-/** `detail` shape of the {@link UNREAD_EVENT} CustomEvent. */
-export interface UnreadDetail {
-  readonly unread: number;
-}
-
 /**
  * Attributes read once while connecting, to decide what chrome exists at all.
  *
@@ -829,7 +715,17 @@ export class AgUiChat extends HTMLElement {
   readonly #checkpoints: CheckpointMenu;
   /** Built lazily from `data-runs-url`; `null` when the host didn't opt in. */
   #runIndex: RunIndex | null = null;
-  readonly #skillHint: HTMLDivElement;
+  /**
+   * The one-line hint above the composer, cleared by the next keystroke.
+   *
+   * Two things write it -- a skill whose template is short of a field, and a
+   * run continuation picked with nothing typed -- and both say the same kind of
+   * thing: what the composer still needs before this can go. Its `part` stays
+   * `skill-hint`, which the skills feature named and the README documents;
+   * renaming a part is breaking, and a second hint element in the same slot
+   * would be worse than one whose name is a release older than its job.
+   */
+  readonly #composerHint: HTMLDivElement;
   /** File-picker button + hidden input + tray slot; the tray mounts on connect. */
   readonly #attachButton: HTMLButtonElement;
   readonly #fileInput: HTMLInputElement;
@@ -1052,7 +948,7 @@ export class AgUiChat extends HTMLElement {
     this.#input = document.createElement("textarea");
     this.#send = document.createElement("button");
     this.#title = document.createElement("span");
-    this.#skillHint = document.createElement("div");
+    this.#composerHint = document.createElement("div");
     this.#attachButton = document.createElement("button");
     this.#fileInput = document.createElement("input");
     this.#attachSlot = document.createElement("div");
@@ -1144,10 +1040,29 @@ export class AgUiChat extends HTMLElement {
   async #continueRun(runId: string, verb: CheckpointVerb): Promise<void> {
     const index = this.#runs();
     if (index === null) {
+      // Unreachable from the built-in control: the header button is only
+      // rendered when `#runs()` is configured, so a row to pick cannot exist
+      // without one. A host calling `openCheckpoints()` regardless gets the
+      // documented empty panel, which has no rows either. Typed, not silent.
       return;
     }
     const content = this.#input.value.trim();
     if (content === "") {
+      // A continuation sends *only* the next turn -- the snapshot supplies
+      // everything before it -- so with an empty composer there is nothing to
+      // send. Returning here was the same failure the endpoint guard above had:
+      // the row's button closes the panel before this runs, so the widget
+      // visibly reacted and then did nothing, which reads as a resume that was
+      // attempted and lost rather than one that never started.
+      //
+      // Said at the composer rather than in the transcript, because that is
+      // where the fix goes and because the hint clears itself on the first
+      // keystroke -- a transcript notice for a recoverable slip would outlive
+      // the slip. Focus follows for the same reason `#applySkill` moves it when
+      // a template is short of a field.
+      this.#composerHint.textContent = this.#strings.continueNeedsTurn;
+      this.#composerHint.hidden = false;
+      this.#input.focus();
       return;
     }
     this.#input.value = "";
@@ -1805,21 +1720,45 @@ export class AgUiChat extends HTMLElement {
     return value !== null && value !== "false";
   }
 
-  /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
-  #readStringOverrides(): Partial<UiStrings> {
-    const raw = this.getAttribute("data-strings");
+  /**
+   * Parse a JSON-valued attribute, saying so when it will not parse.
+   *
+   * `null` for an absent attribute, and `null` again for one that is not JSON --
+   * but not quietly the second time. Quoting JSON inside an HTML attribute is
+   * fiddly, and the result of getting it wrong is indistinguishable from the
+   * feature being switched off: no chips appear, or the strings stay English,
+   * with nothing anywhere saying why. That is the same failure `data-paste-attach`
+   * already reports for a value it cannot read.
+   *
+   * Console only. A page author's typo is not the reader's business, nothing the
+   * reader did was refused, and the degraded widget is still perfectly usable.
+   */
+  #readJsonAttribute(name: string): unknown {
+    const raw = this.getAttribute(name);
     if (raw === null) {
-      return {};
+      return null;
     }
     try {
-      const parsed: unknown = JSON.parse(raw);
-      if (typeof parsed === "object" && parsed !== null) {
-        return parsed as Partial<UiStrings>;
-      }
+      return JSON.parse(raw);
     } catch {
-      // Malformed JSON — fall back to the defaults rather than failing to mount.
+      console.warn(
+        `<ag-ui-chat>: ${name} is not valid JSON, so it was ignored entirely and ` +
+          "the built-in default is being used. Check the quoting -- JSON inside " +
+          "an HTML attribute needs single quotes around the attribute value, or " +
+          "its own double quotes escaped.",
+      );
+      return null;
     }
-    return {};
+  }
+
+  /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
+  #readStringOverrides(): Partial<UiStrings> {
+    const parsed = this.#readJsonAttribute("data-strings");
+    // A JSON number or string parses fine and overrides nothing. Not warned
+    // about separately: it is the same "this attribute did not take effect"
+    // as a parse failure, and the warning above already covers the spelling
+    // that produces it by accident.
+    return typeof parsed === "object" && parsed !== null ? (parsed as Partial<UiStrings>) : {};
   }
 
   /**
@@ -2278,15 +2217,9 @@ export class AgUiChat extends HTMLElement {
 
   /** Parse the inline `data-skills` JSON catalog (empty when absent/malformed). */
   #readEmbeddedSkills(): readonly Skill[] {
-    const raw = this.getAttribute("data-skills");
-    if (raw === null) {
-      return [];
-    }
-    try {
-      return parseSkills(JSON.parse(raw));
-    } catch {
-      return [];
-    }
+    // `parseSkills` drops anything that is not a well-formed skill, `null`
+    // included, so the absent and unparseable cases need no branch here.
+    return parseSkills(this.#readJsonAttribute("data-skills"));
   }
 
   /** Fetch the backend skills catalog from `data-skills-url`, if set. */
@@ -2329,7 +2262,7 @@ export class AgUiChat extends HTMLElement {
    */
   #applySkill(skill: Skill): void {
     if (skill.prompt === undefined) {
-      this.#skillHint.hidden = true;
+      this.#composerHint.hidden = true;
       void this.sendMessage(`/${skill.name}`);
       return;
     }
@@ -2341,17 +2274,17 @@ export class AgUiChat extends HTMLElement {
       // keystroke replaces it. Blocking with a hint alone left whatever the
       // user had typed to open the palette — a lone "/" — sitting there, which
       // says nothing about what the skill wanted or how to give it.
-      this.#skillHint.textContent = this.#strings.skillNeeds
+      this.#composerHint.textContent = this.#strings.skillNeeds
         .replace("{title}", skill.title)
         .replace("{fields}", missing.join(", "));
-      this.#skillHint.hidden = false;
+      this.#composerHint.hidden = false;
       this.#input.value = text;
       this.#autoGrow();
       this.#input.focus();
       this.#selectFirstPlaceholder(text);
       return;
     }
-    this.#skillHint.hidden = true;
+    this.#composerHint.hidden = true;
     this.#input.value = text;
     this.#autoGrow();
     if (skill.sendImmediately === false) {
@@ -4318,9 +4251,9 @@ export class AgUiChat extends HTMLElement {
       void this.#submit();
     });
 
-    this.#skillHint.className = "skill-hint";
-    this.#skillHint.setAttribute("part", "skill-hint");
-    this.#skillHint.hidden = true;
+    this.#composerHint.className = "skill-hint";
+    this.#composerHint.setAttribute("part", "skill-hint");
+    this.#composerHint.hidden = true;
 
     // File-upload affordance: a paperclip button (hidden until
     // `data-attachments-url` is wired) opening a hidden multi-file input.
@@ -4352,8 +4285,9 @@ export class AgUiChat extends HTMLElement {
     tools.append(this.#attachButton, this.#voiceSlot, this.#send);
     composer.append(this.#input, tools);
     inputRow.append(composer, this.#fileInput);
-    // Skill surfaces sit just above the input: palette (opens on `/`), chips,
-    // the missing-placeholder hint, and the pending-attachments tray.
+    // Composer surfaces sit just above the input: the skills palette (opens on
+    // `/`), the chips, the hint saying what the composer still needs, and the
+    // pending-attachments tray.
     this.#messagesWrap.className = "messages-wrap";
     // Sibling of the list inside a shared box, not a child of it: the
     // affordance offering to scroll must not scroll away with the content.
@@ -4364,7 +4298,7 @@ export class AgUiChat extends HTMLElement {
       this.#messagesWrap,
       this.#skillsMenu.palette,
       this.#skillsMenu.chips,
-      this.#skillHint,
+      this.#composerHint,
       this.#queuedRow,
       this.#attachSlot,
       inputRow,
@@ -4689,10 +4623,16 @@ export class AgUiChat extends HTMLElement {
     this.#emptyWrap.hidden = this.#messages.childElementCount > 1;
   }
 
-  /** Forward input changes to the skills palette and clear any stale hint. */
+  /**
+   * Forward input changes to the skills palette and clear any stale hint.
+   *
+   * Typing is the answer to every hint that surface carries -- a skill short of
+   * a field, a continuation short of its next turn -- so the keystroke that
+   * starts answering it is the right moment to take it down.
+   */
   #onInput(): void {
     this.#skillsMenu.onInput(this.#input.value);
-    this.#skillHint.hidden = true;
+    this.#composerHint.hidden = true;
     this.#autoGrow();
     // Typing puts the composer back in the user's hands: the next ArrowUp
     // starts from the newest turn again rather than continuing a walk through
@@ -4992,8 +4932,39 @@ export class AgUiChat extends HTMLElement {
     );
   }
 
+  /**
+   * Hand the message to the client, or say why it is going nowhere.
+   *
+   * With no `endpoint` there is nothing to send to, and this used to return
+   * here in silence. That is the worst shape the failure can take, because the
+   * two halves of a send that *did* work have already happened by now: the
+   * user's bubble is on screen and {@link SUBMIT_EVENT} has been dispatched. So
+   * the message looks sent, the composer is empty, the Send button never turns
+   * into Stop, and no request is ever made -- an unanswered question rather
+   * than a broken widget. Nothing reached the console either, so the developer
+   * had no thread to pull and the user had no reason to think anything was
+   * wrong with the page.
+   *
+   * Both audiences are told, because they need different things. The console
+   * carries the developer's version -- the attribute is missing, here is what
+   * to set -- since a missing attribute is a page's mistake and not the
+   * reader's. The transcript carries the reader's, because they are looking at
+   * their own message waiting for a reply that cannot come, and the honest
+   * alternative to one muted line is an indefinite wait.
+   *
+   * Said on every attempt rather than once. Each send is a separate thing the
+   * user asked for and did not get, and a once-only report is silence for every
+   * attempt after the first -- which is the defect again, just later.
+   */
   async #client_send(content: string, attachments: readonly AttachmentRef[]): Promise<void> {
     if (this.endpoint === "") {
+      console.error(
+        "<ag-ui-chat>: no endpoint is set, so this message was not sent and no " +
+          "request was made. Point the element at your AG-UI mount with the " +
+          'endpoint attribute (endpoint="/agent/"), or assign chat.endpoint ' +
+          "before sending.",
+      );
+      this.#appendNotice("⚠", this.#strings.notConnected, "not-connected");
       return;
     }
     await this.#ensureClient().send(content, attachments);
@@ -5423,6 +5394,26 @@ export class AgUiChat extends HTMLElement {
         this.#streamDeltas += 1;
       },
       onTextEnd: (buffer) => {
+        // A text message that carried no content is a declaration, not an
+        // answer, and drawing one puts an empty bubble above every tool call.
+        //
+        // `TOOL_CALL_START` names the assistant message a call belongs to, and
+        // a response whose first part is a tool call has no text to open that
+        // message with. pydantic-ai 2.37 started opening and closing an empty
+        // one there so the id names a message the stream actually announced --
+        // before that it named one no event carried, which a client could only
+        // answer by inventing an id of its own that matches nothing echoed
+        // back. So this envelope is a correctness fix upstream, it is legal
+        // AG-UI, and any server may send one.
+        //
+        // `#renderHistoricMessage` already declines to draw a bubble for an
+        // assistant message with no text. Without the same rule here the live
+        // transcript and the reloaded one disagree about the same
+        // conversation, which is the harder half of the bug to notice.
+        if (buffer === "") {
+          this.#endStream();
+          return;
+        }
         const bubble = this.#streamInto(buffer);
         // Only reveal word-by-word when the message arrived at once. If it
         // streamed across multiple deltas it already revealed progressively, so

package/src/core/events/attachments_detail.ts

@@ -0,0 +1,9 @@
+import type { AttachmentRef } from "../attachment.js";
+
+/** `detail` shape of the {@link ATTACHMENT_EVENT} CustomEvent. */
+export interface AttachmentsDetail {
+  /** Durable refs for every file that has finished uploading. */
+  readonly attachments: readonly AttachmentRef[];
+  /** How many files are still uploading; a send now would leave these behind. */
+  readonly pending: number;
+}

package/src/core/events/custom_agent_detail.ts

@@ -0,0 +1,7 @@
+/** `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;
+}

package/src/core/events/feedback_detail.ts

@@ -0,0 +1,6 @@
+/** {@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";
+}

package/src/core/events/invalidate_detail.ts

@@ -0,0 +1,15 @@
+/** `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;
+}

package/src/core/events/run_finished_detail.ts

@@ -0,0 +1,22 @@
+import type { ToolRun } from "./tool_run.js";
+
+/** `detail` shape of the {@link RUN_FINISHED_EVENT} CustomEvent. */
+export interface RunFinishedDetail {
+  /** In settle order. Empty when the interaction called no tools. */
+  readonly tools: readonly ToolRun[];
+  /**
+   * 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[];
+}

package/src/core/events/state_detail.ts

@@ -0,0 +1,4 @@
+/** `detail` shape of the {@link STATE_EVENT} CustomEvent. */
+export interface StateDetail {
+  readonly state: Readonly<Record<string, unknown>>;
+}

package/src/core/events/submit_detail.ts

@@ -0,0 +1,8 @@
+import type { AttachmentRef } from "../attachment.js";
+
+/** `detail` shape of the {@link SUBMIT_EVENT} CustomEvent. */
+export interface SubmitDetail {
+  readonly content: string;
+  /** Durable refs for the files attached to this message (empty when none). */
+  readonly attachments: readonly AttachmentRef[];
+}

package/src/core/events/toggle_detail.ts

@@ -0,0 +1,4 @@
+/** `detail` shape of the {@link TOGGLE_EVENT} CustomEvent. */
+export interface ToggleDetail {
+  readonly collapsed: boolean;
+}

package/src/core/events/tool_run.ts

@@ -0,0 +1,10 @@
+/** One tool that ran during an interaction, as {@link RunFinishedDetail} lists it. */
+export interface ToolRun {
+  readonly name: string;
+  /**
+   * Where it executed. `"server"` is the one a data-rendering host cares about:
+   * a `"client"` tool ran in the host's own handler, so the host already knows
+   * whatever it did.
+   */
+  readonly side: "server" | "client";
+}