@artooi/ag-ui-web-component 0.9.0 → 0.11.0

package/src/core/conversation_store.ts

@@ -64,10 +64,11 @@ export interface ClientConversationStore {
   renameThread(threadId: string, title: string): void;
 }
 
-const THREAD_KEY = "ag-ui-chat:thread";
-const THREADS_KEY = "ag-ui-chat:threads";
-const MESSAGES_PREFIX = "ag-ui-chat:messages:";
-const CHECKPOINT_PREFIX = "ag-ui-chat:checkpoint:";
+const KEY_ROOT = "ag-ui-chat";
+const THREAD_SUFFIX = "thread";
+const THREADS_SUFFIX = "threads";
+const MESSAGES_SUFFIX = "messages:";
+const CHECKPOINT_SUFFIX = "checkpoint:";
 
 const TITLE_LIMIT = 60;
 const PREVIEW_LIMIT = 100;
@@ -90,33 +91,50 @@ interface StoredThread {
  * Tracks multiple threads per tab: the active id lives under one key, the
  * message history / checkpoint are namespaced by id, and a small index feeds
  * the drawer so it works with no server.
+ *
+ * An optional `namespace` scopes every key to one element (its `id`, else its
+ * endpoint), so two `<ag-ui-chat>` instances — or two apps — on the same origin
+ * keep separate active-thread pointers and drawer indexes instead of clobbering
+ * each other. Constructing with a namespace migrates any pre-namespacing
+ * (`ag-ui-chat:*`) keys into it once, so an existing conversation survives the
+ * upgrade; the default empty namespace keeps the legacy origin-global keys.
  */
 export class SessionStorageStore implements ClientConversationStore {
+  readonly #root: string;
+
+  constructor(namespace = "") {
+    this.#root = namespace === "" ? KEY_ROOT : `${KEY_ROOT}@${namespace}`;
+    if (namespace !== "") {
+      this.#migrateLegacyKeys();
+    }
+  }
+
   threadId(): string {
-    const existing = sessionStorage.getItem(THREAD_KEY);
+    const key = this.#key(THREAD_SUFFIX);
+    const existing = sessionStorage.getItem(key);
     if (existing !== null) {
       return existing;
     }
     const id = randomUUID();
-    sessionStorage.setItem(THREAD_KEY, id);
+    sessionStorage.setItem(key, id);
     return id;
   }
 
   loadMessages(threadId: string): Promise<readonly Message[] | null> {
-    return Promise.resolve(this.#readJson<Message[]>(MESSAGES_PREFIX + threadId));
+    return Promise.resolve(this.#readJson<Message[]>(this.#key(MESSAGES_SUFFIX + threadId)));
   }
 
   saveMessages(threadId: string, messages: readonly Message[]): void {
-    sessionStorage.setItem(MESSAGES_PREFIX + threadId, JSON.stringify(messages));
+    sessionStorage.setItem(this.#key(MESSAGES_SUFFIX + threadId), JSON.stringify(messages));
     this.#touchThread(threadId, messages);
   }
 
   loadCheckpoint(threadId: string): NavigationCheckpoint | null {
-    return this.#readJson<NavigationCheckpoint>(CHECKPOINT_PREFIX + threadId);
+    return this.#readJson<NavigationCheckpoint>(this.#key(CHECKPOINT_SUFFIX + threadId));
   }
 
   saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void {
-    const key = CHECKPOINT_PREFIX + threadId;
+    const key = this.#key(CHECKPOINT_SUFFIX + threadId);
     if (checkpoint === null) {
       sessionStorage.removeItem(key);
       return;
@@ -125,14 +143,14 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   clear(threadId: string): void {
-    sessionStorage.removeItem(MESSAGES_PREFIX + threadId);
-    sessionStorage.removeItem(CHECKPOINT_PREFIX + threadId);
+    sessionStorage.removeItem(this.#key(MESSAGES_SUFFIX + threadId));
+    sessionStorage.removeItem(this.#key(CHECKPOINT_SUFFIX + threadId));
     this.#writeThreads(this.#readThreads().filter((thread) => thread.threadId !== threadId));
     // Only drop the active pointer when the active thread itself is cleared, so
     // the next `threadId()` mints a fresh one. Deleting another thread from the
     // drawer must not disturb the conversation on screen.
-    if (sessionStorage.getItem(THREAD_KEY) === threadId) {
-      sessionStorage.removeItem(THREAD_KEY);
+    if (sessionStorage.getItem(this.#key(THREAD_SUFFIX)) === threadId) {
+      sessionStorage.removeItem(this.#key(THREAD_SUFFIX));
     }
   }
 
@@ -144,7 +162,7 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   setActiveThread(threadId: string): void {
-    sessionStorage.setItem(THREAD_KEY, threadId);
+    sessionStorage.setItem(this.#key(THREAD_SUFFIX), threadId);
   }
 
   renameThread(threadId: string, title: string): void {
@@ -183,15 +201,53 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   #readThreads(): StoredThread[] {
-    return this.#readJson<StoredThread[]>(THREADS_KEY) ?? [];
+    return this.#readJson<StoredThread[]>(this.#key(THREADS_SUFFIX)) ?? [];
   }
 
   #writeThreads(threads: readonly StoredThread[]): void {
+    const key = this.#key(THREADS_SUFFIX);
     if (threads.length === 0) {
-      sessionStorage.removeItem(THREADS_KEY);
+      sessionStorage.removeItem(key);
       return;
     }
-    sessionStorage.setItem(THREADS_KEY, JSON.stringify(threads));
+    sessionStorage.setItem(key, JSON.stringify(threads));
+  }
+
+  /** This store's fully-qualified key for a suffix (namespaced when set). */
+  #key(suffix: string): string {
+    return `${this.#root}:${suffix}`;
+  }
+
+  /**
+   * One-time move of pre-namespacing (`ag-ui-chat:*`) keys into this instance's
+   * namespace, so an existing conversation isn't orphaned by the upgrade. Only
+   * this store's own keys move (thread pointer, drawer index, per-thread
+   * messages/checkpoints) — the element's `collapsed`/`theme` keys are left
+   * alone. The first namespaced instance to mount adopts the legacy data; a
+   * second namespace finds it gone and starts fresh.
+   */
+  #migrateLegacyKeys(): void {
+    const legacyRoot = `${KEY_ROOT}:`;
+    const moves: Array<readonly [string, string]> = [];
+    for (let i = 0; i < sessionStorage.length; i += 1) {
+      const key = sessionStorage.key(i);
+      if (key === null || !key.startsWith(legacyRoot)) {
+        continue;
+      }
+      const suffix = key.slice(legacyRoot.length);
+      if (isOwnedSuffix(suffix)) {
+        moves.push([key, this.#key(suffix)]);
+      }
+    }
+    // Collected first, mutated second — writing while iterating by index skips
+    // entries as the key list shifts.
+    for (const [from, to] of moves) {
+      const value = sessionStorage.getItem(from);
+      if (value !== null && sessionStorage.getItem(to) === null) {
+        sessionStorage.setItem(to, value);
+      }
+      sessionStorage.removeItem(from);
+    }
   }
 
   /** Parse a stored JSON value, returning `null` when absent or corrupt. */
@@ -208,6 +264,16 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 }
 
+/** Whether a legacy key suffix belongs to the store (vs the element's own keys). */
+function isOwnedSuffix(suffix: string): boolean {
+  return (
+    suffix === THREAD_SUFFIX ||
+    suffix === THREADS_SUFFIX ||
+    suffix.startsWith(MESSAGES_SUFFIX) ||
+    suffix.startsWith(CHECKPOINT_SUFFIX)
+  );
+}
+
 /** The thread title: the first user message, collapsed + truncated. */
 function deriveTitle(messages: readonly Message[]): string {
   for (const message of messages) {

package/src/core/remote_conversation_store.ts

@@ -96,7 +96,13 @@ export class RemoteConversationStore implements ClientConversationStore {
     if (response === null || !response.ok) {
       return this.#local.loadMessages(threadId);
     }
-    const body = (await response.json()) as { messages?: readonly Message[] };
+    // A 200 whose body isn't the expected 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 instead.
+    const body = await this.#readJson<{ messages?: readonly Message[] }>(response);
+    if (body === null) {
+      return this.#local.loadMessages(threadId);
+    }
     return body.messages ?? null;
   }
 
@@ -105,15 +111,30 @@ export class RemoteConversationStore implements ClientConversationStore {
     if (response === null || !response.ok) {
       return null;
     }
-    const body = (await response.json()) as { threads?: readonly ServerThreadRow[] };
+    const body = await this.#readJson<{ threads?: readonly ServerThreadRow[] }>(response);
+    if (body === null) {
+      return null;
+    }
     return body.threads ?? [];
   }
 
+  /** Parse a `Response` body as JSON, or `null` when it isn't valid JSON. */
+  async #readJson<T>(response: Response): Promise<T | null> {
+    try {
+      return (await response.json()) as T;
+    } catch {
+      return null;
+    }
+  }
+
   #toMeta(row: ServerThreadRow): ThreadMeta {
     return {
       threadId: row.thread_id,
       title: this.#renamed.get(row.thread_id) ?? row.title,
-      updatedAt: row.updated_at === null ? 0 : Date.parse(row.updated_at),
+      // `null` or an unparseable date both become `NaN` (Date.parse's own
+      // signal), which `relativeTime` renders as a neutral label rather than
+      // "~2950w ago" (epoch 0) or "NaNw ago".
+      updatedAt: row.updated_at === null ? Number.NaN : Date.parse(row.updated_at),
       preview: row.preview,
     };
   }

package/src/core/upload_attachment.ts

@@ -7,10 +7,17 @@ import type { AttachmentRef } from "./attachment.js";
  * `tus-js-client` or direct-to-S3 adapter — via `AgUiChat.uploadHandler`,
  * **without** touching the tray, the chips, or the AG-UI wire (refs are
  * transport-agnostic).
+ *
+ * The optional third `signal` argument lets the tray abort an in-flight upload
+ * when its chip is removed (or the element is torn down), so a cancelled upload
+ * doesn't orphan a server-side file. It is non-breaking: existing two-argument
+ * handlers keep working (the extra argument is simply ignored), and a custom
+ * handler that honours it should abort its own transport when the signal fires.
  */
 export type UploadHandler = (
   file: File,
   onProgress: (fraction: number) => void,
+  signal?: AbortSignal,
 ) => Promise<AttachmentRef>;
 
 /** Options for {@link uploadAttachment}. */
@@ -22,7 +29,7 @@ export interface UploadOptions {
   /** Progress callback, `0..1`, fired as the body uploads. */
   readonly onProgress?: (fraction: number) => void;
   /** Abort signal to cancel the in-flight upload. */
-  readonly signal?: AbortSignal;
+  readonly signal?: AbortSignal | undefined;
 }
 
 /**

package/src/index.ts

@@ -27,6 +27,8 @@ export {
   type AgUiToolCall,
   ConnectionLostError,
   type ExecuteTool,
+  type InterruptResponse,
+  type ResolveInterrupts,
   type ToolExecution,
 } from "./core/agui_client.js";
 export { type AttachmentRef, messageAttachments } from "./core/attachment.js";
@@ -98,12 +100,24 @@ export {
   type RouteWithParams,
 } from "./tools/route_map.js";
 export { createStateHookTools, type StateHook } from "./tools/state_hook.js";
+export {
+  type ApprovalOptions,
+  type ApprovalRenderer,
+  type ApprovalRequest,
+  requestApproval,
+} from "./ui/approval_card.js";
 export {
   type ConfirmationOptions,
   type ConfirmationRequest,
   requestConfirmation,
 } from "./ui/confirmation_card.js";
 export { prettifyToolName } from "./ui/prettify_tool_name.js";
+export {
+  type QuestionOptions,
+  type QuestionRenderer,
+  type QuestionRequest,
+  requestQuestion,
+} from "./ui/question_card.js";
 export { type RenderMarkdownOptions, renderMarkdown } from "./ui/render_markdown.js";
 export {
   type SettledStatus,

package/src/ui/approval_card.ts

@@ -0,0 +1,119 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** What the inline approval card displays for one server-side-tool interrupt. */
+export interface ApprovalRequest {
+  /**
+   * Human-readable prompt from the AG-UI interrupt (e.g.
+   * `Approve delete_thing({…})?`). Falls back to the generic
+   * {@link UiStrings.approvalPrompt} when the interrupt carries no message.
+   */
+  message?: string;
+  /** Tool name, surfaced as a `data-tool-name` attribute for styling/tests. */
+  toolName?: string;
+}
+
+/** Build a labelled action button. */
+function actionButton(modifier: string, label: string): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `approval-btn approval-btn--${modifier}`;
+  button.setAttribute("part", `approval-button approval-${modifier}`);
+  button.textContent = label;
+  return button;
+}
+
+/** Options for {@link requestApproval}. */
+export interface ApprovalOptions {
+  /**
+   * Aborting this signal resolves the card as **denied** (buttons disabled,
+   * `data-resolved="denied"`) — the hook a Stop control uses to dismiss a
+   * pending approval when the user cancels the whole run.
+   */
+  signal?: AbortSignal;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  strings?: UiStrings;
+}
+
+/**
+ * A fully custom renderer for a server-side-tool approval, set via
+ * `AgUiChat.approvalRenderer`. Receives the {@link ApprovalRequest} (the
+ * interrupt's message + tool name) and an `AbortSignal` that fires when the run
+ * is stopped, and resolves `true` to approve or `false` to deny. When provided
+ * it **replaces** the built-in {@link requestApproval} card entirely — the host
+ * owns the DOM, so it can render a native modal, a framework component, or
+ * anything else. See the `strings` / `::part()` seams for styling the built-in
+ * card instead of replacing it.
+ */
+export type ApprovalRenderer = (
+  request: ApprovalRequest,
+  options: { signal: AbortSignal },
+) => Promise<boolean>;
+
+/**
+ * Append an inline **approval** card to ``host`` and resolve when the user
+ * decides whether a gated *server-side* tool may run.
+ *
+ * The server-side approval gate is distinct from the client-tool confirmation
+ * card ({@link requestConfirmation}): a destructive server tool defers instead
+ * of executing, and the run finishes on an AG-UI *interrupt* the client answers
+ * with `resume[]`. This card is the browser half of that loop — it reads
+ * naturally after the tool-call card whose execution it gates, and resolves
+ * ``true`` to approve (run the tool) or ``false`` to deny. The card stays in the
+ * transcript as a resolved record (buttons disabled, `data-resolved` set)
+ * rather than vanishing.
+ */
+export function requestApproval(
+  host: Node & ParentNode,
+  request: ApprovalRequest,
+  options: ApprovalOptions = {},
+): Promise<boolean> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
+  return new Promise<boolean>((resolve) => {
+    const card = document.createElement("div");
+    card.className = "approval";
+    card.setAttribute("part", "approval");
+    if (request.toolName !== undefined) {
+      card.setAttribute("data-tool-name", request.toolName);
+    }
+    card.setAttribute("role", "group");
+    card.setAttribute("aria-label", strings.approveAction);
+
+    const body = document.createElement("div");
+    body.className = "approval-body";
+    body.setAttribute("part", "approval-body");
+    body.textContent = request.message ?? strings.approvalPrompt;
+
+    const actions = document.createElement("div");
+    actions.className = "approval-actions";
+    actions.setAttribute("part", "approval-actions");
+
+    const deny = actionButton("deny", strings.deny);
+    const approve = actionButton("approve", strings.approve);
+
+    let settled = false;
+    const close = (approved: boolean): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      deny.disabled = true;
+      approve.disabled = true;
+      card.setAttribute("data-resolved", approved ? "approved" : "denied");
+      resolve(approved);
+    };
+
+    deny.addEventListener("click", () => close(false));
+    approve.addEventListener("click", () => close(true));
+    options.signal?.addEventListener("abort", () => close(false), { once: true });
+
+    actions.append(deny, approve);
+    card.append(body, actions);
+    host.appendChild(card);
+    if (options.signal?.aborted === true) {
+      // The run was cancelled before the card could ask; record the denial.
+      close(false);
+      return;
+    }
+    approve.focus();
+  });
+}

package/src/ui/attachment_chips.ts

@@ -9,6 +9,7 @@ import type { AttachmentRef } from "../core/attachment.js";
 export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivElement {
   const list = document.createElement("div");
   list.className = "attachment-chips";
+  list.setAttribute("part", "attachment-chips");
   for (const ref of refs) {
     list.appendChild(renderChip(ref));
   }
@@ -18,19 +19,23 @@ export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivEl
 function renderChip(ref: AttachmentRef): HTMLDivElement {
   const chip = document.createElement("div");
   chip.className = "attachment-chip attachment-chip--ready";
+  chip.setAttribute("part", "attachment-chip");
 
   const icon = document.createElement("span");
   icon.className = "attachment-chip-icon";
+  icon.setAttribute("part", "attachment-chip-icon");
   icon.textContent = iconFor(ref.mime);
   icon.setAttribute("aria-hidden", "true");
 
   const name = document.createElement("span");
   name.className = "attachment-chip-name";
+  name.setAttribute("part", "attachment-chip-name");
   name.textContent = ref.name;
   name.title = ref.name;
 
   const size = document.createElement("span");
   size.className = "attachment-chip-size";
+  size.setAttribute("part", "attachment-chip-size");
   size.textContent = formatBytes(ref.size);
 
   chip.append(icon, name, size);

package/src/ui/attachment_tray.ts

@@ -30,6 +30,8 @@ interface TrayItem {
   progress: number;
   ref: AttachmentRef | null;
   error: string;
+  /** Aborts the in-flight upload when the chip is removed / the tray cleared. */
+  controller: AbortController | null;
 }
 
 /**
@@ -68,6 +70,7 @@ export class AttachmentTray {
       progress: 0,
       ref: null,
       error: "",
+      controller: null,
     };
     this.#items.push(item);
     const rejection = this.#reject(file);
@@ -110,12 +113,26 @@ export class AttachmentTray {
     this.#render();
   }
 
-  /** Drop every chip (a reset / new-chat). */
+  /** Drop every chip (a reset / new-chat), aborting any in-flight upload. */
   clear(): void {
+    for (const item of this.#items) {
+      item.controller?.abort();
+    }
     this.#items = [];
     this.#render();
   }
 
+  /**
+   * Abort every in-flight upload without touching the rendered chips — the
+   * teardown path when the host element is removed mid-upload, so a cancelled
+   * transfer doesn't orphan a server-side file.
+   */
+  dispose(): void {
+    for (const item of this.#items) {
+      item.controller?.abort();
+    }
+  }
+
   /** The size/type rejection reason for a file, or `null` when accepted. */
   #reject(file: File): string | null {
     if (this.#config.maxBytes > 0 && file.size > this.#config.maxBytes) {
@@ -128,15 +145,32 @@ export class AttachmentTray {
   }
 
   #upload(item: TrayItem): void {
+    // Re-apply the client guard on every attempt, not just the first `add` — an
+    // ERROR chip always renders retry, so without this a size/type-rejected file
+    // would upload in full on ↻.
+    const rejection = this.#reject(item.file);
+    if (rejection !== null) {
+      item.status = ATTACHMENT_STATUS.ERROR;
+      item.error = rejection;
+      this.#render();
+      this.#config.onChange?.();
+      return;
+    }
     item.status = ATTACHMENT_STATUS.UPLOADING;
     item.progress = 0;
     item.error = "";
+    const controller = new AbortController();
+    item.controller = controller;
     this.#render();
     this.#config
-      .upload(item.file, (fraction) => {
-        item.progress = fraction;
-        this.#render();
-      })
+      .upload(
+        item.file,
+        (fraction) => {
+          item.progress = fraction;
+          this.#render();
+        },
+        controller.signal,
+      )
       .then((ref) => {
         item.status = ATTACHMENT_STATUS.READY;
         item.ref = ref;
@@ -146,12 +180,15 @@ export class AttachmentTray {
         item.error = error instanceof Error ? error.message : this.#strings.uploadFailed;
       })
       .finally(() => {
+        item.controller = null;
         this.#render();
         this.#config.onChange?.();
       });
   }
 
   #remove(item: TrayItem): void {
+    // Abort an in-flight upload so removing its chip doesn't orphan the file.
+    item.controller?.abort();
     this.#items = this.#items.filter((other) => other !== item);
     this.#render();
     this.#config.onChange?.();
@@ -168,19 +205,23 @@ export class AttachmentTray {
   #renderChip(item: TrayItem): HTMLDivElement {
     const chip = document.createElement("div");
     chip.className = `attachment-chip attachment-chip--${item.status}`;
+    chip.setAttribute("part", "attachment-chip");
 
     const icon = document.createElement("span");
     icon.className = "attachment-chip-icon";
+    icon.setAttribute("part", "attachment-chip-icon");
     icon.textContent = iconFor(item.file.type);
     icon.setAttribute("aria-hidden", "true");
 
     const name = document.createElement("span");
     name.className = "attachment-chip-name";
+    name.setAttribute("part", "attachment-chip-name");
     name.textContent = item.file.name;
     name.title = item.file.name;
 
     const meta = document.createElement("span");
     meta.className = "attachment-chip-size";
+    meta.setAttribute("part", "attachment-chip-size");
     meta.textContent =
       item.status === ATTACHMENT_STATUS.ERROR ? item.error : formatBytes(item.file.size);
 
@@ -189,8 +230,10 @@ export class AttachmentTray {
     if (item.status === ATTACHMENT_STATUS.UPLOADING) {
       const bar = document.createElement("div");
       bar.className = "attachment-chip-bar";
+      bar.setAttribute("part", "attachment-chip-bar");
       const fill = document.createElement("div");
       fill.className = "attachment-chip-bar-fill";
+      fill.setAttribute("part", "attachment-chip-bar-fill");
       fill.style.width = `${Math.round(item.progress * 100)}%`;
       bar.appendChild(fill);
       chip.appendChild(bar);
@@ -200,6 +243,7 @@ export class AttachmentTray {
       const retry = document.createElement("button");
       retry.type = "button";
       retry.className = "attachment-chip-retry";
+      retry.setAttribute("part", "attachment-chip-retry");
       retry.title = this.#strings.retry;
       retry.setAttribute("aria-label", this.#strings.retryUpload);
       retry.textContent = "↻";
@@ -210,6 +254,7 @@ export class AttachmentTray {
     const remove = document.createElement("button");
     remove.type = "button";
     remove.className = "attachment-chip-remove";
+    remove.setAttribute("part", "attachment-chip-remove");
     remove.title = this.#strings.remove;
     remove.setAttribute("aria-label", this.#strings.removeAttachment);
     remove.textContent = "✕";