@artooi/ag-ui-web-component 0.20.1 → 0.21.0

package/src/core/ag_ui_chat.ts

@@ -75,6 +75,7 @@ import { RemoteConversationStore } from "./remote_conversation_store.js";
 import { RunIndex } from "./run_index.js";
 import { type TranscribeHandler, transcribeAudio } from "./transcribe_audio.js";
 import { type UploadHandler, uploadAttachment } from "./upload_attachment.js";
+import { withCredentials } from "./utils.js";
 
 /** The role a rendered chat message takes. */
 export type MessageRole = (typeof MESSAGE_ROLE)[keyof typeof MESSAGE_ROLE];
@@ -133,6 +134,18 @@ const CONNECT_TIME_ATTRIBUTES = [
   "data-icon-url",
 ] as const;
 
+/**
+ * The cookie policies `fetch` accepts. Anything else is a configuration
+ * mistake, and one that would otherwise surface as an unexplained 401 from a
+ * request the browser silently sent anonymously.
+ */
+const CREDENTIALS_MODES: readonly string[] = ["omit", "same-origin", "include"];
+
+/** Whether `value` is one of the three modes `fetch` understands. */
+function isCredentialsMode(value: string): value is RequestCredentials {
+  return CREDENTIALS_MODES.includes(value);
+}
+
 /** Per-tab persistence key for the collapsed state (survives MPA reloads). */
 const COLLAPSED_KEY = "ag-ui-chat:collapsed";
 
@@ -158,9 +171,34 @@ export class AgUiChat extends HTMLElement {
   /** Agent factory; override to inject a custom or fake agent (tests). */
   agentFactory: AgentFactory = createHttpAgent;
 
-  /** Extra HTTP headers for the AG-UI endpoint (e.g. CSRF). */
+  /**
+   * Static extra HTTP headers, sent with **every** request this element makes —
+   * the agent run, the thread index and its messages, the tool and skill
+   * catalogs, the run index, uploads and transcription.
+   *
+   * Right for values fixed for the element's lifetime. A credential that
+   * rotates (a short-lived JWT, a re-issued CSRF token) belongs in
+   * {@link getHeaders} instead: this is read at request time, but only a
+   * re-assignment updates it, so a token captured here is pinned until the host
+   * remembers to assign again.
+   */
   headers: Record<string, string> = {};
 
+  /**
+   * Live header source, consulted immediately before every request — the way to
+   * supply rotating credentials.
+   *
+   * Set it to a function and each request calls it afresh: a token refreshed by
+   * the host between two requests reaches the second one, with nothing to
+   * re-assign and nothing to keep in sync.
+   *
+   * Composes with {@link headers} rather than replacing it: the two are merged
+   * per key with `getHeaders()` winning, so a static `X-Client` and a rotating
+   * `Authorization` can be configured independently and neither silently drops
+   * the other.
+   */
+  getHeaders: (() => Record<string, string>) | null = null;
+
   /**
    * Permit `<img>` in rendered assistant markdown. **Off by default**: a
    * model-controlled image URL is fetched with no user interaction, which
@@ -474,7 +512,11 @@ export class AgUiChat extends HTMLElement {
       return null;
     }
     if (this.#runIndex === null) {
-      this.#runIndex = new RunIndex(url, () => this.headers);
+      this.#runIndex = new RunIndex(
+        url,
+        () => this.#requestHeaders(),
+        () => this.#requestCredentials(),
+      );
     }
     return this.#runIndex;
   }
@@ -507,8 +549,9 @@ export class AgUiChat extends HTMLElement {
     const endpoint = verb === "resume" ? index.resumeUrl(runId) : index.forkUrl(runId);
     const agent = this.agentFactory({
       endpoint,
-      headers: this.headers,
-      getHeaders: () => this.headers,
+      headers: this.#requestHeaders(),
+      getHeaders: () => this.#requestHeaders(),
+      ...this.#credentialsOption(),
       threadId: this.#threadId,
       // The seed the endpoints assume: nothing. The snapshot is the history.
       initialMessages: [],
@@ -533,10 +576,24 @@ export class AgUiChat extends HTMLElement {
 
   /** Attributes the element reacts to after it has been connected. */
   static get observedAttributes(): string[] {
-    return ["title-text", "placement", ...CONNECT_TIME_ATTRIBUTES];
+    return ["title-text", "placement", "credentials", ...CONNECT_TIME_ATTRIBUTES];
   }
 
   attributeChangedCallback(name: string, previous: string | null, value: string | null): void {
+    if (name === "credentials") {
+      // Reported the moment the attribute is written — before connect, and
+      // whether it came from markup or the property setter. An unrecognised
+      // mode is otherwise inert, and the request it was meant to authorise
+      // goes out anonymously with nothing to show for it.
+      if (value !== null && !isCredentialsMode(value)) {
+        console.error(
+          `<ag-ui-chat>: credentials="${value}" is not a fetch credentials mode ` +
+            `(${CREDENTIALS_MODES.join(" / ")}) — it is being ignored, so requests use ` +
+            "the browser default and cross-origin cookies will not be sent.",
+        );
+      }
+      return;
+    }
     if (name === "placement") {
       // A placement owns the axes it fixes, so hand those back before anything
       // else: a size dragged under the previous placement would otherwise sit
@@ -777,6 +834,82 @@ export class AgUiChat extends HTMLElement {
     this.setAttribute("endpoint", value);
   }
 
+  /**
+   * Cookie policy for **every** request this element makes, as `fetch`'s own
+   * `credentials` mode (`"omit"` / `"same-origin"` / `"include"`). Mirrored to
+   * the `credentials` attribute, so markup embeds can set it without script.
+   *
+   * `null` (the default) leaves the browser's default of `same-origin` in
+   * place. That default sends **no cookies at all** when the endpoints live on
+   * a different origin from the page — app.example.com calling
+   * api.example.com is cross-origin — and the request goes out anonymously
+   * rather than failing, so the symptom is a 401 from a server that looks
+   * correctly configured. A cookie-authenticated cross-origin deployment wants
+   * `"include"`, plus `Access-Control-Allow-Credentials: true` and a concrete
+   * (non-wildcard) `Access-Control-Allow-Origin` on the server.
+   *
+   * Read per request, so a late assignment applies to everything after it.
+   * `"omit"` cannot be honoured by the built-in **upload** transport, which is
+   * an `XMLHttpRequest` and only has a two-state cookie switch; every other
+   * endpoint honours all three modes.
+   */
+  get credentials(): RequestCredentials | null {
+    const attr = this.getAttribute("credentials");
+    return attr !== null && isCredentialsMode(attr) ? attr : null;
+  }
+
+  set credentials(value: RequestCredentials | null) {
+    if (value === null) {
+      this.removeAttribute("credentials");
+      return;
+    }
+    // Thrown, not warned: an unrecognised mode is inert at request time, and
+    // the whole failure this option exists to fix is a request that goes out
+    // wrong without saying so. Fail where the mistake was made instead.
+    if (!isCredentialsMode(value)) {
+      throw new TypeError(
+        `<ag-ui-chat>: credentials must be one of ${CREDENTIALS_MODES.map((mode) => `"${mode}"`).join(", ")} ` +
+          `(got ${JSON.stringify(value)}).`,
+      );
+    }
+    this.setAttribute("credentials", value);
+  }
+
+  /**
+   * The headers for the request about to go out: the static {@link headers}
+   * with {@link getHeaders}'s live values overlaid, per key.
+   *
+   * Every request site goes through here, so "how this element authenticates"
+   * is one answer rather than one per endpoint.
+   */
+  #requestHeaders(): Record<string, string> {
+    return { ...this.headers, ...this.getHeaders?.() };
+  }
+
+  /** The configured cookie policy as `fetch` spells it; `undefined` when unset. */
+  #requestCredentials(): RequestCredentials | undefined {
+    return this.credentials ?? undefined;
+  }
+
+  /**
+   * The `credentials` entry for an {@link AgentFactory} call, or nothing at all.
+   *
+   * Spread rather than assigned: `exactOptionalPropertyTypes` rejects an
+   * explicit `credentials: undefined`, and a factory should see the field
+   * absent — not present-and-empty — when no policy is configured. The agent
+   * reads it when it is built (first send, thread switch, continuation), by
+   * which time any host configuration has landed.
+   */
+  #credentialsOption(): { credentials?: RequestCredentials } {
+    const credentials = this.#requestCredentials();
+    return credentials === undefined ? {} : { credentials };
+  }
+
+  /** The `fetch` init for the element's own plain GETs (catalogs). */
+  #fetchInit(): RequestInit | undefined {
+    return withCredentials({ headers: this.#requestHeaders() }, this.#requestCredentials());
+  }
+
   /**
    * How much detail tool-call cards show, from the `data-tool-display`
    * attribute (`minimal` / `inline` / `compact` / `full`). Defaults to `full`.
@@ -833,7 +966,6 @@ export class AgUiChat extends HTMLElement {
     }
     this.#syncRail();
     this.#initSkills();
-    void this.#fetchToolCatalog();
     // Namespace the built-in default store too (a host-injected store is used
     // verbatim). Must precede #wireThreadStore, which wraps the current store.
     if (this.#storageNs !== "" && this.conversationStore instanceof SessionStorageStore) {
@@ -843,12 +975,72 @@ export class AgUiChat extends HTMLElement {
     this.#wireAttachments();
     this.#wireVoice();
     this.#threadId = this.conversationStore.threadId();
+    // The catalog requests go out a microtask later, so a host configuring
+    // through a framework ref still has a chance to be heard — see #startup.
+    queueMicrotask(() => this.#startup());
     void this.#rehydrate();
     // Last: everything above reads (and some of it sets) attributes, and none
     // of that should trip the connect-time warning.
     this.#connected = true;
   }
 
+  /**
+   * The catalog requests the element issues on startup: the tool labels
+   * (`data-tools-url`) and the backend skills (`data-skills-url`).
+   *
+   * Deliberately one microtask behind `connectedCallback`. A host that
+   * configures the element through a framework ref necessarily does so *after*
+   * inserting the node — React attaches refs and runs layout effects in the
+   * same commit as the insertion, but strictly afterwards — so a request issued
+   * from `connectedCallback` itself goes out before `headers`,
+   * {@link getHeaders} or {@link credentials} exist, and comes back 401 in a
+   * way that reads as a server fault rather than a mis-timed assignment. A
+   * microtask lands after that commit and still before paint.
+   *
+   * Two things it is **not**. It is not a fix for configuration that arrives
+   * later than the commit (a passive `useEffect`, an awaited token fetch):
+   * configure before insertion (`createElement` → configure → `append`) or call
+   * {@link reload} once configured, because a longer timer would hide that race
+   * rather than close it. And it deliberately excludes the *history* replay,
+   * which stays in `connectedCallback`: the replay renders into the transcript,
+   * so deferring it lets a `sendMessage()` issued in the same task land first
+   * and the replay then duplicate it. The thread history is therefore the one
+   * request that can still go out before a ref is attached — {@link reload}
+   * covers it.
+   */
+  #startup(): void {
+    // An element can be inserted and removed inside one task (a discarded
+    // render, a double-mount); nothing should go out for a node that has
+    // already left the document.
+    if (!this.#connected) {
+      return;
+    }
+    void this.#fetchToolCatalog();
+    void this.#fetchSkills();
+  }
+
+  /**
+   * Re-run everything the element loads on startup — the tool-label catalog,
+   * the backend skill catalog and the thread's history — with the transport
+   * configuration as it stands now.
+   *
+   * This is the answer for a host that can only configure the element after the
+   * fact (a token fetched in a passive effect, an async auth handshake): the
+   * startup requests already went out with whatever was set then, and this says
+   * "try again, properly authenticated" without removing and re-inserting the
+   * node.
+   *
+   * A reload, not a merge — the in-flight run is cancelled and the transcript
+   * is rebuilt from the persisted history, so anything streamed since is
+   * dropped. Call it once, when configuration lands; not between turns.
+   */
+  async reload(): Promise<void> {
+    this.#cancelRun();
+    this.#resetState();
+    this.#setRunning(false);
+    await Promise.all([this.#fetchToolCatalog(), this.#fetchSkills(), this.#rehydrate()]);
+  }
+
   /**
    * Tear down live resources when the element leaves the DOM (a removed node, a
    * client-side route swap): cancel the in-flight run so its SSE stream closes,
@@ -940,7 +1132,13 @@ export class AgUiChat extends HTMLElement {
     // Forward the tray's abort signal so removing a chip (or tearing the
     // element down) cancels the XHR.
     return (file, onProgress, signal) =>
-      uploadAttachment(file, { url, headers: this.headers, onProgress, signal });
+      uploadAttachment(file, {
+        url,
+        headers: this.#requestHeaders(),
+        ...this.#credentialsOption(),
+        onProgress,
+        signal,
+      });
   }
 
   /**
@@ -969,7 +1167,12 @@ export class AgUiChat extends HTMLElement {
     if (url === null) {
       return null;
     }
-    return (audio) => transcribeAudio(audio, { url, headers: this.headers });
+    return (audio) =>
+      transcribeAudio(audio, {
+        url,
+        headers: this.#requestHeaders(),
+        ...this.#credentialsOption(),
+      });
   }
 
   /** Drop a voice transcript into the composer (appended to any typed text). */
@@ -1050,8 +1253,9 @@ export class AgUiChat extends HTMLElement {
     if (url !== null) {
       this.conversationStore = new RemoteConversationStore(
         url,
-        () => this.headers,
+        () => this.#requestHeaders(),
         this.conversationStore,
+        () => this.#requestCredentials(),
       );
     }
   }
@@ -1063,7 +1267,7 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     try {
-      const response = await fetch(url, { headers: this.headers });
+      const response = await fetch(url, this.#fetchInit());
       this.#toolCatalog = parseToolCatalog(await response.json());
     } catch {
       // Network/parse failure: cards fall back to toolSummaries / raw names.
@@ -1079,13 +1283,16 @@ export class AgUiChat extends HTMLElement {
     this.#recomputeSkills();
   }
 
-  /** Wire the skill surfaces: opt-in flags, embedded catalog, optional fetch. */
+  /**
+   * Wire the skill surfaces: opt-in flags and the embedded catalog. The backend
+   * catalog is fetched from `#startup`, a microtask later, so it carries the
+   * host's transport configuration.
+   */
   #initSkills(): void {
     this.#skillsMenu.enableChips(this.#flag("data-prompt-chips"));
     this.#skillsMenu.enableSlash(this.#flag("data-slash-commands"));
     this.#embedSkills = this.#readEmbeddedSkills();
     this.#recomputeSkills();
-    void this.#fetchSkills();
   }
 
   /** Parse the inline `data-skills` JSON catalog (empty when absent/malformed). */
@@ -1108,7 +1315,7 @@ export class AgUiChat extends HTMLElement {
       return;
     }
     try {
-      const response = await fetch(url, { headers: this.headers });
+      const response = await fetch(url, this.#fetchInit());
       this.#backendSkills = parseSkills(await response.json());
       this.#recomputeSkills();
     } catch {
@@ -1397,6 +1604,34 @@ export class AgUiChat extends HTMLElement {
     this.#themeToggle.textContent = dark ? "☀️" : "🌙";
   }
 
+  /**
+   * Open the thread-history drawer: the imperative route to the control that
+   * renders as `::part(history-button)`.
+   *
+   * A host that hides `::part(header)` to render its own title bar hides the
+   * history, new-chat and collapse buttons with it — and thread switching then
+   * has no route at all, because those controls live inside the header. Each of
+   * them has a method, so a host chrome can rebuild the set: this one,
+   * {@link openCheckpoints}, {@link newChat}, {@link toggleCollapsed} and
+   * {@link toggleTheme}.
+   */
+  openThreads(): void {
+    void this.#refreshDrawer();
+    this.#drawer.open();
+  }
+
+  /**
+   * Open the checkpoints panel (the `::part(checkpoints-button)` route).
+   *
+   * It lists the runs the `data-runs-url` server reports as continuable;
+   * without that attribute the built-in button is never rendered and this opens
+   * an empty panel.
+   */
+  openCheckpoints(): void {
+    void this.#refreshCheckpoints();
+    this.#checkpoints.open();
+  }
+
   /**
    * Start a fresh conversation: forget the persisted history, drop the
    * in-memory run state, clear the transcript, and mint a new thread id.
@@ -1713,17 +1948,13 @@ export class AgUiChat extends HTMLElement {
     controls.className = "header-controls";
     controls.setAttribute("part", "header-controls");
 
+    // Both controls delegate to the public methods, so a host chrome driving
+    // them imperatively takes exactly the path the built-in button takes.
     const history = this.#headerButton("history", this.#strings.chatHistory, "☰");
-    history.addEventListener("click", () => {
-      void this.#refreshDrawer();
-      this.#drawer.open();
-    });
+    history.addEventListener("click", () => this.openThreads());
 
     const checkpoints = this.#headerButton("checkpoints", this.#strings.checkpoints, "⭯");
-    checkpoints.addEventListener("click", () => {
-      void this.#refreshCheckpoints();
-      this.#checkpoints.open();
-    });
+    checkpoints.addEventListener("click", () => this.openCheckpoints());
 
     const newChat = this.#headerButton("new", this.#strings.newChat, "✚");
     newChat.addEventListener("click", () => this.newChat());
@@ -2098,11 +2329,12 @@ export class AgUiChat extends HTMLElement {
     if (this.#client === null) {
       const agent = this.agentFactory({
         endpoint: this.endpoint,
-        headers: this.headers,
+        headers: this.#requestHeaders(),
         // Live getter: the client is built once and cached, but a rotated
         // token must still reach every request — the factory's fetch wrapper
         // re-reads this on each call.
-        getHeaders: () => this.headers,
+        getHeaders: () => this.#requestHeaders(),
+        ...this.#credentialsOption(),
         threadId: this.#threadId,
         initialMessages: this.#initialMessages,
         initialState: this.#sharedState,

package/src/core/create_http_agent.ts

@@ -1,10 +1,20 @@
 import { type AbstractAgent, HttpAgent } from "@ag-ui/client";
 import type { Message } from "@ag-ui/core";
+import { withCredentials } from "./utils.js";
 
 /** Config for {@link createHttpAgent}. */
 export interface HttpAgentOptions {
   endpoint: string;
   headers?: Record<string, string>;
+  /**
+   * Cookie policy for the run request, as `fetch`'s own `credentials` mode.
+   * Unset leaves the browser default (`same-origin`) alone — which sends **no**
+   * cookies when the agent endpoint is on a different origin (or a different
+   * subdomain) from the page. A cookie-authenticated cross-origin deployment
+   * needs `"include"` here, and a server that answers it with
+   * `Access-Control-Allow-Credentials: true` and a concrete origin.
+   */
+  credentials?: RequestCredentials;
   /**
    * Live header source, re-read on **every** request. `HttpAgent` bakes the
    * static `headers` into its constructor and the element caches the agent
@@ -43,17 +53,18 @@ export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
     // "Illegal invocation" in browsers. Wrap it so `fetch` is always called as
     // a free function with the correct receiver. The wrapper also overlays
     // `getHeaders()` per request, so header rotation (CSRF, short-lived JWT)
-    // reaches the stream even though the agent instance is cached.
+    // reaches the stream even though the agent instance is cached, and applies
+    // the configured cookie policy — the agent's own config has no seam for it.
     fetch: (url, init) => {
       const fresh = options.getHeaders?.();
       if (fresh === undefined) {
-        return fetch(url, init);
+        return fetch(url, withCredentials(init, options.credentials));
       }
       const headers = new Headers(init?.headers);
       for (const [name, value] of Object.entries(fresh)) {
         headers.set(name, value);
       }
-      return fetch(url, { ...init, headers });
+      return fetch(url, withCredentials({ ...init, headers }, options.credentials));
     },
     // Spread conditionally: under `exactOptionalPropertyTypes` an explicit
     // `undefined` is not assignable to these optional config fields.

package/src/core/remote_conversation_store.ts

@@ -5,6 +5,7 @@ import {
   SessionStorageStore,
   type ThreadMeta,
 } from "./conversation_store.js";
+import { withCredentials } from "./utils.js";
 
 /** One row of the server thread index (django-ag-ui's `ThreadsView` wire shape). */
 interface ServerThreadRow {
@@ -17,6 +18,14 @@ interface ServerThreadRow {
 /** Live header source, read per request so rotated tokens / CSRF reach the server. */
 type HeadersProvider = () => Record<string, string>;
 
+/**
+ * Live cookie policy, read per request. A provider rather than a value because
+ * the store is built once (on connect) and kept, while a host may configure the
+ * element after inserting it — a captured value would pin whatever was set
+ * during that first frame.
+ */
+type CredentialsProvider = () => RequestCredentials | undefined;
+
 /**
  * A {@link ClientConversationStore} backed by a server thread-index endpoint —
  * django-ag-ui's owner-scoped `ThreadsView`, the URL passed to `<ag-ui-chat>`
@@ -37,6 +46,7 @@ export class RemoteConversationStore implements ClientConversationStore {
   readonly #url: string;
   readonly #headers: HeadersProvider;
   readonly #local: ClientConversationStore;
+  readonly #credentials: CredentialsProvider;
   readonly #dropped = new Set<string>();
   readonly #renamed = new Map<string, string>();
 
@@ -44,10 +54,12 @@ export class RemoteConversationStore implements ClientConversationStore {
     url: string,
     headers: HeadersProvider = () => ({}),
     local: ClientConversationStore = new SessionStorageStore(),
+    credentials: CredentialsProvider = () => undefined,
   ) {
     this.#url = url.endsWith("/") ? url : `${url}/`;
     this.#headers = headers;
     this.#local = local;
+    this.#credentials = credentials;
   }
 
   threadId(): string {
@@ -142,7 +154,7 @@ export class RemoteConversationStore implements ClientConversationStore {
   /** GET that resolves to the `Response`, or `null` on a network error. */
   async #get(url: string): Promise<Response | null> {
     try {
-      return await fetch(url, { headers: this.#headers() });
+      return await fetch(url, withCredentials({ headers: this.#headers() }, this.#credentials()));
     } catch {
       return null;
     }
@@ -156,11 +168,18 @@ export class RemoteConversationStore implements ClientConversationStore {
   ): Promise<void> {
     const headers = this.#headers();
     try {
-      await fetch(`${this.#url}${encodeURIComponent(threadId)}/`, {
-        method,
-        headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
-        body: body === undefined ? null : JSON.stringify(body),
-      });
+      await fetch(
+        `${this.#url}${encodeURIComponent(threadId)}/`,
+        withCredentials(
+          {
+            method,
+            headers:
+              body === undefined ? headers : { ...headers, "content-type": "application/json" },
+            body: body === undefined ? null : JSON.stringify(body),
+          },
+          this.#credentials(),
+        ),
+      );
     } catch {
       // Best-effort; the optimistic overlay keeps the drawer consistent.
     }

package/src/core/run_index.ts

@@ -1,3 +1,5 @@
+import { withCredentials } from "./utils.js";
+
 /** One row of the server run index (django-ag-ui's `RunsView` wire shape). */
 export interface RunRow {
   readonly run_id: string;
@@ -11,6 +13,14 @@ export interface RunRow {
 /** Live header source, read per request so rotated tokens / CSRF reach the server. */
 type HeadersProvider = () => Record<string, string>;
 
+/**
+ * Live cookie policy, read per request. A provider rather than a value because
+ * the index is built once (on connect) and kept, while a host may configure the
+ * element after inserting it — a captured value would pin whatever was set
+ * during that first frame.
+ */
+type CredentialsProvider = () => RequestCredentials | undefined;
+
 /**
  * Reads the server's run index and derives the resume / fork URLs beside it.
  *
@@ -34,10 +44,16 @@ type HeadersProvider = () => Record<string, string>;
 export class RunIndex {
   readonly #url: string;
   readonly #headers: HeadersProvider;
+  readonly #credentials: CredentialsProvider;
 
-  constructor(url: string, headers: HeadersProvider = () => ({})) {
+  constructor(
+    url: string,
+    headers: HeadersProvider = () => ({}),
+    credentials: CredentialsProvider = () => undefined,
+  ) {
     this.#url = url.endsWith("/") ? url : `${url}/`;
     this.#headers = headers;
+    this.#credentials = credentials;
   }
 
   /**
@@ -48,10 +64,16 @@ export class RunIndex {
    */
   async list(): Promise<readonly RunRow[]> {
     try {
-      const response = await fetch(this.#url, {
-        method: "GET",
-        headers: { Accept: "application/json", ...this.#headers() },
-      });
+      const response = await fetch(
+        this.#url,
+        withCredentials(
+          {
+            method: "GET",
+            headers: { Accept: "application/json", ...this.#headers() },
+          },
+          this.#credentials(),
+        ),
+      );
       if (!response.ok) {
         return [];
       }

package/src/core/transcribe_audio.ts

@@ -1,3 +1,5 @@
+import { withCredentials } from "./utils.js";
+
 /**
  * The composer's voice-transcription contract: take a recorded audio `Blob` and
  * resolve to the transcript text. The built-in handler is {@link transcribeAudio}
@@ -13,6 +15,13 @@ export interface TranscribeOptions {
   readonly url: string;
   /** Extra HTTP headers (CSRF / auth), read fresh per request. */
   readonly headers?: Record<string, string>;
+  /**
+   * Cookie policy, as `fetch`'s own `credentials` mode. Unset leaves the
+   * browser default (`same-origin`), which sends no cookies to an endpoint on
+   * another origin; a cookie-authenticated cross-origin deployment needs
+   * `"include"`.
+   */
+  readonly credentials?: RequestCredentials;
 }
 
 /**
@@ -29,11 +38,17 @@ export async function transcribeAudio(audio: Blob, options: TranscribeOptions):
   // reads the blob's content type).
   form.append("audio", audio, "recording.webm");
 
-  const response = await fetch(options.url, {
-    method: "POST",
-    headers: { ...(options.headers ?? {}) },
-    body: form,
-  });
+  const response = await fetch(
+    options.url,
+    withCredentials(
+      {
+        method: "POST",
+        headers: { ...(options.headers ?? {}) },
+        body: form,
+      },
+      options.credentials,
+    ),
+  );
   if (!response.ok) {
     throw new Error(await errorMessage(response));
   }

package/src/core/upload_attachment.ts

@@ -26,6 +26,15 @@ export interface UploadOptions {
   readonly url: string;
   /** Extra HTTP headers (CSRF / auth), read fresh per upload. */
   readonly headers?: Record<string, string>;
+  /**
+   * Cookie policy, spelled as `fetch`'s `credentials` mode for consistency with
+   * the component's other endpoints — but carried by `XMLHttpRequest`, which
+   * only has the two-state `withCredentials`. `"include"` sets it; every other
+   * value leaves it off, which matches `"same-origin"`. `"omit"` therefore
+   * **cannot** be honoured for a same-origin upload (XHR always sends cookies
+   * there); use a custom {@link UploadHandler} if that matters.
+   */
+  readonly credentials?: RequestCredentials;
   /** Progress callback, `0..1`, fired as the body uploads. */
   readonly onProgress?: (fraction: number) => void;
   /** Abort signal to cancel the in-flight upload. */
@@ -48,6 +57,10 @@ export function uploadAttachment(file: File, options: UploadOptions): Promise<At
 
     const xhr = new XMLHttpRequest();
     xhr.open("POST", options.url);
+    // Cross-origin cookies ride only when asked for, exactly as with the fetch
+    // sites; without this an upload to another subdomain is anonymous and 401s
+    // while the run itself succeeds.
+    xhr.withCredentials = options.credentials === "include";
     for (const [key, value] of Object.entries(options.headers ?? {})) {
       xhr.setRequestHeader(key, value);
     }