@artooi/ag-ui-web-component 0.4.0 → 0.6.0

package/src/core/conversation_store.ts

@@ -12,6 +12,22 @@ export interface NavigationCheckpoint {
   readonly toolCallId: string;
 }
 
+/**
+ * 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.
+ */
+export interface ThreadMeta {
+  readonly threadId: string;
+  readonly title: string;
+  readonly updatedAt: number;
+  readonly preview: string;
+}
+
 /**
  * Client-side persistence seam for the conversation and a pending-navigation
  * checkpoint, keyed by `thread_id`.
@@ -19,36 +35,61 @@ export interface NavigationCheckpoint {
  * 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` is 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.
+ * 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.
+ *
+ * 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.
  */
 export interface ClientConversationStore {
-  /** A stable conversation id, generated and persisted on first read. */
+  /** The active conversation id, generated and persisted on first read. */
   threadId(): string;
   /** Load the persisted message history, or `null` when none exists. */
   loadMessages(threadId: string): Promise<readonly Message[] | null>;
-  /** Persist the message history. */
+  /** Persist the message history (and refresh the thread's drawer metadata). */
   saveMessages(threadId: string, messages: readonly Message[]): void;
   /** Load the pending-navigation checkpoint, or `null` when none is set. */
   loadCheckpoint(threadId: string): NavigationCheckpoint | null;
   /** Set the pending-navigation checkpoint, or clear it when given `null`. */
   saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void;
-  /** Forget the conversation and checkpoint (e.g. a "new chat" action). */
+  /** Forget the conversation and checkpoint (a "delete thread" / "new chat"). */
   clear(threadId: string): void;
+  /** The user's threads as drawer metadata (no message bodies), newest first. */
+  listThreads(): Promise<readonly ThreadMeta[]>;
+  /** Make `threadId` the active conversation (the drawer selecting a row). */
+  setActiveThread(threadId: string): void;
+  /** Set a thread's display title (the drawer renaming a row). */
+  renameThread(threadId: string, title: string): void;
 }
 
 const THREAD_KEY = "ag-ui-chat:thread";
+const THREADS_KEY = "ag-ui-chat:threads";
 const MESSAGES_PREFIX = "ag-ui-chat:messages:";
 const CHECKPOINT_PREFIX = "ag-ui-chat:checkpoint:";
 
+const TITLE_LIMIT = 60;
+const PREVIEW_LIMIT = 100;
+const DEFAULT_TITLE = "New conversation";
+
+/** The drawer-index entry; `titleCustom` (private) freezes a renamed title. */
+interface StoredThread {
+  threadId: string;
+  title: string;
+  titleCustom: boolean;
+  preview: string;
+  updatedAt: number;
+}
+
 /**
  * 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.
- * One thread id per tab; the message history and checkpoint are namespaced by
- * it so two tabs hold independent conversations.
+ * 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.
  */
 export class SessionStorageStore implements ClientConversationStore {
   threadId(): string {
@@ -67,6 +108,7 @@ export class SessionStorageStore implements ClientConversationStore {
 
   saveMessages(threadId: string, messages: readonly Message[]): void {
     sessionStorage.setItem(MESSAGES_PREFIX + threadId, JSON.stringify(messages));
+    this.#touchThread(threadId, messages);
   }
 
   loadCheckpoint(threadId: string): NavigationCheckpoint | null {
@@ -85,7 +127,71 @@ export class SessionStorageStore implements ClientConversationStore {
   clear(threadId: string): void {
     sessionStorage.removeItem(MESSAGES_PREFIX + threadId);
     sessionStorage.removeItem(CHECKPOINT_PREFIX + threadId);
-    sessionStorage.removeItem(THREAD_KEY);
+    this.#writeThreads(this.#readThreads().filter((thread) => thread.threadId !== threadId));
+    // Only drop the active pointer when the active thread itself is cleared, so
+    // the next `threadId()` mints a fresh one. Deleting another thread from the
+    // drawer must not disturb the conversation on screen.
+    if (sessionStorage.getItem(THREAD_KEY) === threadId) {
+      sessionStorage.removeItem(THREAD_KEY);
+    }
+  }
+
+  listThreads(): Promise<readonly ThreadMeta[]> {
+    const metas = this.#readThreads()
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .map(({ threadId, title, updatedAt, preview }) => ({ threadId, title, updatedAt, preview }));
+    return Promise.resolve(metas);
+  }
+
+  setActiveThread(threadId: string): void {
+    sessionStorage.setItem(THREAD_KEY, threadId);
+  }
+
+  renameThread(threadId: string, title: string): void {
+    const threads = this.#readThreads();
+    const entry = threads.find((thread) => thread.threadId === threadId);
+    if (entry === undefined) {
+      return;
+    }
+    entry.title = title;
+    entry.titleCustom = true;
+    this.#writeThreads(threads);
+  }
+
+  /** Add or refresh a thread's drawer metadata from its latest messages. */
+  #touchThread(threadId: string, messages: readonly Message[]): void {
+    const threads = this.#readThreads();
+    const entry = threads.find((thread) => thread.threadId === threadId);
+    const preview = derivePreview(messages);
+    const updatedAt = Date.now();
+    if (entry === undefined) {
+      threads.push({
+        threadId,
+        title: deriveTitle(messages),
+        titleCustom: false,
+        preview,
+        updatedAt,
+      });
+    } else {
+      entry.preview = preview;
+      entry.updatedAt = updatedAt;
+      if (!entry.titleCustom) {
+        entry.title = deriveTitle(messages);
+      }
+    }
+    this.#writeThreads(threads);
+  }
+
+  #readThreads(): StoredThread[] {
+    return this.#readJson<StoredThread[]>(THREADS_KEY) ?? [];
+  }
+
+  #writeThreads(threads: readonly StoredThread[]): void {
+    if (threads.length === 0) {
+      sessionStorage.removeItem(THREADS_KEY);
+      return;
+    }
+    sessionStorage.setItem(THREADS_KEY, JSON.stringify(threads));
   }
 
   /** Parse a stored JSON value, returning `null` when absent or corrupt. */
@@ -101,3 +207,36 @@ export class SessionStorageStore implements ClientConversationStore {
     }
   }
 }
+
+/** The thread title: the first user message, collapsed + truncated. */
+function deriveTitle(messages: readonly Message[]): string {
+  for (const message of messages) {
+    if (message.role === "user") {
+      const text = cleanText(message.content);
+      if (text !== "") {
+        return truncate(text, TITLE_LIMIT);
+      }
+    }
+  }
+  return DEFAULT_TITLE;
+}
+
+/** A one-line preview: the latest message with text, collapsed + truncated. */
+function derivePreview(messages: readonly Message[]): string {
+  for (const message of [...messages].reverse()) {
+    const text = cleanText(message.content);
+    if (text !== "") {
+      return truncate(text, PREVIEW_LIMIT);
+    }
+  }
+  return "";
+}
+
+/** Whitespace-collapsed message text, or `""` for non-string content. */
+function cleanText(content: unknown): string {
+  return typeof content === "string" ? content.replace(/\s+/g, " ").trim() : "";
+}
+
+function truncate(text: string, limit: number): string {
+  return text.length <= limit ? text : `${text.slice(0, limit - 1).trimEnd()}…`;
+}

package/src/core/remote_conversation_store.ts

@@ -0,0 +1,147 @@
+import type { Message } from "@ag-ui/core";
+import {
+  type ClientConversationStore,
+  type NavigationCheckpoint,
+  SessionStorageStore,
+  type ThreadMeta,
+} from "./conversation_store.js";
+
+/** One row of the server thread index (django-ag-ui's `ThreadsView` wire shape). */
+interface ServerThreadRow {
+  readonly thread_id: string;
+  readonly title: string;
+  readonly updated_at: string | null;
+  readonly preview: string;
+}
+
+/** Live header source, read per request so rotated tokens / CSRF reach the server. */
+type HeadersProvider = () => Record<string, string>;
+
+/**
+ * A {@link ClientConversationStore} backed by a server thread-index endpoint —
+ * django-ag-ui's owner-scoped `ThreadsView`, the URL passed to `<ag-ui-chat>`
+ * as `data-threads-url`:
+ *
+ * - `GET  <url>`        → list the user's threads (metadata only);
+ * - `GET  <url><id>/`   → that thread's messages;
+ * - `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.
+ */
+export class RemoteConversationStore implements ClientConversationStore {
+  readonly #url: string;
+  readonly #headers: HeadersProvider;
+  readonly #local: ClientConversationStore;
+  readonly #dropped = new Set<string>();
+  readonly #renamed = new Map<string, string>();
+
+  constructor(
+    url: string,
+    headers: HeadersProvider = () => ({}),
+    local: ClientConversationStore = new SessionStorageStore(),
+  ) {
+    this.#url = url.endsWith("/") ? url : `${url}/`;
+    this.#headers = headers;
+    this.#local = local;
+  }
+
+  threadId(): string {
+    return this.#local.threadId();
+  }
+
+  setActiveThread(threadId: string): void {
+    this.#local.setActiveThread(threadId);
+  }
+
+  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);
+  }
+
+  loadCheckpoint(threadId: string): NavigationCheckpoint | null {
+    return this.#local.loadCheckpoint(threadId);
+  }
+
+  saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void {
+    this.#local.saveCheckpoint(threadId, checkpoint);
+  }
+
+  renameThread(threadId: string, title: string): void {
+    this.#local.renameThread(threadId, title);
+    this.#renamed.set(threadId, title);
+    void this.#mutate(threadId, "PATCH", { title });
+  }
+
+  clear(threadId: string): void {
+    this.#local.clear(threadId);
+    this.#dropped.add(threadId);
+    void this.#mutate(threadId, "DELETE");
+  }
+
+  async listThreads(): Promise<readonly ThreadMeta[]> {
+    const rows = await this.#fetchThreads();
+    if (rows === null) {
+      return this.#local.listThreads();
+    }
+    return rows.filter((row) => !this.#dropped.has(row.thread_id)).map((row) => this.#toMeta(row));
+  }
+
+  async loadMessages(threadId: string): Promise<readonly Message[] | null> {
+    const response = await this.#get(this.#url + encodeURIComponent(threadId) + "/");
+    if (response === null || !response.ok) {
+      return this.#local.loadMessages(threadId);
+    }
+    const body = (await response.json()) as { messages?: readonly Message[] };
+    return body.messages ?? null;
+  }
+
+  async #fetchThreads(): Promise<readonly ServerThreadRow[] | null> {
+    const response = await this.#get(this.#url);
+    if (response === null || !response.ok) {
+      return null;
+    }
+    const body = (await response.json()) as { threads?: readonly ServerThreadRow[] };
+    return body.threads ?? [];
+  }
+
+  #toMeta(row: ServerThreadRow): ThreadMeta {
+    return {
+      threadId: row.thread_id,
+      title: this.#renamed.get(row.thread_id) ?? row.title,
+      updatedAt: row.updated_at === null ? 0 : Date.parse(row.updated_at),
+      preview: row.preview,
+    };
+  }
+
+  /** 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() });
+    } catch {
+      return null;
+    }
+  }
+
+  /** Fire a best-effort write to the thread endpoint; failures are tolerated. */
+  async #mutate(
+    threadId: string,
+    method: "PATCH" | "DELETE",
+    body?: { title: string },
+  ): 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),
+      });
+    } catch {
+      // Best-effort; the optimistic overlay keeps the drawer consistent.
+    }
+  }
+}

package/src/core/upload_attachment.ts

@@ -0,0 +1,113 @@
+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} (multipart POST); a host swaps in its own — e.g. a
+ * `tus-js-client` or direct-to-S3 adapter — via `AgUiChat.uploadHandler`,
+ * **without** touching the tray, the chips, or the AG-UI wire (refs are
+ * transport-agnostic).
+ */
+export type UploadHandler = (
+  file: File,
+  onProgress: (fraction: number) => void,
+) => 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>;
+  /** 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;
+}
+
+/**
+ * Upload one file to the attachments endpoint and resolve to its durable
+ * {@link AttachmentRef}.
+ *
+ * Uses `XMLHttpRequest` (not `fetch`) for real upload-progress events: the file
+ * is sent as multipart under the `file` field, with the element's `headers` so
+ * CSRF / auth ride along exactly like the skills/tools fetches. A non-2xx
+ * response or a network/abort error rejects, so the tray can 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);
+    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})`;
+}

package/src/index.ts

@@ -28,10 +28,12 @@ export {
   type ExecuteTool,
   type ToolExecution,
 } from "./core/agui_client.js";
+export { type AttachmentRef, messageAttachments } from "./core/attachment.js";
 export {
   type ClientConversationStore,
   type NavigationCheckpoint,
   SessionStorageStore,
+  type ThreadMeta,
 } from "./core/conversation_store.js";
 export {
   type AgentFactory,
@@ -39,6 +41,12 @@ export {
   type HttpAgentOptions,
 } from "./core/create_http_agent.js";
 export { defineAgUiChat } from "./core/define_ag_ui_chat.js";
+export { RemoteConversationStore } from "./core/remote_conversation_store.js";
+export {
+  type UploadHandler,
+  type UploadOptions,
+  uploadAttachment,
+} from "./core/upload_attachment.js";
 export {
   type FlashOptions,
   focusWithFlash,

package/src/ui/attachment_chips.ts

@@ -0,0 +1,68 @@
+import type { AttachmentRef } from "../core/attachment.js";
+
+/**
+ * Render the read-only attachment chips shown on a sent user message bubble
+ * (and on restored history) — one chip per ref with a type icon, the filename,
+ * and a human size. Static by design: no progress, no remove (that lives in the
+ * composer tray); a restored bubble re-renders these with no animation.
+ */
+export function renderAttachmentChips(refs: readonly AttachmentRef[]): HTMLDivElement {
+  const list = document.createElement("div");
+  list.className = "attachment-chips";
+  for (const ref of refs) {
+    list.appendChild(renderChip(ref));
+  }
+  return list;
+}
+
+function renderChip(ref: AttachmentRef): HTMLDivElement {
+  const chip = document.createElement("div");
+  chip.className = "attachment-chip attachment-chip--ready";
+
+  const icon = document.createElement("span");
+  icon.className = "attachment-chip-icon";
+  icon.textContent = iconFor(ref.mime);
+  icon.setAttribute("aria-hidden", "true");
+
+  const name = document.createElement("span");
+  name.className = "attachment-chip-name";
+  name.textContent = ref.name;
+  name.title = ref.name;
+
+  const size = document.createElement("span");
+  size.className = "attachment-chip-size";
+  size.textContent = formatBytes(ref.size);
+
+  chip.append(icon, name, size);
+  return chip;
+}
+
+/** A coarse type icon for a chip — image, document, or generic file. */
+export function iconFor(mime: string): string {
+  if (mime.startsWith("image/")) {
+    return "🖼";
+  }
+  if (mime === "application/pdf") {
+    return "📕";
+  }
+  if (mime.startsWith("text/")) {
+    return "📄";
+  }
+  return "📎";
+}
+
+/** A compact human-readable byte size (e.g. `1.2 MB`). */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const rounded = value < 10 ? Math.round(value * 10) / 10 : Math.round(value);
+  return `${rounded} ${units[unit]}`;
+}