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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artooi/ag-ui-web-component",
-  "version": "0.35.1",
+  "version": "0.36.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",

package/src/constants.ts

@@ -263,6 +263,32 @@ export const TOOL_CALL_STATUS = {
   DECLINED: "declined",
 } as const;
 
+/**
+ * How a tool call ended, as the server states it on `TOOL_CALL_RESULT`.
+ *
+ * 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
+ * one word for it.
+ *
+ * **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
+ * 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.
+ *
+ * Anything *else* on the wire — a value from a later protocol version, or
+ * pydantic-ai's own `interrupted` — is read as a success rather than rejected.
+ * A card is a claim about what happened, and "I do not know this word" is not
+ * grounds for claiming failure. `toolStatusFromOutcome` is where that is done.
+ */
+export const TOOL_OUTCOME = {
+  SUCCESS: "success",
+  FAILED: "failed",
+  DENIED: "denied",
+} as const;
+
 /**
  * Lifecycle status of a pending-attachment chip in the composer tray. A chip
  * opens as `UPLOADING` (with a progress bar), then settles to `READY` (a durable

package/src/core/ag_ui_chat.ts

@@ -35,6 +35,7 @@ import {
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
+  TOOL_OUTCOME,
   UNREAD_EVENT,
   X_CONFIRM_KEY,
   X_SUMMARY_KEY,
@@ -144,6 +145,7 @@ import {
 import { type AgentFactory, createHttpAgent } from "./create_http_agent.js";
 import { RemoteConversationStore } from "./remote_conversation_store.js";
 import { RunIndex } from "./run_index.js";
+import { toolStatusFromOutcome } from "./tool_outcome.js";
 import { type TranscribeHandler, transcribeAudio } from "./transcribe_audio.js";
 import { type UploadHandler, uploadAttachment } from "./upload_attachment.js";
 import { mintThread, warnOnCrossOriginCredentials, withCredentials } from "./utils.js";
@@ -3995,7 +3997,17 @@ export class AgUiChat extends HTMLElement {
     if (message.role === "tool") {
       const card = this.#toolCards.get(message.toolCallId);
       if (card !== undefined) {
-        card.settle(TOOL_CALL_STATUS.DONE, message.content);
+        // The outcome `AgUiClient` annotated onto the persisted message, read
+        // back through the same mapping the live path uses -- so a card that
+        // said "declined" before the reload still says it after. Narrowed off
+        // `unknown` rather than trusted, like every other field read out of the
+        // store: `Message` does not declare it, a host store may not round-trip
+        // it, and history written before this shipped has none. All three land
+        // on DONE, which is what this line did unconditionally.
+        card.settle(
+          toolStatusFromOutcome((message as { outcome?: unknown }).outcome),
+          message.content,
+        );
       }
     }
   }
@@ -5175,7 +5187,9 @@ export class AgUiChat extends HTMLElement {
       const message = this.#strings.pageMoved;
       card.settle(TOOL_CALL_STATUS.ERROR, message);
       this.#showPending();
-      return { content: `Error: ${message}`, error: message };
+      // Stated so a reload settles this card the same way. The card's own status
+      // lives only in the DOM, and the DOM is what a reload throws away.
+      return { content: `Error: ${message}`, error: message, outcome: TOOL_OUTCOME.FAILED };
     }
     const rule = await this.#confirmationRule(call, tool);
     if (rule !== null) {
@@ -5208,7 +5222,11 @@ export class AgUiChat extends HTMLElement {
         const message = this.#strings.declinedAction;
         card.settle(TOOL_CALL_STATUS.DECLINED, message);
         this.#showPending();
-        return { content: message };
+        // The one outcome with no error text and no server involvement at all:
+        // a person said no in this browser. Nothing else records that, so
+        // without the annotation the reload showed a green card for an action
+        // the user had explicitly refused.
+        return { content: message, outcome: TOOL_OUTCOME.DENIED };
       }
     }
     // A navigating tool reloads only without a client-side router; with a
@@ -5251,7 +5269,7 @@ export class AgUiChat extends HTMLElement {
       const message = error instanceof Error ? error.message : String(error);
       card.settle(TOOL_CALL_STATUS.ERROR, message);
       this.#showPending();
-      return { content: `Error: ${message}`, error: message };
+      return { content: `Error: ${message}`, error: message, outcome: TOOL_OUTCOME.FAILED };
     }
   }
 
@@ -5516,12 +5534,18 @@ export class AgUiChat extends HTMLElement {
         // got for compaction, one handler up.
         this.#appendNotice("\u{1F504}", this.#strings.historyReplaced, "history-replaced");
       },
-      onToolResult: (toolCallId, content) => {
+      onToolResult: (toolCallId, content, outcome) => {
         const card = this.#toolCards.get(toolCallId);
         if (card === undefined) {
           return;
         }
-        card.settle(TOOL_CALL_STATUS.DONE, content);
+        // Settled as the server says it ended, not as "it ended". This path used
+        // to pass DONE unconditionally, so a refusal arrived as a green card
+        // with the reason folded inside it -- a booking the server declined
+        // read, at a glance, as a booking that was made. An absent or
+        // unrecognised outcome still means DONE, so every server written before
+        // the field existed renders exactly as it did.
+        card.settle(toolStatusFromOutcome(outcome), content);
         this.#serverSettled.add(toolCallId);
         // The card stops being the live thing the moment it settles, and the
         // server goes straight back to the model with the result -- a wait with

package/src/core/agui_client.ts

@@ -8,6 +8,7 @@ import {
 import type { Context, Interrupt, Message, ResumeEntry, Tool } from "@ag-ui/core";
 import { MAX_TOOL_ROUNDS } from "../constants.js";
 import type { AttachmentRef } from "./attachment.js";
+import type { ToolOutcome } from "./tool_outcome.js";
 
 /** A tool call surfaced to the host by {@link AgUiClient}. */
 export interface AgUiToolCall {
@@ -22,6 +23,18 @@ export interface ToolExecution {
   content: string;
   /** Present when the handler failed; surfaced for logging. */
   error?: string;
+  /**
+   * How the call ended, in the same vocabulary a server states on
+   * `TOOL_CALL_RESULT`. Omit for a success -- absent *is* success, here for the
+   * same reason it is on the wire.
+   *
+   * Distinct from {@link error}, which is a *message* and only exists for the
+   * one failure shape that produces one. A refusal has no error and is still
+   * not a success, and that is the case this field exists for: without it a
+   * declined call was persisted as an ordinary result and came back from a
+   * reload as a green card.
+   */
+  outcome?: ToolOutcome;
   /**
    * When `true`, a navigating tool triggered a page reload. The loop stops
    * without appending a result — the result is supplied after the next mount
@@ -76,8 +89,19 @@ export interface AgUiClientHandlers {
    * Fired when a server-side tool's result streams back (AG-UI's
    * `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.
+   *
+   * Added as a third parameter rather than as a new callback, so an
+   * implementation written against the two-parameter form still satisfies this
+   * interface and still behaves exactly as it did — which is the same
+   * backwards-compatibility promise the wire field makes.
    */
-  onToolResult(toolCallId: string, content: string): void;
+  onToolResult(toolCallId: string, content: string, outcome?: unknown): void;
   /**
    * Fired for AG-UI activity events — ambient notices about what the *run* did,
    * as opposed to work the agent asked for. `django-ag-ui` emits one with
@@ -259,6 +283,25 @@ 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.
+   */
+  readonly #outcomes = new Map<string, string>();
   readonly #connectionLostMessage: string;
   readonly #maxToolRounds: number;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
@@ -334,7 +377,7 @@ export class AgUiClient {
       (message as { attachments?: readonly AttachmentRef[] }).attachments = attachments;
     }
     this.#agent.addMessage(message);
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
     await this.#run();
   }
 
@@ -373,7 +416,7 @@ export class AgUiClient {
     }
     const kept = messages.slice(0, lastUser + 1);
     this.#agent.setMessages(kept);
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
     return kept;
   }
 
@@ -389,7 +432,7 @@ export class AgUiClient {
   /** Append a frontend tool result to history (used by the resume path). */
   addToolResult(toolCallId: string, content: string): void {
     this.#agent.addMessage({ id: randomUUID(), role: "tool", content, toolCallId });
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
   }
 
   /**
@@ -428,10 +471,42 @@ export class AgUiClient {
   #onCancelled(): void {
     // Persist so the truncated exchange, partial assistant text included,
     // survives a reload.
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
     this.#handlers.onCancelled();
   }
 
+  /**
+   * Hand the transcript to the host's store, annotated with what {@link #outcomes}
+   * knows about how each tool call ended.
+   *
+   * 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.
+   */
+  #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);
+      }),
+    );
+  }
+
   async #runLoop(): Promise<void> {
     // Carries resolved approval answers into the next run when a round finished
     // on a server-side-tool interrupt. Distinct from the public resume(), which
@@ -455,7 +530,7 @@ export class AgUiClient {
       }
       await this.#agent.runAgent(params, this.#buildSubscriber(pending, runState));
       resume = undefined;
-      this.#onPersist(this.#agent.messages);
+      this.#persist();
       // Cancelled mid-stream: don't execute the tool calls collected before the
       // abort.
       if (this.#cancelled) {
@@ -503,13 +578,21 @@ 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);
+        }
         this.#agent.addMessage({
           id: randomUUID(),
           role: "tool",
           content: result.content,
           toolCallId: call.id,
         });
-        this.#onPersist(this.#agent.messages);
+        this.#persist();
         executed = true;
       }
       if (!executed) {
@@ -521,6 +604,7 @@ 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;
@@ -562,7 +646,20 @@ export class AgUiClient {
         h.onToolCall(call);
       },
       onToolCallResultEvent({ event }) {
-        h.onToolResult(event.toolCallId, event.content);
+        // 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);
       },
       onActivitySnapshotEvent({ event, messages }) {
         // A snapshot for an id already in the list is a replacement, not a new

package/src/core/tool_outcome.ts

@@ -0,0 +1,36 @@
+import { TOOL_CALL_STATUS, TOOL_OUTCOME } from "../constants.js";
+import type { SettledStatus } from "../ui/tool_call_card.js";
+
+/**
+ * How a tool call ended, in the wire's own words. See {@link TOOL_OUTCOME}.
+ *
+ * Absent is the fourth case and the common one: a server that has never heard
+ * of the field says nothing, and nothing means success.
+ */
+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.
+ *
+ * **Everything unrecognised maps to `DONE`.** Not because unknown values are
+ * expected to be successes, but because the alternative is worse in the
+ * direction that matters: a card claiming a call failed when it did not is a
+ * lie the user acts on, while a card claiming success has at least the result
+ * text under it for them to read. `interrupted` is the concrete case today --
+ * pydantic-ai emits it, this vocabulary does not carry it, and a future release
+ * may add more. Forward compatibility is the point of the open field.
+ */
+export function toolStatusFromOutcome(outcome: unknown): SettledStatus {
+  if (outcome === TOOL_OUTCOME.FAILED) {
+    return TOOL_CALL_STATUS.ERROR;
+  }
+  if (outcome === TOOL_OUTCOME.DENIED) {
+    return TOOL_CALL_STATUS.DECLINED;
+  }
+  return TOOL_CALL_STATUS.DONE;
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
+  TOOL_OUTCOME,
   UNREAD_EVENT,
   X_CONFIRM_KEY,
   X_DESTRUCTIVE_KEY,
@@ -69,6 +70,7 @@ export {
 export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
 export { RemoteConversationStore } from "./core/remote_conversation_store.js";
 export { RunIndex, type RunRow } from "./core/run_index.js";
+export { type ToolOutcome, toolStatusFromOutcome } from "./core/tool_outcome.js";
 export {
   type TranscribeHandler,
   type TranscribeOptions,

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.35.1";
+export const VERSION: string = "0.36.0";