@artooi/ag-ui-web-component 0.41.2 → 0.42.0

package/src/core/agui_client.ts

@@ -55,8 +55,11 @@ export interface ToolExecution {
  * Executes a frontend tool call.
  *
  * Returns the {@link ToolExecution} to post back to the agent, or `null` when
- * the call is not a frontend tool the host owns — a server-side tool the server
- * already executed, which the client must not re-run.
+ * there is nothing to post: the call is not a frontend tool the host owns (a
+ * server-side tool the server already executed, which the client must not
+ * re-run), or its run was stopped or handed over while the call waited. A
+ * stopped call is left unanswered here, like the calls after it in the round,
+ * and the next request answers it as not finished.
  */
 export type ExecuteTool = (call: AgUiToolCall) => Promise<ToolExecution | null>;
 
@@ -317,8 +320,10 @@ export class AgUiClient {
   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.
+  // Set by cancel(); reset as send() or resume() begins, before either runs
+  // any host code. Checked by the loop so a cancel between frontend-tool
+  // rounds doesn't start another round, and again just before each request,
+  // so a cancel from host code the round itself runs is not sent anyway.
   #cancelled = false;
 
   constructor(config: AgUiClientConfig) {
@@ -388,6 +393,12 @@ export class AgUiClient {
    * {@link messageAttachments}.
    */
   async send(content: string, attachments: readonly AttachmentRef[] = []): Promise<void> {
+    // A new interaction, so the Stop of the one before it is forgotten here --
+    // ahead of the save below, which is the host's store. Forgotten as the run
+    // began instead, a Stop that store made (a new chat started from the save)
+    // was erased before anything read it, and the turn went out regardless,
+    // into the conversation being left and with all of its history.
+    this.#cancelled = false;
     // 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
@@ -410,11 +421,14 @@ export class AgUiClient {
    * can be asked again.
    *
    * Returns the retained history, or `null` when there is nothing to retry (no
-   * user message has been sent yet). **Truncates only** -- the caller re-renders
-   * from the returned list and then calls {@link resume}, because the transcript
-   * belongs to the element and a client that reached into it would own two
-   * things. Running here instead would stream the new answer in underneath the
-   * old one.
+   * user message has been sent yet). The shortened history is saved before it
+   * replaces the current one, so a save that throws changes nothing and the
+   * throw propagates.
+   *
+   * **Truncates only** -- the caller re-renders from the returned list and then
+   * calls {@link resume}, because the transcript belongs to the element and a
+   * client that reached into it would own two things. Running here instead
+   * would stream the new answer in underneath the old one.
    *
    * Re-running answers the question the agent was last asked, rather than
    * telling it its answer was wrong, which is what makes the result a
@@ -439,8 +453,15 @@ export class AgUiClient {
       return null;
     }
     const kept = messages.slice(0, lastUser + 1);
+    // Saved before the history is shortened, so a store that throws leaves it
+    // as it was and the throw reaches the caller, as a refused save does from
+    // send(). Shortened first, the refusal left this client without the answer
+    // while the caller's transcript still showed it, and the next request then
+    // asked a follow-up about something the agent was never told it had said.
+    // Handed over directly rather than through #persist, which saves the list
+    // the agent holds, because the agent does not hold this one yet.
+    this.#onPersist(kept);
     this.#agent.setMessages(kept);
-    this.#persist();
     return kept;
   }
 
@@ -450,6 +471,10 @@ export class AgUiClient {
    * message; it continues the conversation already in history.
    */
   async resume(): Promise<void> {
+    // A new interaction, as in send(). No host code runs between here and the
+    // loop, so for a resume this is the same moment the run used to forget a
+    // Stop at; it moved here so that both ways in forget it in one place.
+    this.#cancelled = false;
     await this.#run();
   }
 
@@ -465,6 +490,13 @@ export class AgUiClient {
    * disconnect). Safe to call with no run in flight. Partial text already
    * streamed stays in history; {@link AgUiClientHandlers.onCancelled} fires
    * instead of `onError`, and `onSettled` still follows.
+   *
+   * Also stops a {@link send} or {@link resume} whose request has not been made
+   * yet, when host code it runs on the way calls this: the save of the turn,
+   * the tool and context providers, the save answering a call left open. No
+   * request is made then, and `onCancelled` and `onSettled` fire as for any
+   * other Stop. A cancel with nothing in flight is forgotten when the next
+   * send or resume begins.
    */
   cancel(): void {
     this.#cancelled = true;
@@ -472,7 +504,6 @@ export class AgUiClient {
   }
 
   async #run(): Promise<void> {
-    this.#cancelled = false;
     try {
       await this.#runLoop();
       // `@ag-ui/client` filters abort errors inside `runAgent` (it resolves
@@ -637,7 +668,10 @@ export class AgUiClient {
     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.
+      // running handler completed, but no further round starts. The check
+      // before the request below would stop the round as well; this one keeps
+      // a stopped loop from running the providers and the store for a round
+      // it will not send.
       if (this.#cancelled) {
         return;
       }
@@ -651,6 +685,15 @@ export class AgUiClient {
         params.resume = resume;
       }
       this.#answerUnansweredCalls(resuming);
+      // Everything above since the check at the top is host code -- the tool
+      // and context providers, and the store saving the answers just made -- and
+      // any of it can be what stopped the run, by starting a new chat or
+      // changing the principal. `@ag-ui/client` makes a fresh abort controller
+      // for each run, so the abort `cancel()` made in that time reached
+      // nothing, and only this check keeps the request from going out.
+      if (this.#cancelled) {
+        return;
+      }
       await this.#agent.runAgent(params, this.#buildSubscriber(pending, runState));
       resume = undefined;
       resuming = new Set();

package/src/core/storage_scope.ts

@@ -53,9 +53,12 @@ export class StorageScope {
   // remounts, but re-resolves if the host answers the warning with an `id`.
   #generatedNs = "";
   #generatedFor = "";
-  // The `sessionStorage`-backed store, which the element may therefore re-scope
-  // on a principal change. `null` when the host injected a store of its own
-  // kind, whose keying the element does not know and must not guess at.
+  // The `sessionStorage`-backed store this scope handed out, which the element
+  // may therefore re-scope on a principal change -- while it is still the store
+  // in use, which rescopeStore asks, since a host can assign its own at any
+  // time. `null` until connecting has met the built-in store at all. A store of
+  // the host's own kind is never held here: the element does not know its
+  // keying and must not guess at it.
   #builtinStore: SessionStorageStore | null = null;
 
   constructor(host: StorageScopeHost) {
@@ -115,12 +118,22 @@ export class StorageScope {
   }
 
   /**
-   * Rebuild the built-in store under `namespace`, or `null` for a store of the
-   * host's own kind, which holds its data somewhere the element cannot see and
-   * has to scope itself.
+   * Rebuild the built-in store under `namespace`, or `null` when `current` --
+   * the store the element is using now, unwrapped from any remote it wrapped
+   * it in -- is not the one this scope handed out.
+   *
+   * Asked of the store in use rather than of what connecting remembered,
+   * because the two part company the moment a host assigns a store of its own
+   * to a connected element. Remembering was enough to tell a host's store from
+   * the built-in one at connect; after it, the built-in one was still
+   * remembered, so a key change replaced the host's store with a fresh
+   * `sessionStorage` one -- and a host that had chosen to keep message bodies
+   * off the client found every one of them cached in the tab again. A store
+   * the element did not make holds its data somewhere the element cannot see,
+   * and has to scope itself.
    */
-  rescopeStore(namespace: string): SessionStorageStore | null {
-    if (this.#builtinStore === null) {
+  rescopeStore(current: ClientConversationStore, namespace: string): SessionStorageStore | null {
+    if (current !== this.#builtinStore) {
       return null;
     }
     this.#builtinStore = new SessionStorageStore(namespace);

package/src/tools/tool_dispatch.ts

@@ -14,6 +14,7 @@ import {
   requestConfirmation,
 } from "../ui/interrupts/confirmation_card.js";
 import type { PendingDecision } from "../ui/interrupts/pending_decision.js";
+import type { ToolCallCard } from "../ui/progress/tool_call_card.js";
 import type { Transcript } from "../ui/transcript/transcript.js";
 import type { UiStrings } from "../ui/ui_strings.js";
 import type { ClientTool } from "./client_tool_registry.js";
@@ -56,6 +57,13 @@ export interface ToolDispatchHost {
   readonly conversationStore: () => ClientConversationStore;
   /** The active thread's id. */
   readonly threadId: () => string;
+  /**
+   * The element's current tenure: an identity it replaces on every handover
+   * from one principal to another, and never otherwise. Only ever compared, so
+   * a call can tell whether the principal it was dispatched for is still the
+   * one the element serves.
+   */
+  readonly tenure: () => object;
 }
 
 /**
@@ -118,6 +126,12 @@ export class ToolDispatch {
    * Execute one frontend tool call the round produced, against its own card:
    * refused when the page moved under the round, asked about when a rule gates
    * it, and settled with what the handler returned or threw.
+   *
+   * Every await below is a place the run can end, so each is followed by a
+   * check that it has not. A Stop while the host's predicate is pending ends
+   * the call there, and one while the card is open declines it. A handover
+   * during any of the three leaves the call with no transcript to draw in and
+   * no store to write to, so it does neither.
    */
   async execute(call: AgUiToolCall): Promise<ToolExecution | null> {
     // A skill load already rendered as a notice on the stream; it is never a
@@ -126,6 +140,15 @@ export class ToolDispatch {
     if (skillNameFrom(call) !== null) {
       return null;
     }
+    // Fixed here, as the call is dispatched, rather than read when they are
+    // used. The client calls this in the same task as its own check that the
+    // run was not stopped, so these are the run's principal and thread; read
+    // after the handler instead, they were whoever was current by then. A
+    // navigating handler's failure cleared the checkpoint of the thread New
+    // chat had just moved to, leaving its own behind, and across a handover
+    // it wrote into the next principal's store.
+    const tenure = this.#host.tenure();
+    const threadId = this.#host.threadId();
     const card = this.#host.transcript.cardFor(call);
     this.#host.transcript.forgetCard(call.id);
     // Kept after the card leaves the awaiting cards: a tool that renders into the
@@ -180,7 +203,23 @@ export class ToolDispatch {
       // lives only in the DOM, and the DOM is what a reload throws away.
       return { content: `Error: ${message}`, error: message, outcome: TOOL_OUTCOME.FAILED };
     }
+    // The run is suspended on the host's predicate as much as on a card, and a
+    // predicate is free to take as long as one: it may ask a server. So the
+    // wait is opened for it the same way, and a Stop -- or a handover, which
+    // stops the run first -- aborts it. Unchecked, a predicate that answered
+    // after the Stop opened its card or ran its handler for a run the user had
+    // ended, and after a handover it ran the previous principal's handler on
+    // the next principal's page.
+    //
+    // Held by "draws no card when the predicate answers after Stop", and for
+    // the handover by "does not run the previous principal's handler after a
+    // handover", in tool_dispatch.test.ts.
+    const asking = this.#host.decision.open();
     const rule = await this.#confirmationRule(call, tool);
+    this.#host.decision.close();
+    if (asking.aborted) {
+      return this.#abandoned(card);
+    }
     if (rule === "unanswered") {
       // Settled as a refusal and returned as one, so the run carries on to its
       // next round the way it does after a decline and the agent can say what
@@ -216,6 +255,17 @@ export class ToolDispatch {
       this.#host.transcript.follow();
       const accepted = await decision;
       this.#host.decision.close();
+      // A handover while the card was open declines it, as any Stop does, but
+      // the transcript the decline would be drawn into is the next principal's
+      // by now, and the client the refusal goes to writes nothing for a tenure
+      // that has ended. Unchecked, the pending indicator the decline shows was
+      // left in the next principal's empty transcript with nothing to remove it.
+      //
+      // Held by "draws nothing for the next principal when a handover declines
+      // the card" in tool_dispatch.test.ts.
+      if (this.#host.tenure() !== tenure) {
+        return null;
+      }
       card.recordDecision(accepted ? "approved" : "declined");
       if (!accepted) {
         const message = this.#host.strings().declinedAction;
@@ -227,6 +277,18 @@ export class ToolDispatch {
         // the user had explicitly refused.
         return { content: message, outcome: TOOL_OUTCOME.DENIED };
       }
+      // Answered yes, and then stopped before that answer was heard: a click
+      // on Confirm and a Stop in the same task, so the card had already
+      // resolved by the time the abort reached it. The person agreed to the
+      // call, so it is not declined; the run it belonged to is over, so it does
+      // not run either. The server-side gate treats approve-then-Stop the same
+      // way.
+      //
+      // Held by "does not run a call confirmed in the same task as Stop" in
+      // tool_dispatch.test.ts.
+      if (signal.aborted) {
+        return this.#abandoned(card);
+      }
     }
     // A navigating tool reloads only without a client-side router; with a
     // host `navigate()` (SPA) it routes in-page and the loop just continues.
@@ -235,12 +297,30 @@ export class ToolDispatch {
       // Checkpoint before the handler reloads the page; the history (incl.
       // this tool call) was already persisted when the run that produced it
       // settled. The result is supplied on the next mount via the resume path.
-      this.#host.conversationStore().saveCheckpoint(this.#host.threadId(), { toolCallId: call.id });
+      //
+      // Nothing has been awaited since the last check that the run is still
+      // going, so the live thread is the dispatch one here too. Written under
+      // the dispatch thread all the same, so the clear below is certain to
+      // remove what this wrote.
+      this.#host.conversationStore().saveCheckpoint(threadId, { toolCallId: call.id });
     }
     try {
       // The call id lets a handler that renders into the transcript find its
       // own card; handlers that only act on the page ignore it.
       const result = await tool.handler(call.args, call.id);
+      // A handler cannot be aborted, and a plain Stop while it ran keeps its
+      // result: the action happened on the page, and the agent is told so on
+      // the next request. A handover is different. The transcript this would
+      // draw into is the next principal's now, and the client the result goes
+      // to writes nothing for a tenure that has ended, so the result has no
+      // one left to reach. Unchecked, the pending indicator was drawn into the
+      // next principal's empty transcript, where nothing would ever remove it.
+      //
+      // Held by "draws nothing for the next principal when a handler resolves
+      // after a handover" in tool_dispatch.test.ts.
+      if (this.#host.tenure() !== tenure) {
+        return null;
+      }
       // Drawn from the arguments rather than the result, so the live path and
       // the replay path render the same thing from the same input.
       if (tool.render !== undefined) {
@@ -255,9 +335,20 @@ export class ToolDispatch {
       this.#host.transcript.showPending();
       return { content };
     } catch (error) {
+      // The same handover check as on success, and here it also guards a
+      // write: the store is read live, and after a handover it is the next
+      // principal's, so the clear below removed their checkpoint rather than
+      // this call's -- which the handover's purge had already removed.
+      //
+      // Held by "leaves the next principal's checkpoint alone when a handler
+      // fails after a handover" in tool_dispatch.test.ts.
+      if (this.#host.tenure() !== tenure) {
+        return null;
+      }
       if (navigates) {
-        // The navigation never happened; drop the dangling checkpoint.
-        this.#host.conversationStore().saveCheckpoint(this.#host.threadId(), null);
+        // The navigation never happened; drop the dangling checkpoint, from
+        // the thread it was written to.
+        this.#host.conversationStore().saveCheckpoint(threadId, null);
       }
       // The handler's own message, verbatim, in two places at once: the card,
       // which the user sees, and the tool result, which goes to the endpoint,
@@ -479,6 +570,26 @@ export class ToolDispatch {
     return isDestructive(tool.parameters) ? "destructive" : null;
   }
 
+  /**
+   * Settle a call whose run ended while it waited, and give the loop nothing.
+   *
+   * The card is settled here because nothing else will: dispatch took it out
+   * of the end-of-run sweep before it waited, so left alone it read "running…"
+   * for good. It says the call did not finish, which is true -- nothing ran and
+   * nobody refused it.
+   *
+   * `null` rather than a result, because a stopped run has no next round to
+   * send one in. The loop moves on and finds the run stopped, and the call is
+   * left unanswered like every call after it in the round, so the client
+   * answers it as not finished on the next request -- in the same words as
+   * this card. After a handover the card is in a transcript already cleared,
+   * and settling it there is seen by no one.
+   */
+  #abandoned(card: ToolCallCard): null {
+    card.settle(TOOL_CALL_STATUS.INTERRUPTED, this.#host.strings().callNotFinished);
+    return null;
+  }
+
   /**
    * Whether the page moved since the current round's context was built.
    *

package/src/ui/composer/voice_input.ts

@@ -100,6 +100,16 @@ export class VoiceInput {
       this.#fail(this.#strings.transcriptionFailed);
       return;
     }
+    if (this.#disposed) {
+      // The permission prompt outlived the control: the element left, or
+      // user-key changed, while it was open. Recording now would light the
+      // browser's indicator for a button nobody can see or stop, and dispose
+      // has already run, so nothing else would ever release these tracks.
+      for (const track of stream.getTracks()) {
+        track.stop();
+      }
+      return;
+    }
     this.#stream = stream;
     this.#chunks = [];
     this.#hitCap = false;
@@ -136,10 +146,16 @@ export class VoiceInput {
   }
 
   /**
-   * Tear the control down, for a host element removed mid-recording. Stops any
-   * live `MediaRecorder`, releases the mic tracks so the browser's recording
-   * indicator clears, and suppresses the pending transcription — a
-   * disconnected control must not fire `onText` into a detached element.
+   * Tear the control down, for a host element removed mid-recording or handed
+   * to the next principal. Stops any live `MediaRecorder`, releases the mic
+   * tracks so the browser's recording indicator clears, and suppresses the
+   * pending transcription — a disconnected control must not fire `onText` into
+   * a detached element.
+   *
+   * Disposal is final: nothing un-disposes an instance, and the host's next
+   * wiring builds a new one. So the disposed flag alone tells a stale
+   * continuation from a live one, and a clip already posted when this runs is
+   * dropped whenever its answer arrives.
    */
   dispose(): void {
     this.#disposed = true;
@@ -160,6 +176,15 @@ export class VoiceInput {
     const audio = new Blob(this.#chunks, { type: mimeType || "audio/webm" });
     try {
       const text = await this.#transcribe(audio);
+      if (this.#disposed) {
+        // Disposed while the clip was in flight. The check above ran before the
+        // await and cannot see this: on a change of user-key the host disposes
+        // and wires a fresh mic over the same composer, so delivering now
+        // would put the previous principal's words in the next one's box.
+        // The button is left as it was, too: it is no longer this control's
+        // to change.
+        return;
+      }
       this.#setState("idle");
       if (this.#hitCap) {
         // #setState has just reset the tooltip to the idle label, so this goes
@@ -188,6 +213,12 @@ export class VoiceInput {
   }
 
   #fail(message: string): void {
+    // Both callers reach here after an await, a permission prompt or a
+    // transcription, either of which can settle after dispose. A disposed
+    // control has nothing to release and no tooltip to draw.
+    if (this.#disposed) {
+      return;
+    }
     this.#releaseStream();
     this.#recorder = null;
     this.#setState("idle");