@artooi/ag-ui-web-component 0.26.1 → 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;
@@ -408,6 +415,9 @@ export class AgUiClient {
   #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
     const closed = this.#closedMessageIds;
+    // Read at event time, not captured now: the flag flips mid-run, and the
+    // subscriber is built before the run that a later `cancel()` stops.
+    const cancelled = (): boolean => this.#cancelled;
     // Charts whose patch has been dispatched but not yet applied. Scoped to the
     // subscriber, so it cannot outlive the run that created it.
     const pendingDeltas = new Set<string>();
@@ -494,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();
       },
@@ -510,6 +530,15 @@ export class AgUiClient {
       onRunErrorEvent({ event }) {
         runState.terminal = true;
         runState.errored = true;
+        // Cancelling aborts the response mid-read, and the browser's own words
+        // for that can arrive here as a RUN_ERROR — Chrome's is
+        // "BodyStreamBuffer was aborted". The run is over either way, but a
+        // deliberate stop is not a failure, and reporting it would raise a
+        // warning bubble above the stopped note saying the same thing twice.
+        // The promise route in `#run` reports the cancellation.
+        if (cancelled()) {
+          return;
+        }
         h.onError(event.message);
       },
       onRunFinalized() {
@@ -532,7 +561,19 @@ interface RunState {
  * Whether a rejection came from aborting the run's fetch. Belt-and-suspenders
  * with the `#cancelled` flag: some `@ag-ui/client` versions re-throw the
  * `AbortError` instead of filtering it.
+ *
+ * Aborting a fetch whose body is mid-read does not always surface as an
+ * `AbortError`. Chrome raises `TypeError: BodyStreamBuffer was aborted`, which
+ * is the same event wearing a different name, so a message naming the abort is
+ * read as one too. Narrow on purpose: only a `TypeError`, and only when it says
+ * so — a genuine type error carries no such word, and misreading one as a
+ * cancellation would hide a real failure behind a stopped note.
  */
 function isAbortError(error: unknown): boolean {
-  return error instanceof Error && error.name === "AbortError";
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return (
+    error.name === "AbortError" || (error instanceof TypeError && /abort/i.test(error.message))
+  );
 }

package/src/core/conversation_store.ts

@@ -36,12 +36,24 @@ export interface ThreadMeta {
  * is a small local hint a server store can derive from history and no-op.
  *
  * Thread enumeration backs the chat-history drawer; deleting a thread reuses
- * {@link clear} and "new chat" reuses {@link threadId} after clearing the
- * active thread.
+ * {@link clear}, and "new chat" is {@link newThread} — which leaves the
+ * conversation it moves off of intact, for the drawer to offer back.
  */
 export interface ClientConversationStore {
   /** The active conversation id, generated and persisted on first read. */
   threadId(): string;
+  /**
+   * Start a fresh conversation, make it active, and return its id.
+   *
+   * Existing threads are left where they are: "new chat" adds one, and
+   * {@link clear} is the only method that takes one away.
+   *
+   * Optional, so a store written before this method existed still works. The
+   * caller then mints the id itself and hands it to {@link setActiveThread},
+   * which loses only the store's own record that the thread is new (see
+   * {@link isUnsent}).
+   */
+  newThread?(): string;
   /** Load the persisted message history, or `null` when none exists. */
   loadMessages(threadId: string): Promise<readonly Message[] | null>;
   /** Persist the message history (and refresh the thread's drawer metadata). */
@@ -90,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;
@@ -110,27 +165,70 @@ 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);
     }
   }
 
-  threadId(): string {
-    const key = this.#key(THREAD_SUFFIX);
-    const existing = sessionStorage.getItem(key);
-    if (existing !== null) {
-      return existing;
+  /**
+   * 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);
     }
+  }
+
+  threadId(): string {
+    return sessionStorage.getItem(this.#key(THREAD_SUFFIX)) ?? this.newThread();
+  }
+
+  newThread(): string {
     const id = randomUUID();
-    sessionStorage.setItem(key, id);
-    sessionStorage.setItem(this.#key(MINTED_SUFFIX + id), "1");
+    writeStoredItem(this.#key(THREAD_SUFFIX), id);
+    writeStoredItem(this.#key(MINTED_SUFFIX + id), "1");
     return id;
   }
 
@@ -146,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);
   }
@@ -161,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 {
@@ -185,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 {
@@ -233,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). */
@@ -241,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);
@@ -286,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

@@ -5,7 +5,7 @@ import {
   SessionStorageStore,
   type ThreadMeta,
 } from "./conversation_store.js";
-import { withCredentials } from "./utils.js";
+import { mintThread, withCredentials } from "./utils.js";
 
 /** One row of the server thread index (django-ag-ui's `ThreadsView` wire shape). */
 interface ServerThreadRow {
@@ -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 {
@@ -69,14 +94,31 @@ export class RemoteConversationStore implements ClientConversationStore {
     this.#local.setActiveThread(threadId);
   }
 
+  /**
+   * Delegated to the local store, which owns the active id — and deliberately
+   * silent on the wire: the server learns of a thread when its first message is
+   * persisted, so an abandoned new chat costs no round-trip and leaves no row.
+   */
+  newThread(): string {
+    return mintThread(this.#local);
+  }
+
   /** Delegated, so wrapping a store does not lose what it knows about its own ids. */
   isUnsent(threadId: string): boolean {
     return this.#local.isUnsent?.(threadId) === true;
   }
 
   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

@@ -1,4 +1,7 @@
-// Non-exported-from-index helpers shared by the core transport modules.
+// Non-exported-from-index helpers shared by the core modules.
+
+import { randomUUID } from "@ag-ui/client";
+import type { ClientConversationStore } from "./conversation_store.js";
 
 /**
  * Overlay a `credentials` mode onto a fetch `init`, or hand the `init` back
@@ -14,3 +17,82 @@ export function withCredentials(
 ): RequestInit | undefined {
   return credentials === undefined ? init : { ...init, credentials };
 }
+
+/**
+ * Start a new conversation in `store` and return its id.
+ *
+ * `newThread` is optional on the interface, so a store that predates it is
+ * driven the only other way the interface allows: mint an id here and make it
+ * active. That path loses the store's own note that the thread is new, so a
+ * remote store would go on to ask the server for a conversation that cannot
+ * exist yet — which is why every store in this package implements the method.
+ *
+ * What neither path does is clear the thread being left behind. Starting a
+ * conversation is not a reason to destroy the previous one.
+ */
+export function mintThread(store: ClientConversationStore): string {
+  if (store.newThread !== undefined) {
+    return store.newThread();
+  }
+  const id = randomUUID();
+  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;