@artooi/agents-web-components 0.0.0-stage → 0.1.1

package/src/core/storage_scope.ts

@@ -0,0 +1,291 @@
+import { randomUUID } from "@ag-ui/client";
+import {
+  type ClientConversationStore,
+  SessionStorageStore,
+  type WriteFailureReport,
+  writeStoredItem,
+} from "./conversation_store.js";
+
+/**
+ * Storage namespaces already spoken for in this document.
+ *
+ * Per document rather than per origin, and released on disconnect, because the
+ * question it answers is "is another element on this page using these keys right
+ * now" — not "has anything ever used them". A registry that never released would
+ * turn every remount, and every framework re-render that moves the node, into a
+ * false collision that costs the element its own conversation.
+ *
+ * Module-level on purpose, and the one piece of shared mutable state the
+ * repository's `CLAUDE.md` exempts from its rule against it: the question is
+ * about the *other* live elements, which no instance field can answer. See the
+ * three conditions recorded there before adding anything beside it.
+ */
+const CLAIMED_NAMESPACES = new Set<string>();
+
+/** What the storage scope needs from the element that owns it. */
+export interface StorageScopeHost {
+  /** The element's `id`, the namespace it prefers. */
+  readonly id: () => string;
+  /** The element's `endpoint`, the namespace it falls back to. */
+  readonly endpoint: () => string;
+}
+
+/**
+ * Which storage keys are this element's: the namespace it claims in the
+ * document, the key a layout preference is stored under, and the built-in
+ * conversation store scoped to it.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`. The one thing it shares is the record
+ * of claimed namespaces above, which is what keeps two elements apart.
+ */
+export class StorageScope {
+  readonly #host: StorageScopeHost;
+  // Per-instance suffix for the origin-scoped storage keys (collapsed / theme /
+  // size), so two instances on one origin don't clobber each other. Empty ⇒ the
+  // root keys, for an element with nothing to key on. Resolved on connect; the
+  // conversation adds `user-key` on top of it, see conversationNamespace.
+  #storageNs = "";
+  // The entry this element put in CLAIMED_NAMESPACES, to take back out on
+  // disconnect. `null` when it claimed nothing (no id, no endpoint, or it lost
+  // the claim to an element that mounted first).
+  #claimedNs: string | null = null;
+  // The fallback namespace minted when the preferred one was already claimed,
+  // with the preferred value it was minted for — so the element keeps it across
+  // remounts, but re-resolves if the host answers the warning with an `id`.
+  #generatedNs = "";
+  #generatedFor = "";
+  // The `sessionStorage`-backed store this scope handed out, which the element
+  // may therefore re-scope on a principal change -- while it is still the store
+  // in use, which rescopeStore asks, since a host can assign its own at any
+  // time. `null` until connecting has met the built-in store at all. A store of
+  // the host's own kind is never held here: the element does not know its
+  // keying and must not guess at it.
+  #builtinStore: SessionStorageStore | null = null;
+  readonly #writeFailure: WriteFailureReport = { reported: false };
+
+  constructor(host: StorageScopeHost) {
+    this.#host = host;
+  }
+
+  /**
+   * Resolve the per-instance storage namespace, before any key is read or
+   * written, so this instance doesn't share collapsed/theme/thread state with
+   * another on the same origin.
+   */
+  claim(): void {
+    this.#storageNs = this.#claimNamespace();
+  }
+
+  /**
+   * Give the namespace back. A disconnect is not necessarily a farewell — a
+   * DOM move and a framework re-render both look like one — and an element
+   * that could not reclaim its own namespace on the way back in would lose its
+   * conversation to a false collision.
+   */
+  release(): void {
+    if (this.#claimedNs !== null) {
+      CLAIMED_NAMESPACES.delete(this.#claimedNs);
+      this.#claimedNs = null;
+    }
+  }
+
+  /**
+   * The conversation store's namespace: this element's, scoped to the principal
+   * `key` names.
+   *
+   * Only the conversation is principal-scoped. The panel's own collapsed / size
+   * / theme preferences stay on the element's own namespace, because they are
+   * this element's UI state rather than anyone's data — they carry no word of
+   * what was said — and because they are read once while connecting, so
+   * re-scoping them under a live element would rearrange the panel around a
+   * user who had only just signed in.
+   */
+  conversationNamespace(key: string): string {
+    return key === "" ? this.#storageNs : `${this.#storageNs}#${key}`;
+  }
+
+  /**
+   * Namespace the built-in default store, and hand back the store to use. A
+   * host-injected store is used verbatim; the built-in one is remembered
+   * either way, because it is the element's own store and a later `user-key`
+   * change may move it to another namespace.
+   */
+  scopeStore(store: ClientConversationStore, key: string): ClientConversationStore {
+    if (!(store instanceof SessionStorageStore)) {
+      return store;
+    }
+    const namespace = this.conversationNamespace(key);
+    this.#builtinStore = namespace === "" ? store : new SessionStorageStore(namespace);
+    return this.#builtinStore;
+  }
+
+  /**
+   * Rebuild the built-in store under `namespace`, or `null` when `current` --
+   * the store the element is using now, unwrapped from any remote it wrapped
+   * it in -- is not the one this scope handed out.
+   *
+   * Asked of the store in use rather than of what connecting remembered,
+   * because the two part company the moment a host assigns a store of its own
+   * to a connected element. Remembering was enough to tell a host's store from
+   * the built-in one at connect; after it, the built-in one was still
+   * remembered, so a key change replaced the host's store with a fresh
+   * `sessionStorage` one -- and a host that had chosen to keep message bodies
+   * off the client found every one of them cached in the tab again. A store
+   * the element did not make holds its data somewhere the element cannot see,
+   * and has to scope itself.
+   */
+  rescopeStore(current: ClientConversationStore, namespace: string): SessionStorageStore | null {
+    if (current !== this.#builtinStore) {
+      return null;
+    }
+    this.#builtinStore = new SessionStorageStore(namespace);
+    return this.#builtinStore;
+  }
+
+  /** This instance's namespaced form of an origin-scoped storage key. */
+  key(base: string): string {
+    return this.#storageNs === "" ? base : `${base}:${this.#storageNs}`;
+  }
+
+  /** Read a namespaced origin-scoped value. */
+  readScopedItem(base: string): string | null {
+    return sessionStorage.getItem(this.key(base));
+  }
+
+  /**
+   * Read a layout preference: where the widget sits, how big it is, which
+   * theme it wears.
+   *
+   * These live in `localStorage` rather than beside the transcript, because a
+   * layout preference is not a conversation. The transcript is deliberately
+   * per-tab -- two tabs are two conversations, and closing the tab ends it --
+   * and everything else inherited that scoping without earning it. A user who
+   * dragged the panel clear of their own UI did it again in the next tab, and
+   * again after every restart.
+   *
+   * Whether the widget is *currently open* stays per-tab with the transcript.
+   * It is a statement about this tab rather than a preference: carrying it
+   * across would pop the panel open on every new tab because it was opened
+   * once, somewhere else.
+   *
+   * Falls back to the per-tab copy, which is all a browser that denies
+   * `localStorage` has.
+   */
+  readPreference(base: string): string | null {
+    try {
+      const stored = localStorage.getItem(this.key(base));
+      if (stored !== null) {
+        return stored;
+      }
+    } catch {
+      // Fall through to the per-tab copy below.
+    }
+    return this.readScopedItem(base);
+  }
+
+  /**
+   * Persist a layout preference as durably as this browser allows: to
+   * `localStorage` so it outlives the tab, and to the per-tab store as well.
+   *
+   * The second write is not redundancy for its own sake. A privacy mode can
+   * deny `localStorage` while allowing `sessionStorage`, and losing the
+   * durable copy should degrade to the per-tab behaviour this replaced rather
+   * than to no persistence at all. The read above prefers the durable copy, so
+   * a tab that has both cannot be shadowed by its own stale one.
+   *
+   * Neither write is worth an exception. A refused per-tab write warns once
+   * per scope rather than once per write, because the size path writes on
+   * every step.
+   */
+  writePreference(base: string, value: string): void {
+    const key = this.key(base);
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+      // Quota, or a store that denies writes.
+    }
+    writeStoredItem(key, value, this.#writeFailure);
+  }
+
+  /** Write a per-tab value under this scope's key, sharing its one refused-write warning. */
+  writeSession(base: string, value: string): void {
+    writeStoredItem(this.key(base), value, this.#writeFailure);
+  }
+
+  /**
+   * Drop a layout preference from both stores.
+   *
+   * The mirror of {@link writePreference}, and it has to clear both for the
+   * same reason that writes both: leaving either copy behind means the value
+   * comes back on the next read.
+   */
+  clearPreference(base: string): void {
+    const key = this.key(base);
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      // A store that denies access; the per-tab copy below still goes.
+    }
+    try {
+      sessionStorage.removeItem(key);
+    } catch {
+      // Nothing left to do: the value was never persisted in the first place.
+    }
+  }
+
+  /**
+   * Claim this element's storage namespace: its `id`, else its `endpoint`.
+   *
+   * The endpoint fallback exists so a lone widget restores its conversation
+   * across reloads with nothing asked of the page author. It stops working the
+   * moment there are two of them — a docked support panel and an inline page
+   * assistant against one agent mount, neither carrying an `id`, which nothing
+   * requires — because both resolve to the same string and then share a thread
+   * pointer, a drawer index and every message key. Whichever mounts second
+   * adopts the first's active thread and rehydrates its transcript into its own
+   * panel: one conversation's content inside another, on the same page.
+   *
+   * So the namespace is claimed by the first element to mount under it, and a
+   * second is given one of its own plus a warning naming the fix. The first
+   * element keeps the endpoint namespace, which is what leaves the ordinary
+   * single-element case exactly as it was.
+   *
+   * The generated namespace is random rather than derived from mount order.
+   * That costs the second element its history across reloads — the warning says
+   * so, and an `id` fixes it — which is the honest trade against an order-based
+   * name that would silently hand a stored conversation to whichever element
+   * happened to mount second on the next load.
+   */
+  #claimNamespace(): string {
+    const id = this.#host.id();
+    const preferred = id !== "" ? id : this.#host.endpoint();
+    // Nothing to key on, so the root keys: an element with neither an id nor
+    // an endpoint cannot send anything, so what it would claim is an empty
+    // conversation.
+    if (preferred === "") {
+      return "";
+    }
+    // Already lost this claim once. Keep the fallback rather than drifting back
+    // onto a namespace the other element may since have released, which would
+    // swap this panel's conversation for that one's.
+    if (this.#generatedFor === preferred) {
+      return this.#generatedNs;
+    }
+    if (!CLAIMED_NAMESPACES.has(preferred)) {
+      CLAIMED_NAMESPACES.add(preferred);
+      this.#claimedNs = preferred;
+      return preferred;
+    }
+    this.#generatedFor = preferred;
+    this.#generatedNs = `${preferred}~${randomUUID()}`;
+    console.warn(
+      `<ag-ui-chat>: another element on this page already stores its ` +
+        `conversation under "${preferred}", so this one has been given a ` +
+        "throwaway namespace of its own — the two would otherwise share a " +
+        "thread pointer, a history drawer and every message. Give each " +
+        "<ag-ui-chat> its own id to keep them apart and let this one restore " +
+        "its conversation across reloads.",
+    );
+    return this.#generatedNs;
+  }
+}

package/src/core/tool_outcome.ts

@@ -0,0 +1,39 @@
+import { TOOL_CALL_STATUS, TOOL_OUTCOME } from "../constants.js";
+import type { SettledStatus } from "../ui/progress/tool_call_card.js";
+
+/**
+ * How a tool call ended, in the wire's own words. See {@link TOOL_OUTCOME}.
+ *
+ * Absent is the fourth case and the common one: a server that has never heard
+ * of the field says nothing, and nothing means success.
+ */
+export type ToolOutcome = (typeof TOOL_OUTCOME)[keyof typeof TOOL_OUTCOME];
+
+/**
+ * The card status a wire outcome settles into.
+ *
+ * Takes `unknown` rather than {@link ToolOutcome} on purpose: both callers read
+ * this off a boundary the type system does not police -- a key in an AG-UI
+ * event's `metadata`, which the protocol declares open and does not validate,
+ * and a JSON blob out of the conversation store -- so the narrowing belongs
+ * here, once, instead of at each of them.
+ *
+ * **Everything unrecognised maps to `DONE`.** Not because unknown values are
+ * expected to be successes, but because the alternative is worse in the
+ * direction that matters: a card claiming a call failed when it did not is a
+ * lie the user acts on, while a card claiming success has at least the result
+ * text under it for them to read. A future release may add words, and forward
+ * compatibility is the point of the open field.
+ */
+export function toolStatusFromOutcome(outcome: unknown): SettledStatus {
+  if (outcome === TOOL_OUTCOME.FAILED) {
+    return TOOL_CALL_STATUS.ERROR;
+  }
+  if (outcome === TOOL_OUTCOME.DENIED) {
+    return TOOL_CALL_STATUS.DECLINED;
+  }
+  if (outcome === TOOL_OUTCOME.INTERRUPTED) {
+    return TOOL_CALL_STATUS.INTERRUPTED;
+  }
+  return TOOL_CALL_STATUS.DONE;
+}

package/src/core/transcribe_audio.ts

@@ -0,0 +1,76 @@
+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}; 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>;
+
+/** Options for {@link transcribeAudio}. */
+export interface TranscribeOptions {
+  /** The transcription endpoint (`data-transcribe-url`). */
+  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;
+}
+
+/**
+ * POST a recorded clip to the transcription endpoint and resolve to its text.
+ *
+ * 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();
+  // The extension is cosmetic: the server reads the blob's content type.
+  form.append("audio", audio, "recording.webm");
+
+  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));
+  }
+  const body: unknown = await response.json();
+  if (
+    typeof body === "object" &&
+    body !== null &&
+    typeof (body as { text?: unknown }).text === "string"
+  ) {
+    return (body as { text: string }).text;
+  }
+  throw new Error("transcription returned an unreadable response");
+}
+
+/** A human-readable message from a non-2xx transcription response. */
+async function errorMessage(response: Response): Promise<string> {
+  try {
+    const body = (await response.json()) as { error?: unknown };
+    if (typeof body.error === "string") {
+      return body.error;
+    }
+  } catch {
+    // Non-JSON error body — fall through to the status code.
+  }
+  return `transcription failed (${response.status})`;
+}

package/src/core/upload_attachment.ts

@@ -0,0 +1,130 @@
+import type { AttachmentRef } from "./attachment.js";
+
+/**
+ * The composer's upload contract: take a `File`, report `0..1` progress, and
+ * resolve to a durable {@link AttachmentRef}. The built-in handler is
+ * {@link uploadAttachment}; a host swaps in its own (a `tus-js-client` or
+ * direct-to-S3 adapter) via `AgUiChat.uploadHandler` without touching the tray,
+ * the chips, or the AG-UI wire, refs being transport-agnostic.
+ *
+ * The optional `signal` fires when the tray removes a chip or the element is
+ * torn down; a handler that honours it should abort its own transport, so a
+ * cancelled upload doesn't orphan a server-side file.
+ */
+export type UploadHandler = (
+  file: File,
+  onProgress: (fraction: number) => void,
+  signal?: AbortSignal,
+) => Promise<AttachmentRef>;
+
+/** Options for {@link uploadAttachment}. */
+export interface UploadOptions {
+  /** The attachments endpoint (`data-attachments-url`). */
+  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 other endpoints, but carried by `XMLHttpRequest`'s two-state
+   * `withCredentials`: `"include"` sets it and every other value leaves it off,
+   * matching `"same-origin"`. `"omit"` therefore cannot be honoured for a
+   * same-origin upload, XHR always sending 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. */
+  readonly signal?: AbortSignal | undefined;
+}
+
+/**
+ * Upload one file to the attachments endpoint and resolve to its durable
+ * {@link AttachmentRef}.
+ *
+ * Uses `XMLHttpRequest` rather than `fetch` for real upload-progress events.
+ * The file goes as multipart under the `file` field with the element's
+ * `headers`, so CSRF / auth ride along; a non-2xx response or a network/abort
+ * error rejects, letting the tray show an error chip.
+ */
+export function uploadAttachment(file: File, options: UploadOptions): Promise<AttachmentRef> {
+  return new Promise<AttachmentRef>((resolve, reject) => {
+    const form = new FormData();
+    form.append("file", file);
+
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", options.url);
+    // Cross-origin cookies ride only when asked for, as at the fetch sites.
+    // Without this an upload to another subdomain goes 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);
+    }
+
+    const onProgress = options.onProgress;
+    if (onProgress !== undefined) {
+      xhr.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable) {
+          onProgress(event.total === 0 ? 0 : event.loaded / event.total);
+        }
+      });
+    }
+
+    xhr.addEventListener("load", () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        try {
+          resolve(parseRef(JSON.parse(xhr.responseText)));
+        } catch {
+          reject(new Error("upload returned an unreadable response"));
+        }
+      } else {
+        reject(new Error(errorMessage(xhr)));
+      }
+    });
+    xhr.addEventListener("error", () => reject(new Error("upload failed")));
+    xhr.addEventListener("abort", () => reject(new Error("upload cancelled")));
+
+    const signal = options.signal;
+    if (signal !== undefined) {
+      signal.addEventListener("abort", () => xhr.abort());
+    }
+
+    xhr.send(form);
+  });
+}
+
+/** Validate + narrow the server's `201` body into an {@link AttachmentRef}. */
+function parseRef(body: unknown): AttachmentRef {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("not an object");
+  }
+  const o = body as Record<string, unknown>;
+  const id = o["id"];
+  const name = o["name"];
+  const mime = o["mime"];
+  const size = o["size"];
+  const url = o["url"];
+  if (
+    typeof id !== "string" ||
+    typeof name !== "string" ||
+    typeof mime !== "string" ||
+    typeof size !== "number"
+  ) {
+    throw new Error("missing fields");
+  }
+  return typeof url === "string" ? { id, name, mime, size, url } : { id, name, mime, size };
+}
+
+/** A human-readable message from a non-2xx upload response. */
+function errorMessage(xhr: XMLHttpRequest): string {
+  try {
+    const body = JSON.parse(xhr.responseText) as { error?: unknown };
+    if (typeof body.error === "string") {
+      return body.error;
+    }
+  } catch {
+    // Non-JSON error body — fall through to the status text.
+  }
+  return `upload failed (${xhr.status})`;
+}