@artooi/ag-ui-web-component 0.22.0 → 0.23.1

package/src/core/agui_client.ts

@@ -33,9 +33,9 @@ export interface ToolExecution {
 /**
  * Executes a frontend tool call.
  *
- * Returns the {@link ToolExecution} to post back to the agent, or ``null`` when
- * the call is not a frontend tool the host owns (a server-side tool the server
- * already executed — the client must not re-run for it).
+ * Returns the {@link ToolExecution} to post back to the agent, or `null` when
+ * the call is not a frontend tool the host owns — a server-side tool the server
+ * already executed, which the client must not re-run.
  */
 export type ExecuteTool = (call: AgUiToolCall) => Promise<ToolExecution | null>;
 
@@ -50,11 +50,10 @@ export type InterruptResponse = { status: "resolved"; payload?: unknown } | { st
 /**
  * Resolves the approval interrupts a run finished on, keyed by interrupt id.
  *
- * When a gated **server-side** tool defers instead of executing, the run
- * finishes on an AG-UI interrupt outcome; the host renders an approval card per
- * interrupt and returns each decision here, and the loop resumes the run with
- * the answers. Omit for agents that never gate server-side tools — an
- * unresolved interrupt then simply ends the loop.
+ * A gated server-side tool defers instead of executing, so the run finishes on
+ * an interrupt outcome; the host collects one decision per interrupt and the
+ * loop resumes with the answers. Omit for agents that never gate server-side
+ * tools — an unresolved interrupt then ends the loop.
  */
 export type ResolveInterrupts = (
   interrupts: readonly Interrupt[],
@@ -67,9 +66,9 @@ export type ResolveInterrupts = (
  */
 export interface AgUiClientHandlers {
   onRunStart(): void;
-  /** Fired on every streamed token; ``buffer`` is the full text so far. */
+  /** Fired on every streamed token; `buffer` is the full text so far. */
   onTextDelta(buffer: string): void;
-  /** Fired when the assistant message completes; ``buffer`` is the final text. */
+  /** Fired when the assistant message completes; `buffer` is the final text. */
   onTextEnd(buffer: string): void;
   /** Fired when the agent finishes calling a tool (server- or frontend-side). */
   onToolCall(call: AgUiToolCall): void;
@@ -95,17 +94,15 @@ export interface AgUiClientHandlers {
   onError(message: string): void;
   /**
    * Fired when the user cancelled the run ({@link AgUiClient.cancel}) — the
-   * deliberate-stop sibling of `onError`. Any partial assistant text already
-   * streamed stays valid; the host should keep the bubble and show a muted
-   * "stopped" affordance rather than an error. `onSettled` still follows.
+   * deliberate-stop sibling of `onError`. Partial assistant text already
+   * streamed stays valid, so the host keeps the bubble and shows a stopped
+   * affordance rather than an error. `onSettled` still follows.
    */
   onCancelled(): void;
   /**
-   * Fired exactly once when the whole interaction settles — after the run loop
-   * ends for any reason (a server-only round, frontend-tool rounds exhausted,
-   * a cancellation, or an error). The terminal guarantee that the UI returns
-   * to rest (pending indicator cleared, input re-enabled) no matter how the
-   * run finished.
+   * Fired exactly once when the interaction settles, however the run loop ended
+   * — server-only round, rounds exhausted, cancellation, or error. The terminal
+   * guarantee that the UI returns to rest.
    */
   onSettled(): void;
 }
@@ -138,17 +135,15 @@ export interface AgUiClientConfig extends AgUiRunInputs {
    */
   onPersist?: (messages: readonly Message[]) => void;
   /**
-   * Called whenever AG-UI shared state changes — the server streamed a
-   * `STATE_SNAPSHOT` / `STATE_DELTA`, or {@link AgUiClient.setState} was
-   * called. `@ag-ui/client` owns applying those events; this only forwards
-   * the result so a host can react.
+   * Called whenever AG-UI shared state changes — a streamed `STATE_SNAPSHOT` /
+   * `STATE_DELTA`, or {@link AgUiClient.setState}. `@ag-ui/client` owns applying
+   * those events; this only forwards the result.
    */
   onStateChanged?: (state: Readonly<Record<string, unknown>>) => void;
   /**
-   * Error text surfaced to {@link AgUiClientHandlers.onError} when a run's
-   * stream closes without a terminal AG-UI event (`RUN_FINISHED`/`RUN_ERROR`) —
-   * a dropped connection. Defaults to `"Connection lost"`; the host passes its
-   * localized string.
+   * Error text for {@link AgUiClientHandlers.onError} when a run's stream closes
+   * without a terminal AG-UI event. Defaults to `"Connection lost"`; the host
+   * passes its localized string.
    */
   connectionLostMessage?: string;
 }
@@ -182,10 +177,9 @@ export class AgUiClient {
   readonly #resolveInterrupts: ResolveInterrupts | null;
   readonly #onPersist: (messages: readonly Message[]) => void;
   /**
-   * Message ids the server has already closed, so a reuse can be reported.
-   *
-   * Per client rather than per run: the merge happens across runs, which is the
-   * case a per-run set would miss entirely.
+   * Message ids the server has already closed, so a reuse can be reported. Per
+   * client rather than per run — the merge happens across runs, which a per-run
+   * set would miss entirely.
    */
   readonly #closedMessageIds = new Set<string>();
   readonly #connectionLostMessage: string;
@@ -205,8 +199,8 @@ export class AgUiClient {
     const onStateChanged = config.onStateChanged;
     if (onStateChanged !== undefined) {
       // The agent applies STATE_SNAPSHOT / STATE_DELTA itself; subscribing is
-      // how we learn the result rather than re-deriving it from the event
-      // stream. Lives for the agent's lifetime, which is this client's.
+      // how the result is learned rather than re-derived from the event stream.
+      // Lives for the agent's lifetime, which is this client's.
       this.#agent.subscribe({
         onStateChanged: ({ state }) => {
           onStateChanged(state as Record<string, unknown>);
@@ -243,9 +237,8 @@ export class AgUiClient {
    * tools (bounded by {@link MAX_TOOL_ROUNDS}).
    *
    * `attachments` ride on the user message as a non-standard field so the
-   * default client store round-trips them for history replay; the agent learns
-   * the ids from the run context (the server's strict validation ignores the
-   * unknown message field), then reads bytes via the `read_attachment` tool.
+   * default store round-trips them for history replay; see
+   * {@link messageAttachments}.
    */
   async send(content: string, attachments: readonly AttachmentRef[] = []): Promise<void> {
     // Cast at the AG-UI boundary: `attachments` is a web-component augmentation
@@ -263,7 +256,7 @@ export class AgUiClient {
   /**
    * Resume the run loop after a navigating tool's result was supplied
    * post-reload (via {@link addToolResult}). Unlike {@link send}, adds no user
-   * message — it simply continues the conversation already in history.
+   * message; it continues the conversation already in history.
    */
   async resume(): Promise<void> {
     await this.#run();
@@ -309,21 +302,21 @@ export class AgUiClient {
   }
 
   #onCancelled(): void {
-    // The truncated exchange (including any partial assistant text the agent
-    // already applied) survives a reload.
+    // Persist so the truncated exchange, partial assistant text included,
+    // survives a reload.
     this.#onPersist(this.#agent.messages);
     this.#handlers.onCancelled();
   }
 
   async #runLoop(): Promise<void> {
-    // Carries the resolved approval answers into the *next* run when a round
-    // finished on a server-side-tool interrupt. Distinct from the public
-    // resume() navigation-reload path (which continues an unfinished
-    // frontend-tool round after a page load) — this stays inside one #run().
+    // Carries resolved approval answers into the next run when a round finished
+    // on a server-side-tool interrupt. Distinct from the public resume(), which
+    // continues an unfinished frontend-tool round after a page load; this stays
+    // inside one #run().
     let resume: ResumeEntry[] | undefined;
     for (let round = 0; round < MAX_TOOL_ROUNDS; round += 1) {
-      // A cancel during the previous round's frontend-tool execution lands
-      // here: the running handler completed, but no further round starts.
+      // A cancel during the previous round's tool execution lands here: the
+      // running handler completed, but no further round starts.
       if (this.#cancelled) {
         return;
       }
@@ -339,29 +332,28 @@ export class AgUiClient {
       await this.#agent.runAgent(params, this.#buildSubscriber(pending, runState));
       resume = undefined;
       this.#onPersist(this.#agent.messages);
-      // Cancelled mid-stream: the user said stop — don't execute the tool
-      // calls collected before the abort.
+      // Cancelled mid-stream: don't execute the tool calls collected before the
+      // abort.
       if (this.#cancelled) {
         return;
       }
-      // The stream resolved without RUN_FINISHED / RUN_ERROR: the transport
-      // dropped mid-run. Surface it as an error so the UI doesn't rest silently
-      // with a stuck pending indicator (caught by #run → onError).
+      // The stream resolved without RUN_FINISHED / RUN_ERROR, so the transport
+      // dropped mid-run. Surface it as an error (via #run) rather than resting
+      // silently with a stuck pending indicator.
       if (!runState.terminal) {
         throw new ConnectionLostError(this.#connectionLostMessage);
       }
-      // RUN_ERROR is terminal: the agent already reported the failure via
-      // onError. Don't execute the tool calls collected before it or start
-      // another round — that would run into a broken context and surface a
-      // confusing second error. Any pending tool card is swept at onSettled.
+      // RUN_ERROR is terminal and the agent already reported it via onError.
+      // Executing the calls collected before it, or starting another round,
+      // would run into a broken context and raise a confusing second error.
+      // Pending tool cards are swept at onSettled.
       if (runState.errored) {
         return;
       }
-      // A gated server-side tool deferred instead of executing: the run finished
-      // on an interrupt outcome. Ask the host to resolve each interrupt, then
-      // re-enter the loop carrying the answers — the follow-up run runs or denies
-      // the tool (its result streams back as TOOL_CALL_RESULT). Takes precedence
-      // over the frontend-tool sweep below: a server-side tool isn't ours to run.
+      // A gated server-side tool deferred, so the run finished on an interrupt
+      // outcome: resolve each interrupt, then re-enter carrying the answers so
+      // the follow-up run executes or denies the tool. Must precede the
+      // frontend-tool sweep below — a server-side tool isn't ours to run.
       if (runState.interrupts.length > 0) {
         if (this.#resolveInterrupts === null) {
           return;
@@ -410,13 +402,10 @@ export class AgUiClient {
         h.onRunStart();
       },
       onTextMessageStartEvent({ event }) {
-        // A server that reuses a message id gets its two answers merged into
-        // one transcript entry, silently, and that merged entry is what gets
-        // persisted. The protocol has no rule to enforce here and refusing the
-        // event would be worse than the merge, so this warns and continues —
-        // but it should not be silent, because the corruption outlives the
-        // session and reads as a client bug. Found by a demo harness doing
-        // exactly this.
+        // A reused message id merges two answers into one persisted transcript
+        // entry. The protocol has no rule to enforce and refusing the event
+        // would be worse than the merge, so warn and continue — but do not stay
+        // silent, since the corruption outlives the session.
         if (closed.has(event.messageId)) {
           console.warn(
             `<ag-ui-chat>: the server reused message id "${event.messageId}", which was ` +
@@ -448,9 +437,9 @@ export class AgUiClient {
       onActivitySnapshotEvent({ event }) {
         h.onActivity(event.activityType, event.content);
       },
-      // Reasoning. `@ag-ui/client` already maps the deprecated
-      // THINKING_* events onto these REASONING_* callbacks, so handling the
-      // reasoning family alone covers both protocol versions.
+      // `@ag-ui/client` maps the deprecated THINKING_* events onto these
+      // REASONING_* callbacks, so the reasoning family alone covers both
+      // protocol versions.
       onReasoningStartEvent() {
         h.onReasoningStart();
       },
@@ -462,9 +451,9 @@ export class AgUiClient {
       },
       onRunFinishedEvent(params) {
         // RUN_FINISHED is terminal for both a normal finish and an interrupt.
-        // Capturing the interrupts here (rather than reading the agent's
-        // `pendingInterrupts` field afterwards) keeps the loop self-contained
-        // and independent of that field's cross-run clearing semantics.
+        // Capture the interrupts here rather than reading the agent's
+        // `pendingInterrupts` afterwards, to stay independent of that field's
+        // cross-run clearing semantics.
         runState.terminal = true;
         if (params.outcome === "interrupt") {
           runState.interrupts = params.interrupts;

package/src/core/attachment.ts

@@ -4,11 +4,9 @@ import type { Message } from "@ag-ui/core";
  * A durable, lightweight reference to one uploaded file — what an upload
  * returns and what rides on a sent message, never the bytes.
  *
- * Mirrors django-ag-ui's `AttachmentRef`: a file uploads out-of-band to the
+ * Mirrors django-ag-ui's `AttachmentRef`: the file uploads out-of-band to the
  * attachments endpoint, the server hands back this ref, and the agent reads the
- * actual content server-side via the `read_attachment` tool. Keeping the AG-UI
- * message stream free of base64 mirrors how the tool catalog keeps schemas off
- * the wire.
+ * content server-side via the `read_attachment` tool.
  */
 export interface AttachmentRef {
   /** Opaque, owner-scoped handle the server resolves back to bytes. */
@@ -26,17 +24,14 @@ export interface AttachmentRef {
 /**
  * The attachment refs a user message carries.
  *
- * Refs are stored on the user message as a non-standard `attachments` field: a
- * web-component augmentation that the default client store round-trips and
- * `@ag-ui/client` preserves through `addMessage` / `structuredClone`, so a
- * restored conversation re-renders its attachment chips. The server's strict
- * `RunAgentInput` validation ignores the unknown field — the model learns the
- * ids from the run context manifest instead.
+ * Refs ride on the message as a non-standard `attachments` field, which the
+ * default store round-trips and `@ag-ui/client` preserves through `addMessage`
+ * / `structuredClone`, so a restored conversation re-renders its chips. The
+ * server's strict `RunAgentInput` validation ignores the unknown field.
  *
- * The persisted array is untrusted (it can be hand-edited, truncated, or
- * corrupted in storage), so every entry is validated and malformed ones are
- * dropped — a `null` or shapeless entry would otherwise throw in `iconFor` and
- * abort the whole history replay.
+ * Storage is untrusted — hand-edited, truncated, or corrupted — so malformed
+ * entries are dropped here; a shapeless one would throw in `iconFor` and abort
+ * the whole history replay.
  */
 export function messageAttachments(message: Message): readonly AttachmentRef[] {
   const refs = (message as { attachments?: unknown }).attachments;

package/src/core/conversation_store.ts

@@ -13,13 +13,11 @@ export interface NavigationCheckpoint {
 }
 
 /**
- * Lightweight metadata for one conversation — the thread-drawer row shape.
- *
- * Returned by {@link ClientConversationStore.listThreads} so the drawer can
- * render a list without loading message bodies. `title` defaults to a
- * truncation of the first user message (until an explicit rename); `preview`
- * is a one-line excerpt of the latest message; `updatedAt` is epoch ms of the
- * last change, used to order the list.
+ * Lightweight metadata for one conversation — the thread-drawer row shape, so
+ * the drawer renders without loading message bodies. `title` defaults to a
+ * truncation of the first user message until an explicit rename, `preview` is a
+ * one-line excerpt of the latest message, and `updatedAt` is epoch ms of the
+ * last change, which orders the list.
  */
 export interface ThreadMeta {
   readonly threadId: string;
@@ -32,16 +30,14 @@ export interface ThreadMeta {
  * Client-side persistence seam for the conversation and a pending-navigation
  * checkpoint, keyed by `thread_id`.
  *
- * The default {@link SessionStorageStore} keeps everything per-tab in
- * `sessionStorage`, so the chat survives the full page reloads of a
- * multi-page app. A host may inject a server-backed store instead (e.g. one
- * that rehydrates from a history endpoint); `loadMessages` and `listThreads`
- * are therefore async-friendly. The checkpoint methods stay synchronous — the
- * marker is a tiny local hint a server store can derive from history and no-op.
+ * The default {@link SessionStorageStore} keeps everything per-tab. A host may
+ * inject a server-backed store instead, which is why `loadMessages` and
+ * `listThreads` are async. The checkpoint methods stay synchronous: the marker
+ * is a small local hint a server store can derive from history and no-op.
  *
- * Thread enumeration (`listThreads` / `setActiveThread` / `renameThread`) backs
- * the chat-history drawer; "delete a thread" reuses {@link clear} and "new
- * chat" reuses {@link threadId} after clearing the active thread.
+ * Thread enumeration backs the chat-history drawer; deleting a thread reuses
+ * {@link clear} and "new chat" reuses {@link threadId} after clearing the
+ * active thread.
  */
 export interface ClientConversationStore {
   /** The active conversation id, generated and persisted on first read. */
@@ -86,18 +82,15 @@ interface StoredThread {
 /**
  * Default {@link ClientConversationStore}: per-tab `sessionStorage`.
  *
- * Survives full page reloads and same-tab navigation, clears on tab close —
- * the right scope for an embedded agent's conversation in a multi-page app.
- * 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.
+ * Survives full page reloads and same-tab navigation, clears on tab close.
+ * Tracks multiple threads per tab: the active id under one key, message history
+ * and checkpoint namespaced by id, and a small index feeding the drawer with no
+ * server involved.
  *
- * 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.
+ * 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}.
  */
 export class SessionStorageStore implements ClientConversationStore {
   readonly #root: string;
@@ -219,12 +212,11 @@ export class SessionStorageStore implements ClientConversationStore {
   }
 
   /**
-   * 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.
+   * 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}:`;

package/src/core/create_http_agent.ts

@@ -8,20 +8,18 @@ export interface HttpAgentOptions {
   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.
+   * Unset leaves the browser default (`same-origin`), which sends no cookies
+   * to an agent endpoint on a different origin or subdomain. A
+   * cookie-authenticated cross-origin deployment needs `"include"` here plus a
+   * server answering 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
-   * for the whole conversation — so a rotated token (CSRF, short-lived JWT)
-   * would otherwise never reach the agent endpoint and a long session 401s
-   * mid-conversation. When set, the fetch wrapper overlays these values on
-   * each call; `headers` still seeds the initial/static configuration.
+   * Live header source, re-read on every request, overlaid on `headers`.
+   * `HttpAgent` bakes static `headers` in at construction and the element
+   * caches the agent for the whole conversation, so rotating credentials (CSRF,
+   * short-lived JWT) must come through here.
    */
   getHeaders?: () => Record<string, string>;
   /** Stable conversation id, so the agent's runs share a thread. */
@@ -37,11 +35,11 @@ export interface HttpAgentOptions {
 }
 
 /**
- * Build an AG-UI {@link HttpAgent} pointed at ``endpoint``.
+ * Build an AG-UI {@link HttpAgent} pointed at `endpoint`.
  *
- * This is the default agent factory used by ``<ag-ui-chat>``. Tests and
- * advanced hosts override the element's ``agentFactory`` to inject a
- * different {@link AbstractAgent} (e.g. a fake, or a middleware-wrapped one).
+ * The default agent factory for `<ag-ui-chat>`; tests and advanced hosts
+ * override the element's `agentFactory` to inject a different
+ * {@link AbstractAgent}.
  */
 export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
   return new HttpAgent({
@@ -49,12 +47,10 @@ export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
     headers: options.headers ?? {},
     initialState: { ...(options.initialState ?? {}) },
     // HttpAgent invokes its configured fetch as a method (`this.fetch(...)`),
-    // which would rebind the global `fetch` to the agent instance and trigger
-    // "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, and applies
-    // the configured cookie policy — the agent's own config has no seam for it.
+    // rebinding the global `fetch` to the agent instance — "Illegal invocation"
+    // in browsers. The wrapper keeps `fetch` a free call, and is also where the
+    // per-request `getHeaders()` overlay and the cookie policy go, the agent's
+    // own config having no seam for either.
     fetch: (url, init) => {
       const fresh = options.getHeaders?.();
       if (fresh === undefined) {
@@ -67,7 +63,7 @@ export function createHttpAgent(options: HttpAgentOptions): AbstractAgent {
       return fetch(url, withCredentials({ ...init, headers }, options.credentials));
     },
     // Spread conditionally: under `exactOptionalPropertyTypes` an explicit
-    // `undefined` is not assignable to these optional config fields.
+    // `undefined` is not assignable to an optional field.
     ...(options.threadId !== undefined ? { threadId: options.threadId } : {}),
     ...(options.initialMessages !== undefined
       ? { initialMessages: [...options.initialMessages] }

package/src/core/remote_conversation_store.ts

@@ -19,10 +19,9 @@ interface ServerThreadRow {
 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.
+ * Live cookie policy, read per request. A provider rather than a value: the
+ * store is built once on connect, but a host may configure the element after
+ * inserting it, and a captured value would pin that first frame's setting.
  */
 type CredentialsProvider = () => RequestCredentials | undefined;
 
@@ -36,11 +35,11 @@ type CredentialsProvider = () => RequestCredentials | undefined;
  * - `PATCH <url><id>/`  → rename (`{ "title": … }`);
  * - `DELETE <url><id>/` → delete.
  *
- * It wraps a local store (default {@link SessionStorageStore}) for the
- * client-only concerns — the active thread id, the navigation checkpoint, and a
- * message cache — and as the graceful fallback when a request fails. Rename and
- * delete apply **optimistically** (a small local overlay) so the drawer
- * reflects them at once, before the fire-and-forget server round-trip lands.
+ * Wraps a local store (default {@link SessionStorageStore}) for the client-only
+ * concerns — active thread id, navigation checkpoint, message cache — and as
+ * 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.
  */
 export class RemoteConversationStore implements ClientConversationStore {
   readonly #url: string;
@@ -108,9 +107,9 @@ export class RemoteConversationStore implements ClientConversationStore {
     if (response === null || !response.ok) {
       return this.#local.loadMessages(threadId);
     }
-    // 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.
+    // A 200 whose body isn't 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.
     const body = await this.#readJson<{ messages?: readonly Message[] }>(response);
     if (body === null) {
       return this.#local.loadMessages(threadId);
@@ -143,9 +142,9 @@ export class RemoteConversationStore implements ClientConversationStore {
     return {
       threadId: row.thread_id,
       title: this.#renamed.get(row.thread_id) ?? row.title,
-      // `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".
+      // `null` and an unparseable date both become NaN, Date.parse's own
+      // signal, which `relativeTime` renders as a neutral label rather than an
+      // epoch-0 or NaN duration.
       updatedAt: row.updated_at === null ? Number.NaN : Date.parse(row.updated_at),
       preview: row.preview,
     };

package/src/core/run_index.ts

@@ -13,12 +13,7 @@ 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.
- */
+/** Live cookie policy, read per request; see `RemoteConversationStore`'s note. */
 type CredentialsProvider = () => RequestCredentials | undefined;
 
 /**
@@ -29,17 +24,14 @@ type CredentialsProvider = () => RequestCredentials | undefined;
  *
  * - `GET <url>` → the user's runs, newest first.
  *
- * **Only `continuable` rows can be resumed.** The server reports whether a run
- * has a saved snapshot to seed from; a run that never reached a provider-valid
- * boundary has none, so resuming it would start from nothing. Callers should
- * offer the action only for those rows and treat the rest as informational — a
- * crashed run worth showing, not worth continuing. {@link continuable} filters
- * for exactly that.
+ * Only `continuable` rows can be resumed: the server reports whether a run has
+ * a saved snapshot to seed from, and a run that never reached a provider-valid
+ * boundary has none. Offer the action only for those rows ({@link continuable}
+ * filters them) and treat the rest as informational.
  *
- * **Resume and fork are siblings of the index**, not separate configuration.
- * django-ag-ui mounts all three under one prefix whenever a step store is
- * configured (`runs/`, `resume/<id>/`, `fork/<id>/`), so one URL locates them
- * all and there is no way to configure a half-working set.
+ * Resume and fork are siblings of the index rather than separate configuration
+ * — django-ag-ui mounts `runs/`, `resume/<id>/` and `fork/<id>/` under one
+ * prefix — so this one URL locates all three.
  */
 export class RunIndex {
   readonly #url: string;
@@ -57,10 +49,9 @@ export class RunIndex {
   }
 
   /**
-   * The user's runs, or `[]` when the endpoint is unreachable or answers with
-   * an error. A history affordance that cannot load is empty, never broken:
-   * the caller renders its empty state rather than surfacing a transport fault
-   * the user can do nothing about.
+   * The user's runs, or `[]` when the endpoint is unreachable or errors — the
+   * caller renders its empty state rather than a transport fault the user can
+   * do nothing about.
    */
   async list(): Promise<readonly RunRow[]> {
     try {
@@ -102,9 +93,9 @@ export class RunIndex {
   /**
    * `<mount>/<verb>/<runId>/`, derived from the index URL's own prefix.
    *
-   * Built by string surgery on the trailing `runs/` rather than with `new URL`,
-   * because the configured value may be root-relative (`/agent/runs/`) — the
-   * common case in a Django template — and `new URL` needs an absolute base.
+   * String surgery on the trailing `runs/` rather than `new URL`, because the
+   * configured value may be root-relative (`/agent/runs/`), the common case in
+   * a Django template, and `new URL` needs an absolute base.
    */
   #sibling(verb: string, runId: string): string {
     const prefix = this.#url.slice(0, -"runs/".length);

package/src/core/transcribe_audio.ts

@@ -2,10 +2,10 @@ 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}
- * (multipart POST to `data-transcribe-url`); a host swaps in its own — e.g. a
- * browser Web Speech adapter or a direct-to-provider call — via
- * `AgUiChat.transcribeHandler`, without touching the mic button.
+ * resolve to the transcript text. The built-in handler is
+ * {@link transcribeAudio}; a host swaps in its own (a Web Speech adapter, a
+ * direct-to-provider call) via `AgUiChat.transcribeHandler` without touching
+ * the mic button.
  */
 export type TranscribeHandler = (audio: Blob) => Promise<string>;
 
@@ -27,15 +27,14 @@ export interface TranscribeOptions {
 /**
  * POST a recorded clip to the transcription endpoint and resolve to its text.
  *
- * The clip is sent as multipart under the `audio` field with the element's
- * `headers`, mirroring {@link uploadAttachment}; the server replies
- * `{ "text": "<transcript>" }`. A non-2xx response or a network error rejects so
- * the mic button can surface the failure.
+ * The clip goes as multipart under the `audio` field with the element's
+ * `headers`, mirroring {@link uploadAttachment}, and the server replies
+ * `{ "text": "<transcript>" }`. A non-2xx response or a network error rejects
+ * so the mic button can surface the failure.
  */
 export async function transcribeAudio(audio: Blob, options: TranscribeOptions): Promise<string> {
   const form = new FormData();
-  // A filename hints the server/codec; the extension is cosmetic (the server
-  // reads the blob's content type).
+  // The extension is cosmetic: the server reads the blob's content type.
   form.append("audio", audio, "recording.webm");
 
   const response = await fetch(