@artooi/ag-ui-web-component 0.27.0 → 0.28.0

package/src/core/agui_client.ts

@@ -97,7 +97,14 @@ export interface AgUiClientHandlers {
   onActivityChanged(messageId: string, activityType: string, content: unknown): void;
   /** Fired when a reasoning model starts emitting its chain-of-thought. */
   onReasoningStart(): void;
-  /** Fired on every reasoning token; ``buffer`` is the full reasoning text so far. */
+  /**
+   * Fired on every reasoning token, and once more when the block ends.
+   *
+   * ``buffer`` is the text accumulated *before* the token that triggered the
+   * call, which is what the protocol client passes -- so the stream trails by
+   * one delta and the final call, at the end of the block, is what completes
+   * it. Render the buffer wholesale rather than appending it.
+   */
   onReasoningDelta(buffer: string): void;
   /** Fired when the reasoning block ends (before the answer text streams). */
   onReasoningEnd(): void;
@@ -497,6 +504,16 @@ export class AgUiClient {
       onReasoningMessageContentEvent({ reasoningMessageBuffer }) {
         h.onReasoningDelta(reasoningMessageBuffer);
       },
+      // The delta callback reports the buffer as it stood *before* the announced
+      // delta was appended, so on its own it always trails the stream by one and
+      // renders nothing at all for a block that arrives as a single delta. The
+      // answer text is spared that because its own end event carries the whole
+      // message; this is the reasoning counterpart, and it has to be
+      // REASONING_MESSAGE_END rather than REASONING_END, because only the former
+      // carries a buffer.
+      onReasoningMessageEndEvent({ reasoningMessageBuffer }) {
+        h.onReasoningDelta(reasoningMessageBuffer);
+      },
       onReasoningEndEvent() {
         h.onReasoningEnd();
       },

package/src/core/conversation_store.ts

@@ -102,6 +102,49 @@ const TITLE_LIMIT = 60;
 const PREVIEW_LIMIT = 100;
 const DEFAULT_TITLE = "New conversation";
 
+// One warning per page, not one per write. The condition is origin-wide and
+// persistent — a full quota stays full — so a message per persisted turn (or,
+// on the resize path, per keystroke) would bury the one that matters.
+let writeFailureReported = false;
+
+/**
+ * `sessionStorage.setItem` that survives a store which refuses to write.
+ *
+ * `setItem` throws on an exhausted quota (a long conversation, or one turn
+ * carrying a large tool result) and in privacy modes that deny storage
+ * altogether. Every write here is a *durability* concern — surviving a reload —
+ * and none of them is worth an exception, because of where they are called
+ * from: the element persists the transcript from inside the run loop, so an
+ * unguarded throw escapes as a run error and tells the user the agent failed
+ * when nothing but the browser's storage did. On the cancel path it escapes as
+ * an unhandled rejection instead.
+ *
+ * So a failed write loses the reload, never the conversation on screen, and
+ * says so once. Recovery is in the user's hands already: deleting the oversized
+ * thread from the history drawer is a `removeItem`, which frees the quota.
+ */
+export function writeStoredItem(key: string, value: string): void {
+  try {
+    sessionStorage.setItem(key, value);
+  } catch {
+    if (writeFailureReported) {
+      return;
+    }
+    writeFailureReported = true;
+    console.warn(
+      "<ag-ui-chat>: the browser refused a sessionStorage write — the quota is " +
+        "full, or storage is disabled for this context. The conversation " +
+        "continues, but it will not survive a page reload. Deleting a long " +
+        "conversation from the history drawer frees the quota.",
+    );
+  }
+}
+
+/** The storage-key root for a namespace; `""` is the pre-namespacing global root. */
+function rootFor(namespace: string): string {
+  return namespace === "" ? KEY_ROOT : `${KEY_ROOT}@${namespace}`;
+}
+
 /** The drawer-index entry; `titleCustom` (private) freezes a renamed title. */
 interface StoredThread {
   threadId: string;
@@ -122,15 +165,59 @@ interface StoredThread {
  * An optional `namespace` scopes every key to one element, so two
  * `<ag-ui-chat>` instances on the same origin keep separate active-thread
  * pointers and drawer indexes instead of clobbering each other. The default
- * empty namespace keeps the origin-global keys; see {@link #migrateLegacyKeys}.
+ * empty namespace keeps the origin-global keys, which a namespaced store adopts
+ * on construction; see {@link SessionStorageStore.adopt}.
  */
 export class SessionStorageStore implements ClientConversationStore {
   readonly #root: string;
 
   constructor(namespace = "") {
-    this.#root = namespace === "" ? KEY_ROOT : `${KEY_ROOT}@${namespace}`;
+    this.#root = rootFor(namespace);
     if (namespace !== "") {
-      this.#migrateLegacyKeys();
+      // One-time move of the pre-namespacing global keys, so an existing
+      // conversation isn't orphaned by the upgrade. See {@link adopt}.
+      SessionStorageStore.adopt("", namespace);
+    }
+  }
+
+  /**
+   * Move every key a store owns out of `from`'s namespace and into `to`'s.
+   *
+   * Two callers, one move. The constructor adopts the pre-namespacing global
+   * keys (`from` = `""`); `<ag-ui-chat>` adopts an element-scoped conversation
+   * into a principal-scoped one the first time a `user-key` arrives, which is a
+   * host naming the user who was already there rather than a handover.
+   *
+   * Only this store's own suffixes move — the element's `collapsed` / `size` /
+   * `theme` keys share the global root and are deliberately left where they
+   * are. A value already present at the destination wins: the destination is
+   * the durable record and the source is the stray this move exists to clear.
+   */
+  static adopt(from: string, to: string): void {
+    const fromRoot = `${rootFor(from)}:`;
+    const toRoot = `${rootFor(to)}:`;
+    for (const [key, suffix] of ownedKeys(fromRoot)) {
+      const value = sessionStorage.getItem(key);
+      const destination = toRoot + suffix;
+      if (value !== null && sessionStorage.getItem(destination) === null) {
+        writeStoredItem(destination, value);
+      }
+      sessionStorage.removeItem(key);
+    }
+  }
+
+  /**
+   * Forget everything a store holds for `namespace`.
+   *
+   * The logout primitive: `<ag-ui-chat>` calls it when its `user-key` changes,
+   * and a host driving its own store can call it from its own sign-out path.
+   * Deliberately narrow — it removes only keys under this exact namespace whose
+   * suffix parses as one this store writes, so it can never reach another
+   * element's conversation or the host's own `sessionStorage` entries.
+   */
+  static purge(namespace: string): void {
+    for (const [key] of ownedKeys(`${rootFor(namespace)}:`)) {
+      sessionStorage.removeItem(key);
     }
   }
 
@@ -140,8 +227,8 @@ export class SessionStorageStore implements ClientConversationStore {
 
   newThread(): string {
     const id = randomUUID();
-    sessionStorage.setItem(this.#key(THREAD_SUFFIX), id);
-    sessionStorage.setItem(this.#key(MINTED_SUFFIX + id), "1");
+    writeStoredItem(this.#key(THREAD_SUFFIX), id);
+    writeStoredItem(this.#key(MINTED_SUFFIX + id), "1");
     return id;
   }
 
@@ -157,7 +244,7 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   saveMessages(threadId: string, messages: readonly Message[]): void {
-    sessionStorage.setItem(this.#key(MESSAGES_SUFFIX + threadId), JSON.stringify(messages));
+    writeStoredItem(this.#key(MESSAGES_SUFFIX + threadId), JSON.stringify(messages));
     sessionStorage.removeItem(this.#key(MINTED_SUFFIX + threadId));
     this.#touchThread(threadId, messages);
   }
@@ -172,7 +259,7 @@ export class SessionStorageStore implements ClientConversationStore {
       sessionStorage.removeItem(key);
       return;
     }
-    sessionStorage.setItem(key, JSON.stringify(checkpoint));
+    writeStoredItem(key, JSON.stringify(checkpoint));
   }
 
   clear(threadId: string): void {
@@ -196,7 +283,7 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   setActiveThread(threadId: string): void {
-    sessionStorage.setItem(this.#key(THREAD_SUFFIX), threadId);
+    writeStoredItem(this.#key(THREAD_SUFFIX), threadId);
   }
 
   renameThread(threadId: string, title: string): void {
@@ -244,7 +331,7 @@ export class SessionStorageStore implements ClientConversationStore {
       sessionStorage.removeItem(key);
       return;
     }
-    sessionStorage.setItem(key, JSON.stringify(threads));
+    writeStoredItem(key, JSON.stringify(threads));
   }
 
   /** This store's fully-qualified key for a suffix (namespaced when set). */
@@ -252,37 +339,6 @@ export class SessionStorageStore implements ClientConversationStore {
     return `${this.#root}:${suffix}`;
   }
 
-  /**
-   * One-time move of un-namespaced `ag-ui-chat:*` keys into this instance's
-   * namespace, so an existing conversation isn't orphaned. Only this store's own
-   * keys move — the element's `collapsed` / `theme` keys are left alone. The
-   * first namespaced instance to mount adopts the 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. */
   #readJson<T>(key: string): T | null {
     const raw = sessionStorage.getItem(key);
@@ -297,13 +353,43 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 }
 
-/** Whether a legacy key suffix belongs to the store (vs the element's own keys). */
+/**
+ * Every `sessionStorage` key under `root` that this store wrote, as
+ * `[key, suffix]`.
+ *
+ * Collected into an array before the caller mutates anything: `sessionStorage`
+ * is enumerated by index, and removing an entry mid-loop shifts the ones after
+ * it out from under the cursor.
+ *
+ * The suffix test is what makes {@link SessionStorageStore.purge} safe to point
+ * at a namespace. It matters most for the global root, which the element's own
+ * `collapsed` / `size` / `theme` keys share — but it also means a namespace
+ * whose name happens to be a prefix of another cannot reach into it, since the
+ * remainder would have to parse as one of these suffixes.
+ */
+function ownedKeys(root: string): Array<readonly [string, string]> {
+  const found: Array<readonly [string, string]> = [];
+  for (let index = 0; index < sessionStorage.length; index += 1) {
+    const key = sessionStorage.key(index);
+    if (key === null || !key.startsWith(root)) {
+      continue;
+    }
+    const suffix = key.slice(root.length);
+    if (isOwnedSuffix(suffix)) {
+      found.push([key, suffix]);
+    }
+  }
+  return found;
+}
+
+/** Whether a 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)
+    suffix.startsWith(CHECKPOINT_SUFFIX) ||
+    suffix.startsWith(MINTED_SUFFIX)
   );
 }
 

package/src/core/create_http_agent.ts

@@ -1,6 +1,6 @@
 import { type AbstractAgent, HttpAgent } from "@ag-ui/client";
 import type { Message } from "@ag-ui/core";
-import { withCredentials } from "./utils.js";
+import { warnOnCrossOriginCredentials, withCredentials } from "./utils.js";
 
 /** Config for {@link createHttpAgent}. */
 export interface HttpAgentOptions {
@@ -32,6 +32,19 @@ export interface HttpAgentOptions {
    * server streams `STATE_SNAPSHOT` / `STATE_DELTA`.
    */
   initialState?: Readonly<Record<string, unknown>>;
+  /**
+   * Origins, besides the document's own, this agent may carry the host's
+   * credentials to.
+   *
+   * Running the agent on another subdomain is a normal deployment and stays
+   * supported, so a cross-origin endpoint is not refused — it is *announced*,
+   * once per origin, on the console. Listing an origin here says the
+   * destination was chosen deliberately and silences the notice for it.
+   *
+   * Entries are compared as serialized origins (`https://agent.example.com`,
+   * scheme and port included), which is what `URL.origin` produces.
+   */
+  trustedOrigins?: readonly string[];
 }
 
 /**
@@ -42,9 +55,11 @@ export interface HttpAgentOptions {
  * {@link AbstractAgent}.
  */
 export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
+  const staticHeaders = options.headers ?? {};
+  const warned = new Set<string>();
   return new HttpAgent({
     url: options.endpoint,
-    headers: options.headers ?? {},
+    headers: staticHeaders,
     initialState: { ...(options.initialState ?? {}) },
     // HttpAgent invokes its configured fetch as a method (`this.fetch(...)`),
     // rebinding the global `fetch` to the agent instance — "Illegal invocation"
@@ -53,6 +68,13 @@ export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
     // own config having no seam for either.
     fetch: (url, init) => {
       const fresh = options.getHeaders?.();
+      // Only the names the *host* supplied. `HttpAgent` adds `Content-Type` and
+      // `Accept` to every request and neither is a credential, so reporting the
+      // outgoing header set wholesale would cry wolf on every plain request.
+      const credentialNames = [
+        ...new Set([...Object.keys(staticHeaders), ...Object.keys(fresh ?? {})]),
+      ].sort();
+      warnOnCrossOriginCredentials(url, credentialNames, options.trustedOrigins ?? [], warned);
       if (fresh === undefined) {
         return fetch(url, withCredentials(init, options.credentials));
       }

package/src/core/remote_conversation_store.ts

@@ -40,25 +40,50 @@ type CredentialsProvider = () => RequestCredentials | undefined;
  * the fallback when a request fails. Rename and delete apply optimistically via
  * a local overlay, so the drawer reflects them before the fire-and-forget
  * round-trip lands.
+ *
+ * Pass `cacheMessages: false` to keep message bodies out of the browser
+ * entirely; see the constructor.
  */
 export class RemoteConversationStore implements ClientConversationStore {
   readonly #url: string;
   readonly #headers: HeadersProvider;
   readonly #local: ClientConversationStore;
   readonly #credentials: CredentialsProvider;
+  readonly #cacheMessages: boolean;
   readonly #dropped = new Set<string>();
   readonly #renamed = new Map<string, string>();
 
+  /**
+   * @param cacheMessages Whether to mirror message bodies into the local store.
+   *
+   * `true` (the default, and the behaviour this class has always had) keeps a
+   * local copy of every turn, so the transcript still replays when the thread
+   * endpoint is unreachable. `false` is for the deployment that chose a
+   * server-backed store precisely so transcripts do not sit in the browser:
+   * regulated content, a shared workstation, an operator who has to be able to
+   * say where the conversation lives. It is not the same as passing a local
+   * store that does nothing — the local store also owns the active thread id,
+   * the navigation checkpoint and the "nothing sent here yet" marker, all of
+   * which must keep working — so the opt-out is scoped to the bodies alone.
+   *
+   * The cost is deliberate and worth stating: with no local copy there is
+   * nothing to fall back to, so a failed request shows an empty transcript
+   * rather than a stale one, and the drawer's offline list loses its previews
+   * (a preview is an excerpt of a message, which is the very thing being kept
+   * off the client).
+   */
   constructor(
     url: string,
     headers: HeadersProvider = () => ({}),
     local: ClientConversationStore = new SessionStorageStore(),
     credentials: CredentialsProvider = () => undefined,
+    cacheMessages = true,
   ) {
     this.#url = url.endsWith("/") ? url : `${url}/`;
     this.#headers = headers;
     this.#local = local;
     this.#credentials = credentials;
+    this.#cacheMessages = cacheMessages;
   }
 
   threadId(): string {
@@ -84,8 +109,16 @@ export class RemoteConversationStore implements ClientConversationStore {
   }
 
   saveMessages(threadId: string, messages: readonly Message[]): void {
-    // The agent run persists server-side; keep a local cache for offline replay.
-    this.#local.saveMessages(threadId, messages);
+    // The agent run persists server-side; keep a local cache for offline replay
+    // unless the host asked for the bodies to stay off the client.
+    //
+    // The empty list is not a way of saying "nothing happened". A save is what
+    // retires the local store's minted marker, and `loadMessages` skips the
+    // server for a thread that store still calls unsent — so dropping the call
+    // entirely would leave every thread permanently unsent and its history
+    // unreachable after a reload. Saving an empty list records that the thread
+    // is real without recording a word of what was said in it.
+    this.#local.saveMessages(threadId, this.#cacheMessages ? messages : []);
   }
 
   loadCheckpoint(threadId: string): NavigationCheckpoint | null {

package/src/core/utils.ts

@@ -38,3 +38,61 @@ export function mintThread(store: ClientConversationStore): string {
   store.setActiveThread(id);
   return id;
 }
+
+/**
+ * Announce host credentials about to leave the document's origin.
+ *
+ * `endpoint` and its six sibling URL attributes are plain HTML, and a page that
+ * interpolates one from a query parameter or from tenant-authored
+ * configuration has handed an attacker the destination. The browser preflights
+ * the custom header, any server willing to answer `Access-Control-Allow-Headers`
+ * receives it, and the token leaves on the element's very first request —
+ * before the user has done anything. Nothing else in this package compares a
+ * configured URL against an expected origin, so without this the delivery is
+ * silent, which is the only part of that sequence worth changing.
+ *
+ * A warning rather than a refusal because a cross-origin agent is a documented
+ * deployment: refusing would break working installations to defend against a
+ * page that is already interpolating untrusted data into its own markup. What
+ * it removes is the silence.
+ *
+ * `warned` is supplied by the caller rather than held here, per this package's
+ * rule against shared mutable state: two elements on one page must each get
+ * their own notice, and the set lives exactly as long as its owner.
+ *
+ * Every configured URL goes through this, not the agent endpoint alone. The
+ * tool catalog, the skills list, the thread and attachment endpoints and the
+ * upload target are all named by the same kind of host attribute and all carry
+ * the same headers, so covering one of them and not the rest would report the
+ * least interesting of the seven.
+ */
+export function warnOnCrossOriginCredentials(
+  url: string | URL,
+  credentialNames: readonly string[],
+  trustedOrigins: readonly string[],
+  warned: Set<string>,
+): void {
+  if (credentialNames.length === 0) {
+    return;
+  }
+  // Resolved against the document, so a relative endpoint — the ordinary case —
+  // lands on this origin and says nothing.
+  const destination = new URL(String(url), location.href).origin;
+  if (
+    destination === location.origin ||
+    trustedOrigins.includes(destination) ||
+    warned.has(destination)
+  ) {
+    return;
+  }
+  warned.add(destination);
+  console.warn(
+    `<ag-ui-chat>: sending host credentials (${credentialNames.join(", ")}) to ` +
+      `${destination}, which is not this page's origin (${location.origin}). Those headers ` +
+      "are the page's own authentication, and whichever server answers the browser's " +
+      "preflight receives them — so a URL attribute built from a query parameter or from " +
+      "tenant-authored configuration is a channel for the token to leave on. If this " +
+      "destination is deliberate, name it in `trustedOrigins` to confirm it and " +
+      "silence this notice. Reported once per origin.",
+  );
+}

package/src/tools/is_destructive.ts

@@ -3,8 +3,14 @@ import { X_DESTRUCTIVE_KEY } from "../constants.js";
 /**
  * Whether a tool's JSON-Schema `parameters` marks it destructive.
  *
- * Reads the `x-destructive` extension stamped by the server (`django-ag-ui`'s
- * `build_input_schema`) or by a host declaring a tool directly.
+ * Reads the `x-destructive` extension off a schema the **host** declared —
+ * a tool passed to `registerTool`, or one of the built-ins. A server-side
+ * tool's schema never reaches the browser: tool definitions travel
+ * client-to-server on `RunAgentInput.tools`, and the only channel coming the
+ * other way is the tool catalog (`data-tools-url`), which carries labels, not
+ * schemas. So a server tool marked destructive there is not gated here, and
+ * must be gated server-side instead — the confirmation this flag drives is a
+ * property of tools the browser itself executes.
  */
 export function isDestructive(parameters: Record<string, unknown>): boolean {
   return parameters[X_DESTRUCTIVE_KEY] === true;

package/src/tools/parse_tool_catalog.ts

@@ -7,17 +7,24 @@ export interface ToolCatalogEntry {
   readonly name: string;
   /** A friendly card label for the tool. */
   readonly summary: string;
-  /** Optional longer blurb (e.g. for a future tooltip). */
+  /** Optional longer blurb (e.g. for a tooltip). */
   readonly description?: string;
 }
 
 /**
- * Parse a fetched tool catalog into a `name → summary` map, skipping any entry
+ * Parse a fetched tool catalog into a `name → entry` map, skipping any entry
  * that isn't a `{ name: string, summary: string }` object. Tolerant by design:
- * a malformed payload yields an empty map rather than throwing.
+ * a malformed payload yields an empty map rather than throwing, and an
+ * optional field of the wrong type costs that field rather than the entry.
+ *
+ * Whole entries rather than bare summaries, even though the element itself
+ * only labels cards with `summary`: the map is what a caller gets, so
+ * narrowing it here would put `description` on the wire with nowhere to
+ * arrive, and no consumer could recover it without changing this signature
+ * first.
  */
-export function parseToolCatalog(data: unknown): Record<string, string> {
-  const out: Record<string, string> = {};
+export function parseToolCatalog(data: unknown): Record<string, ToolCatalogEntry> {
+  const out: Record<string, ToolCatalogEntry> = {};
   if (!Array.isArray(data)) {
     return out;
   }
@@ -28,8 +35,13 @@ export function parseToolCatalog(data: unknown): Record<string, string> {
     const record = entry as Record<string, unknown>;
     const name = record["name"];
     const summary = record["summary"];
+    const description = record["description"];
     if (typeof name === "string" && typeof summary === "string") {
-      out[name] = summary;
+      // Built conditionally rather than with an `undefined` field:
+      // `exactOptionalPropertyTypes` makes "absent" and "present as
+      // undefined" different types, and only the former is the wire shape.
+      out[name] =
+        typeof description === "string" ? { name, summary, description } : { name, summary };
     }
   }
   return out;