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

package/dist/ui/history/conversation_history.d.ts

@@ -1,4 +1,4 @@
-import type { Message } from "@ag-ui/core";
+import { type Message } from "@ag-ui/core";
 import type { ActivityRegistry } from "../../core/activity_registry.js";
 import type { AgUiClient } from "../../core/agui_client.js";
 import type { ClientSeed } from "../../core/client_seed.js";

package/dist/ui/history/conversation_history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation_history.d.ts","sourceRoot":"","sources":["../../../src/ui/history/conversation_history.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,SAAS,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;IAC1D,0CAA0C;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,qBAAqB,GAAG,IAAI,CAAC;IAChE,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAC/E,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7D,yDAAyD;IACzD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,kBAAkB,GAAG,SAAS,CAAC;IAClE,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,cAAc,CAAC;IAC/E,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,IAAI,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;IACzC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,UAAU,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAmB;;IA0B9B,YAAY,IAAI,EAAE,uBAAuB,EAExC;IAED,8BAA8B;IAC9B,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,qEAAqE;IACrE,IAAI,QAAQ,IAAI,SAAS,OAAO,EAAE,CAEjC;IAED,6EAA6E;IAC7E,IAAI,YAAY,IAAI,UAAU,GAAG,IAAI,CAEpC;IAED,oDAAoD;IACpD,iBAAiB,IAAI,IAAI,CAExB;IAED,mDAAmD;IACnD,WAAW,IAAI,IAAI,CAElB;IAED;;;;;;;;OAQG;IACH,gBAAgB,IAAI,IAAI,CAGvB;IAED,6EAA6E;IAC7E,cAAc,IAAI,IAAI,CAKrB;IAED,+DAA+D;IAC/D,UAAU,IAAI,IAAI,CAOjB;IAED,yEAAyE;IACzE,IAAI,IAAI,QAAQ,GAAG,IAAI,CAatB;IAED,mEAAmE;IACnE,WAAW,IAAI,IAAI,CAQlB;IAED,mEAAmE;IACnE,eAAe,IAAI,IAAI,CAKtB;IAED,0EAA0E;IACpE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlD;IAED,kEAAkE;IAClE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGlD;IAED,4EAA4E;IAC5E,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYnC;IAED,kEAAkE;IAC5D,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAMnC;IAWD;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA0GpE;IAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAyD/B;IAyBD;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoF7B;CAgCF"}
+{"version":3,"file":"conversation_history.d.ts","sourceRoot":"","sources":["../../../src/ui/history/conversation_history.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artooi/ag-ui-web-component",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Framework-free <ag-ui-chat> Web Component over the AG-UI protocol. Drop-in chat sidebar with a pluggable client-side tool registry, DOM driver primitives, animations, and destructive-action confirmation modal.",
   "type": "module",
   "main": "./dist/index.js",
@@ -54,8 +54,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@ag-ui/client": ">=0.0.59 <0.1",
-    "@ag-ui/core": ">=0.0.59 <0.1",
+    "@ag-ui/client": ">=1.0.0 <2",
+    "@ag-ui/core": ">=1.0.0 <2",
     "dompurify": "^3.4.13",
     "marked": "^18.0.9"
   },

package/src/constants.ts

@@ -271,7 +271,8 @@ export const TOOL_CALL_STATUS = {
 } as const;
 
 /**
- * How a tool call ended, as the server states it on `TOOL_CALL_RESULT`.
+ * How a tool call ended, as the server states it under `outcome` in a
+ * `TOOL_CALL_RESULT`'s `metadata`.
  *
  * The vocabulary is pydantic-ai's own `ToolReturnPart.outcome`, carried whole
  * rather than re-spelled, so the four repos that pass a refusal along agree on
@@ -280,7 +281,7 @@ export const TOOL_CALL_STATUS = {
  * **Absent means {@link TOOL_OUTCOME.SUCCESS}, and that is load-bearing.** Every
  * server written before the field existed omits it, so a missing field has to
  * render exactly as a plain result did — which is why this is an optional
- * annotation on the event and not a required one. `FAILED` is a call that ran
+ * key in the event's metadata and not a required field. `FAILED` is a call that ran
  * and failed; `DENIED` is one a person or a guard refused, so it never ran at
  * all. The two are worth distinguishing on screen because only the second is
  * something the user did. `INTERRUPTED` is a call that produced no result because

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,47 +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 {
-    this.#onPersist(this.annotatedMessages);
+    this.#onPersist(this.#agent.messages);
   }
 
   /**
-   * The history in the form a save writes it: {@link messages}, with how each
-   * tool call ended annotated onto its result -- exactly what
-   * {@link AgUiClientConfig.onPersist} is handed.
+   * The history in the form a save writes it, which is now {@link messages}
+   * itself.
    *
-   * For writing the conversation somewhere other than a save. The element needs
-   * it when a checkpoint continuation adds to a conversation this client holds:
-   * the continuation's saves write the conversation ahead of the exchange, and
-   * the bare {@link messages} would drop the annotations, so a declined card
-   * turned green on the next reload.
+   * 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[] {
-    const messages = this.#agent.messages;
-    if (this.#outcomes.size === 0) {
-      return messages;
-    }
-    // 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.
-    return 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);
-    });
+    return this.messages;
   }
 
   async #runLoop(): Promise<void> {
@@ -734,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;
@@ -760,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;
@@ -802,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
@@ -876,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();
       },
@@ -958,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/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];
+}