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

package/src/core/agui_client.ts

@@ -6,9 +6,10 @@ import {
   randomUUID,
 } from "@ag-ui/client";
 import type { Context, Interrupt, Message, ResumeEntry, Tool } from "@ag-ui/core";
-import { MAX_TOOL_ROUNDS } from "../constants.js";
+import { MAX_TOOL_ROUNDS, TOOL_OUTCOME } from "../constants.js";
 import type { AttachmentRef } from "./attachment.js";
 import type { ToolOutcome } from "./tool_outcome.js";
+import { answerUnansweredCalls } from "./utils.js";
 
 /** A tool call surfaced to the host by {@link AgUiClient}. */
 export interface AgUiToolCall {
@@ -231,6 +232,22 @@ export interface AgUiClientConfig extends AgUiRunInputs {
    * passes its localized string.
    */
   connectionLostMessage?: string;
+  /**
+   * Result content for a tool call the conversation moved past without one: a
+   * Stop while the stream was arriving, a round that ended on `RUN_ERROR`, a
+   * call no {@link executeTool} answered, or history restored with a call still
+   * open. Sent to the agent, so it says only that the call did not finish --
+   * nobody refused it. Defaults to an English sentence; the host passes its
+   * localized string.
+   */
+  unfinishedMessage?: string;
+  /**
+   * Result content for a server-side approval that Stop closed while it was
+   * open, which the host's {@link resolveInterrupts} answers as declined.
+   * Defaults to `"User declined the action."`; the host passes its localized
+   * string.
+   */
+  declinedMessage?: string;
   /**
    * Upper bound on frontend tool-call to re-run rounds within one
    * {@link AgUiClient.send}. Defaults to {@link MAX_TOOL_ROUNDS}.
@@ -300,9 +317,15 @@ export class AgUiClient {
    * 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, string>();
+  readonly #outcomes = new Map<string, unknown>();
   readonly #connectionLostMessage: string;
+  readonly #unfinishedMessage: string;
+  readonly #declinedMessage: string;
   readonly #maxToolRounds: number;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
   // a cancel between frontend-tool rounds doesn't start another round.
@@ -317,12 +340,17 @@ export class AgUiClient {
     this.#resolveInterrupts = config.resolveInterrupts ?? null;
     this.#onPersist = config.onPersist ?? (() => {});
     this.#connectionLostMessage = config.connectionLostMessage ?? "Connection lost";
+    this.#unfinishedMessage =
+      config.unfinishedMessage ??
+      "Not finished: the run ended or moved on before this tool call returned a result.";
+    this.#declinedMessage = config.declinedMessage ?? "User declined the action.";
     // Validated here rather than at each caller, so the element's attribute and
     // a direct consumer get the same answer. A bound below one -- or a NaN from
     // an unparseable attribute -- is not a smaller budget but a send that runs
     // 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();
     const onStateChanged = config.onStateChanged;
     if (onStateChanged !== undefined) {
       // The agent applies STATE_SNAPSHOT / STATE_DELTA itself; subscribing is
@@ -475,6 +503,109 @@ export class AgUiClient {
     this.#handlers.onCancelled();
   }
 
+  /**
+   * Move the outcome annotations a restored history carries off the agent's
+   * messages and into {@link #outcomes}.
+   *
+   * 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.
+   *
+   * `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.
+   */
+  #adoptSeededOutcomes(): void {
+    const seeded = this.#agent.messages;
+    if (!seeded.some((message) => "outcome" in message)) {
+      return;
+    }
+    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;
+      }),
+    );
+  }
+
+  /**
+   * Give every tool call in history a result, before a request carries it.
+   *
+   * Called ahead of every `runAgent`, which makes it the one place the rule is
+   * kept for every way a call can be left open -- a live run's Stop or
+   * `RUN_ERROR`, a name no tool here owns, a server that sent no result -- and
+   * for a client seeded with a restored history just the same. The answer says
+   * the call did not finish rather than that anyone declined it: a person
+   * declined only where they were asked, and those answers are already here by
+   * the time this runs (see {@link #answerStoppedApprovals}).
+   *
+   * `resuming` names the calls the request is itself answering: a resumed
+   * 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.
+   */
+  #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 };
+      },
+      resuming,
+    );
+    if (answered !== messages) {
+      this.#agent.setMessages([...answered]);
+      this.#persist();
+    }
+  }
+
+  /**
+   * Answer, as declined, every approval that Stop closed as declined.
+   *
+   * Stop cancels the resume that would have told the server, so the decline the
+   * approval recorded reaches no one unless history carries it. Only calls the
+   * host's resolver answered `cancelled` are declined: a person who approved a
+   * call and then pressed Stop did not decline it, and
+   * {@link #answerUnansweredCalls} answers that one on the next request as not
+   * finished.
+   *
+   * The status check is held by "does not call an approved call declined, since
+   * nobody declined it" in `ag_ui_chat_unanswered_tool_calls.test.ts`; the
+   * `toolCallId` check is held by the type checker, since a result needs an id
+   * to answer.
+   */
+  #answerStoppedApprovals(
+    interrupts: readonly Interrupt[],
+    responses: Readonly<Record<string, InterruptResponse>>,
+  ): void {
+    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,
+        });
+      }
+    }
+    this.#persist();
+  }
+
   /**
    * Hand the transcript to the host's store, annotated with what {@link #outcomes}
    * knows about how each tool call ended.
@@ -484,27 +615,39 @@ export class AgUiClient {
    * unannotated save quietly threw the annotations away.
    */
   #persist(): void {
+    this.#onPersist(this.annotatedMessages);
+  }
+
+  /**
+   * 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.
+   *
+   * 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.
+   */
+  get annotatedMessages(): readonly Message[] {
     const messages = this.#agent.messages;
     if (this.#outcomes.size === 0) {
-      this.#onPersist(messages);
-      return;
+      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.
-    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);
-      }),
-    );
+    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);
+    });
   }
 
   async #runLoop(): Promise<void> {
@@ -513,6 +656,7 @@ export class AgUiClient {
     // continues an unfinished frontend-tool round after a page load; this stays
     // inside one #run().
     let resume: ResumeEntry[] | undefined;
+    let resuming: ReadonlySet<string> = new Set();
     for (let round = 0; round < this.#maxToolRounds; round += 1) {
       // A cancel during the previous round's tool execution lands here: the
       // running handler completed, but no further round starts.
@@ -528,8 +672,10 @@ export class AgUiClient {
       if (resume !== undefined) {
         params.resume = resume;
       }
+      this.#answerUnansweredCalls(resuming);
       await this.#agent.runAgent(params, this.#buildSubscriber(pending, runState));
       resume = undefined;
+      resuming = new Set();
       this.#persist();
       // Cancelled mid-stream: don't execute the tool calls collected before the
       // abort.
@@ -559,9 +705,11 @@ export class AgUiClient {
         }
         const responses = await this.#resolveInterrupts(runState.interrupts);
         if (this.#cancelled) {
+          this.#answerStoppedApprovals(runState.interrupts, responses);
           return;
         }
         resume = buildResumeArray(runState.interrupts, responses);
+        resuming = new Set(runState.interrupts.flatMap(({ toolCallId }) => toolCallId ?? []));
         continue;
       }
       if (this.#executeTool === null || pending.length === 0) {
@@ -569,6 +717,14 @@ export class AgUiClient {
       }
       let executed = false;
       for (const call of pending) {
+        // A cancel while an earlier call in this round ran lands here. That
+        // handler could not be aborted and its result is kept, but the calls
+        // after it have not started, and a person who pressed Stop during the
+        // first page action did not ask for the second. They are answered as not
+        // finished before the next request.
+        if (this.#cancelled) {
+          return;
+        }
         const result = await this.#executeTool(call);
         if (result === null) {
           continue;

package/src/core/client_seed.ts

@@ -0,0 +1,27 @@
+import type { Message } from "@ag-ui/core";
+
+/**
+ * What differs between the clients one conversation builds -- its own, and one
+ * per checkpoint continuation. Everything else about a client comes from the
+ * element's single construction, so an option added for one reaches the other.
+ */
+export interface ClientSeed {
+  /** Where the client's runs are sent. */
+  readonly endpoint: string;
+  /** The history the agent starts from, and sends with its first run. */
+  readonly initialMessages: readonly Message[];
+  /**
+   * 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/read_max_tool_rounds.ts

@@ -0,0 +1,13 @@
+import { MAX_TOOL_ROUNDS } from "../constants.js";
+
+/**
+ * The tool-round budget from `element`'s `data-max-tool-rounds`, for one send.
+ *
+ * Anything unparseable becomes `NaN`, which {@link AgUiClient} rejects along
+ * with a bound below one -- so the two ways of setting this are validated in
+ * one place rather than agreeing by coincidence.
+ */
+export function readMaxToolRounds(element: Element): number {
+  const attr = element.getAttribute("data-max-tool-rounds");
+  return attr === null ? MAX_TOOL_ROUNDS : Number.parseInt(attr, 10);
+}

package/src/core/remote_conversation_store.ts

@@ -165,7 +165,7 @@ export class RemoteConversationStore implements ClientConversationStore {
     }
     // A 200 whose body isn't JSON (a proxy's HTML error page, a truncated
     // stream) must not throw an unhandled rejection that the caller's
-    // `void #rehydrate()` swallows; fall back to the local cache.
+    // `void rehydrate()` swallows; fall back to the local cache.
     const body = await this.#readJson<{ messages?: readonly Message[] }>(response);
     if (body === null) {
       return this.#local.loadMessages(threadId);