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

package/src/core/agui_client.ts

@@ -615,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> {

package/src/core/client_seed.ts

@@ -10,6 +10,18 @@ export interface ClientSeed {
   readonly endpoint: string;
   /** The history the agent starts from, and sends with its first run. */
   readonly initialMessages: readonly Message[];
-  /** Whether the client writes its messages to the conversation store. */
-  readonly persist: boolean;
+  /**
+   * 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/tools/tool_catalog.ts

@@ -264,13 +264,13 @@ export class ToolCatalog {
           },
           required: ["question"],
         },
-        handler: (args) => this.#askUser(args),
+        handler: (args, callId) => this.#askUser(args, callId),
       },
     ];
   }
 
   /** Render the `ask_user` question card and resolve with the user's answer. */
-  async #askUser(args: Record<string, unknown>): Promise<string> {
+  async #askUser(args: Record<string, unknown>, callId: string | undefined): Promise<string> {
     const question = typeof args["question"] === "string" ? args["question"] : "";
     const request: QuestionRequest = { question };
     const rawOptions = args["options"];
@@ -284,20 +284,71 @@ export class ToolCatalog {
     // it with an empty answer (the run is then cancelled).
     const signal = this.#host.decision.open();
     this.#host.hidePending();
-    // A host-supplied renderer takes full control of the UI; otherwise the
-    // built-in inline card renders into the current answer group.
+    // The built-in inline card renders into the current answer group.
+    const builtIn = (): Promise<string> =>
+      requestQuestion(this.#host.ensureGroup(), request, {
+        signal,
+        strings: this.#host.strings(),
+      });
+    // A host-supplied renderer takes full control of the UI.
     const renderer = this.#host.askUserRenderer();
-    const answer =
-      renderer !== null
-        ? // Called on the element, as `this.askUserRenderer(...)` always was.
-          await renderer.call(this.#host.element, request, { signal })
-        : await requestQuestion(this.#host.ensureGroup(), request, {
-            signal,
-            strings: this.#host.strings(),
-          });
+    let answer: string;
+    if (renderer === null) {
+      answer = await builtIn();
+    } else {
+      // Awaited here rather than inside a helper, so an answering renderer
+      // takes exactly as many turns to be heard as it always did.
+      try {
+        // Called on the element, as `this.askUserRenderer(...)` always was.
+        answer = await renderer.call(this.#host.element, request, { signal });
+      } catch (error) {
+        answer = await this.#afterRendererFailed(error, signal, callId, builtIn);
+      }
+    }
     this.#host.decision.close();
     this.#host.updateEmptyState();
     this.#host.follow();
     return answer;
   }
+
+  /**
+   * Answer an `ask_user` call whose host renderer threw or rejected instead of
+   * answering: put the question to the built-in card.
+   *
+   * The same answer `approvalRenderer` gets for the same failure, and for the
+   * same reason: a renderer is presentation, not a policy. It decides how the
+   * question looks, never whether the agent's question is put to the user.
+   * Uncaught, the throw escaped the handler, so the call's card settled as an
+   * error quoting the host's message, that message went on to the agent as the
+   * tool result -- a detail of the host's page, never written for the model --
+   * and the pending decision was never closed, so the next Stop, in whatever
+   * round, aborted the signal of a wait that had already ended rather than
+   * finding nothing open. The built-in card still asks,
+   * and the run carries on as if no renderer had been set. Reported the way a
+   * failed `render` is, and for the same reason: survived is not the same as
+   * findable.
+   *
+   * Except when the wait was already abandoned. A renderer honouring its signal
+   * rejects once a Stop fires it, which is the signal working rather than the
+   * renderer failing, and a card drawn then would ask about a run the user just
+   * ended. So it resolves with the empty answer the built-in card resolves with
+   * on the same abort, and says nothing.
+   */
+  #afterRendererFailed(
+    error: unknown,
+    signal: AbortSignal,
+    callId: string | undefined,
+    builtIn: () => Promise<string>,
+  ): Promise<string> {
+    if (signal.aborted) {
+      return Promise.resolve("");
+    }
+    // Named by call rather than by question: the model can ask the same thing
+    // twice in one turn, and the id is the one thing that tells them apart.
+    console.warn(
+      `ag-ui-chat: askUserRenderer failed for tool call ${callId}, so the built-in question card asks instead`,
+      error,
+    );
+    return builtIn();
+  }
 }

package/src/ui/composer/composer_attachments.ts

@@ -57,8 +57,15 @@ export class ComposerAttachments {
    * built-in multipart endpoint: reveal the 📎 button, wire the hidden file
    * input + drag-and-drop, and mount the tray. With neither, the affordance
    * stays hidden and the chat degrades to text-only.
+   *
+   * Called on every connect, so it starts by taking down the tray the last
+   * connection mounted: that one was disposed when the element left, and the
+   * attributes that decide whether there is a tray at all may have changed
+   * since. The shell outlives a connection, so its listeners go under `signal`.
    */
-  wire(): void {
+  wire(signal: AbortSignal): void {
+    this.#tray?.element.remove();
+    this.#tray = null;
     const url = this.#host.element.getAttribute("data-attachments-url");
     const upload = this.#host.uploadHandler() ?? this.#defaultUploadHandler(url);
     if (upload === null) {
@@ -82,8 +89,8 @@ export class ComposerAttachments {
     this.#host.slot.appendChild(this.#tray.element);
     this.#host.fileInput.accept = accept;
     this.#host.button.hidden = false;
-    this.#enableDragAndDrop();
-    this.#enablePaste(tray);
+    this.#enableDragAndDrop(signal);
+    this.#enablePaste(tray, signal);
   }
 
   /** The queueing behind `AgUiChat.attachFile`, whose doc is the contract. */
@@ -136,25 +143,37 @@ export class ComposerAttachments {
   }
 
   /** Accept files dropped anywhere on the chat shell into the tray. */
-  #enableDragAndDrop(): void {
+  #enableDragAndDrop(signal: AbortSignal): void {
     const chat = this.#host.chat;
-    chat.addEventListener("dragover", (event) => {
-      event.preventDefault();
-      chat.classList.add("chat--dragover");
-    });
-    chat.addEventListener("dragleave", () => {
-      chat.classList.remove("chat--dragover");
-    });
-    chat.addEventListener("drop", (event) => {
-      event.preventDefault();
-      chat.classList.remove("chat--dragover");
-      const files = event.dataTransfer?.files;
-      if (files !== undefined) {
-        for (const file of Array.from(files)) {
-          this.#tray?.add(file);
+    chat.addEventListener(
+      "dragover",
+      (event) => {
+        event.preventDefault();
+        chat.classList.add("chat--dragover");
+      },
+      { signal },
+    );
+    chat.addEventListener(
+      "dragleave",
+      () => {
+        chat.classList.remove("chat--dragover");
+      },
+      { signal },
+    );
+    chat.addEventListener(
+      "drop",
+      (event) => {
+        event.preventDefault();
+        chat.classList.remove("chat--dragover");
+        const files = event.dataTransfer?.files;
+        if (files !== undefined) {
+          for (const file of Array.from(files)) {
+            this.#tray?.add(file);
+          }
         }
-      }
-    });
+      },
+      { signal },
+    );
   }
 
   /**
@@ -228,27 +247,31 @@ export class ComposerAttachments {
    * clipboard, and swallowing the words someone meant to paste in order to
    * attach a picture they did not is the worse of the two failures.
    */
-  #enablePaste(tray: AttachmentTray): void {
-    this.#host.chat.addEventListener("paste", (event: ClipboardEvent) => {
-      // Nullish rather than a null check: the property is typed as nullable,
-      // and an engine that fires a plain Event for a paste leaves it absent
-      // instead, which is not the same value and is the same situation.
-      const clipboard = event.clipboardData ?? null;
-      if (clipboard === null) {
-        return;
-      }
-      const files = Array.from(clipboard.files);
-      if (files.length === 0) {
-        this.#pasteLongTextAsFile(event, clipboard, tray);
-        return;
-      }
-      if (clipboard.getData("text/plain") === "") {
-        event.preventDefault();
-      }
-      for (const file of files) {
-        this.#tray?.add(named(file));
-      }
-    });
+  #enablePaste(tray: AttachmentTray, signal: AbortSignal): void {
+    this.#host.chat.addEventListener(
+      "paste",
+      (event: ClipboardEvent) => {
+        // Nullish rather than a null check: the property is typed as nullable,
+        // and an engine that fires a plain Event for a paste leaves it absent
+        // instead, which is not the same value and is the same situation.
+        const clipboard = event.clipboardData ?? null;
+        if (clipboard === null) {
+          return;
+        }
+        const files = Array.from(clipboard.files);
+        if (files.length === 0) {
+          this.#pasteLongTextAsFile(event, clipboard, tray);
+          return;
+        }
+        if (clipboard.getData("text/plain") === "") {
+          event.preventDefault();
+        }
+        for (const file of files) {
+          this.#tray?.add(named(file));
+        }
+      },
+      { signal },
+    );
   }
 
   /** Tell the host what the tray now holds — see {@link ATTACHMENT_EVENT}. */

package/src/ui/composer/composer_voice.ts

@@ -44,8 +44,13 @@ export class ComposerVoice {
    * built-in POST endpoint. The control records via `MediaRecorder` and drops
    * the transcript into the composer; with neither configured the mic stays
    * hidden and the chat is text-only.
+   *
+   * Called on every connect, so it starts by taking down the mic the last
+   * connection mounted, which was released when the element left.
    */
   wire(): void {
+    this.#voice?.element.remove();
+    this.#voice = null;
     const url = this.#host.element.getAttribute("data-transcribe-url");
     const transcribe = this.#host.transcribeHandler() ?? this.#defaultTranscribeHandler(url);
     if (transcribe === null) {

package/src/ui/excerpts/transcript_quote_offer.ts

@@ -99,8 +99,13 @@ export class TranscriptQuoteOffer {
     this.#pageQuote = null;
   }
 
-  /** Build the offer and listen for settled selections in the transcript. */
-  mount(): void {
+  /**
+   * Build the offer and listen for settled selections in the transcript.
+   *
+   * The button and the transcript outlive a connection, so the listeners go
+   * under `signal`, which the element aborts when it leaves the document.
+   */
+  mount(signal: AbortSignal): void {
     const button = this.button;
     button.className = "quote-selection";
     button.type = "button";
@@ -111,23 +116,31 @@ export class TranscriptQuoteOffer {
     // selection first, and by the time a click lands there is nothing left to
     // quote. Preventing the default keeps the selection alive long enough to
     // read it.
-    button.addEventListener("mousedown", (event) => {
-      event.preventDefault();
-    });
-    button.addEventListener("click", () => {
-      this.#host.quote(this.#quoting);
-      window.getSelection()?.removeAllRanges();
-      this.#hide();
-    });
+    button.addEventListener(
+      "mousedown",
+      (event) => {
+        event.preventDefault();
+      },
+      { signal },
+    );
+    button.addEventListener(
+      "click",
+      () => {
+        this.#host.quote(this.#quoting);
+        window.getSelection()?.removeAllRanges();
+        this.#hide();
+      },
+      { signal },
+    );
 
     // A settled selection, by either input. `mouseup` rather than
     // `selectionchange` so the offer does not chase the pointer mid-drag; the
     // second half of the same gesture, `mousedown`, retires the previous offer
     // before the new selection exists.
     const messages = this.#host.messages;
-    messages.addEventListener("mouseup", (event) => this.#onSelectionSettled(event));
-    messages.addEventListener("keyup", () => this.#onSelectionSettled());
-    messages.addEventListener("mousedown", () => this.#hide());
+    messages.addEventListener("mouseup", (event) => this.#onSelectionSettled(event), { signal });
+    messages.addEventListener("keyup", () => this.#onSelectionSettled(), { signal });
+    messages.addEventListener("mousedown", () => this.#hide(), { signal });
   }
 
   /** Whether the transcript offers to quote what the user selects. */

package/src/ui/history/conversation_history.ts

@@ -61,6 +61,17 @@ export interface ConversationHistoryHost {
   readonly appendMessage: (role: MessageRole, content: string) => HTMLDivElement;
   /** Resize the composer to its content. */
   readonly autoGrow: () => void;
+  /**
+   * A continuation has ended, whether or not it ever ran.
+   *
+   * The composer parks a turn typed while one is in flight, and learns a run
+   * has settled from its own events -- which never arrive for a continuation
+   * that failed before starting one. Without this, such a turn stayed parked
+   * with nothing left to release it.
+   */
+  readonly continuationEnded: () => void;
+  /** The conversation's own client, or `null` until one is built. */
+  readonly client: () => AgUiClient | null;
   /** The conversation's own client, built on first use. */
   readonly ensureClient: () => AgUiClient;
   /**
@@ -69,6 +80,14 @@ export interface ConversationHistoryHost {
    * added to one can be missing from the other.
    */
   readonly buildClient: (seed: ClientSeed) => AgUiClient;
+  /**
+   * Forget the conversation's own client, so the next one is built from
+   * {@link ConversationHistory.restored}. Nothing is cancelled: this is for a
+   * client that is not running.
+   */
+  readonly releaseClient: () => void;
+  /** Whether an interaction is in flight, which the composer owns. */
+  readonly running: () => boolean;
   /** Stop the in-flight run. */
   readonly cancelRun: () => void;
   /** Drop the in-memory run and transcript, leaving the thread untouched. */
@@ -97,10 +116,16 @@ export class ConversationHistory {
   /** The active thread's id. Empty until the element connects. */
   #threadId = "";
   /**
-   * The messages the last restore replayed, which seed the next client the
-   * element builds. Emptied with the rest of the in-memory run.
+   * The conversation as last written for the next client the element builds to
+   * start from: what the last restore replayed, or what a checkpoint
+   * continuation last saved after it. Emptied with the rest of the in-memory run.
    */
   #restored: readonly Message[] = [];
+  /**
+   * Counts the conversations cleared away, so a continuation can tell whether
+   * the one it continued is still on screen when it saves.
+   */
+  #cleared = 0;
   // Bumped on every rehydrate; a replay whose generation is stale (a newer
   // thread switch started while it awaited a slow store) drops its result.
   #generation = 0;
@@ -121,11 +146,16 @@ export class ConversationHistory {
     return this.#threadId;
   }
 
-  /** The messages the last restore replayed, for seeding the next client. */
+  /** The conversation as last written, for seeding the next client. */
   get restored(): readonly Message[] {
     return this.#restored;
   }
 
+  /** The checkpoint continuation in flight, or `null` when none is running. */
+  get continuation(): AgUiClient | null {
+    return this.#continuation;
+  }
+
   /** Point at the thread the store says is active. */
   adoptActiveThread(): void {
     this.#threadId = this.#host.conversationStore().threadId();
@@ -153,6 +183,9 @@ export class ConversationHistory {
   /** Forget the messages the last restore seeded, with the rest of the run. */
   forgetRestored(): void {
     this.#restored = [];
+    // The element clears the conversation through here, so a continuation
+    // still saving afterwards learns the conversation is no longer this one.
+    this.#cleared += 1;
   }
 
   /** Delete the active thread if nothing was ever sent in it. */
@@ -258,13 +291,18 @@ export class ConversationHistory {
    * Uses a short-lived agent pointed at the resume / fork endpoint and seeded
    * with no history, because those endpoints supply the prior turns from the
    * snapshot and re-sending them would duplicate. A separate agent makes that
-   * structural — the main agent keeps its own history — and mints the fresh
-   * `run_id` the endpoints also require.
+   * structural and mints the fresh `run_id` the endpoints also require.
    *
    * Built by the same construction as the conversation's own client, so the
    * continuation streams into the same transcript the user is looking at and
    * runs under the same state, tools and bounds. It is the run in flight while
    * it lasts: {@link stopContinuation} is how the element's Stop reaches it.
+   *
+   * What it adds joins the conversation. Its saves write the conversation on
+   * screen ahead of its exchange, and each one hands that whole list to the
+   * next client the element builds, so the next ordinary message is sent with
+   * the exchange it follows. The conversation's own client never held it, and
+   * was sending without it.
    */
   async continueRun(runId: string, verb: CheckpointVerb): Promise<void> {
     const index = this.runs();
@@ -275,6 +313,26 @@ export class ConversationHistory {
       // documented empty panel, which has no rows either. Typed, not silent.
       return;
     }
+    if (this.#host.running() || this.#continuation !== null) {
+      // Refused rather than started beside it. The panel opens and its rows
+      // take a pick while a run streams, and a second run would draw its answer
+      // into the turn still arriving; a second continuation would also replace
+      // the one Stop reaches, leaving the first streaming where nothing could
+      // end it. Nor is the earlier run cancelled for it: a pick in a panel is not
+      // a Stop, and what is streaming may be the answer the user is waiting on.
+      //
+      // Both checks, because they see different moments. `running` is the
+      // composer's own state and spans every round of an interaction, but it
+      // is set when the run's first event arrives; a continuation is recorded
+      // here the moment it starts.
+      //
+      // Said at the composer, as an empty composer is below, because the row
+      // closed the panel before this ran. The typed turn stays where it is --
+      // it is what the user wants sent once the run is done -- and the caret
+      // goes back to it, where Escape stops the run.
+      this.#refuse(this.#host.strings().continueWhileRunning);
+      return;
+    }
     const content = this.#host.input.value.trim();
     if (content === "") {
       // A continuation sends *only* the next turn -- the snapshot supplies
@@ -289,31 +347,81 @@ export class ConversationHistory {
       // keystroke -- a transcript notice for a recoverable slip would outlive
       // the slip. Focus follows for the same reason applying a skill moves it when
       // a template is short of a field.
-      this.#host.hint.textContent = this.#host.strings().continueNeedsTurn;
-      this.#host.hint.hidden = false;
-      this.#host.input.focus();
+      this.#refuse(this.#host.strings().continueNeedsTurn);
       return;
     }
     this.#host.input.value = "";
     this.#host.autoGrow();
+    const cleared = this.#cleared;
     const client = this.#host.buildClient({
       endpoint: verb === "resume" ? index.resumeUrl(runId) : index.forkUrl(runId),
       // The seed the endpoints assume: nothing. The snapshot is the history.
       initialMessages: [],
-      // Nor does it write the store. Its agent holds only the new turn and its
-      // answer, and a store keeps one list per thread, so saving what this
-      // client has would replace the conversation with its last exchange.
-      persist: false,
+      // What its saves write ahead of the exchange: the conversation on screen,
+      // in the form the store holds it. From the conversation's own client when
+      // there is one, because that client keeps how each call ended beside its
+      // messages rather than on them; otherwise what the last restore or
+      // continuation wrote, which is already in that form.
+      //
+      // All of it, even where this forks an earlier run and the server's
+      // snapshot stops there: what is saved is what the screen shows.
+      follows: this.#host.client()?.annotatedMessages ?? this.#restored,
+      onSaved: (conversation) => {
+        // A continuation stopped by New chat or a thread switch saves once its
+        // request closes, into its own thread; the conversation now on screen
+        // is not the one it continued.
+        if (cleared !== this.#cleared) {
+          return;
+        }
+        // The conversation's own client holds the conversation without this
+        // exchange, and would send it that way. Released rather than patched:
+        // the next client is built from this list exactly as a reload builds
+        // one from the store, outcomes included.
+        //
+        // Nothing can run on the released client in between, because the
+        // composer refuses to start one while a continuation is in flight --
+        // it parks the turn instead. It said here that only a script in the
+        // same task could, which was wrong by a whole request: `running` does
+        // not turn on until the continuation's first event, and a person who
+        // typed in that window got a second run against the snapshot
+        // `follows` had already frozen, so whichever saved last dropped the
+        // other's turn.
+        this.#restored = conversation;
+        this.#host.releaseClient();
+      },
     });
     this.#continuation = client;
-    await client.send(content);
-    // Only if it is still the one in flight: stopping forgets it at once, and a
-    // continuation started after that one is not this one to forget.
-    if (this.#continuation === client) {
-      this.#continuation = null;
+    try {
+      await client.send(content);
+    } finally {
+      // Only if it is still the one in flight: stopping forgets it at once, and
+      // a continuation started after that one is not this one to forget.
+      //
+      // In a finally because the send can fail before its run ever starts. The
+      // first save goes through the host's `conversationStore` synchronously
+      // inside it, and a store is the host's to replace: the built-in one
+      // swallows a write the browser refused, a server-backed one need not. A
+      // throw there left this pointing at a client that would never run, so
+      // every later pick was refused with no Stop to clear it -- the composer's
+      // button is Send until a run reports a start -- and `#liveClient` went on
+      // handing that dead client the shared state a host wrote.
+      if (this.#continuation === client) {
+        this.#continuation = null;
+        this.#host.continuationEnded();
+      }
     }
   }
 
+  /**
+   * Say at the composer why a picked run did not continue, and put the caret
+   * there. The hint clears itself on the next keystroke.
+   */
+  #refuse(reason: string): void {
+    this.#host.hint.textContent = reason;
+    this.#host.hint.hidden = false;
+    this.#host.input.focus();
+  }
+
   /**
    * Restore the conversation from the store on mount, then — if a navigating
    * tool reloaded the page mid-run — resume the loop by supplying that tool's