@artooi/ag-ui-web-component 0.3.1 → 0.5.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/index.ts

@@ -32,6 +32,7 @@ export {
   type ClientConversationStore,
   type NavigationCheckpoint,
   SessionStorageStore,
+  type ThreadMeta,
 } from "./core/conversation_store.js";
 export {
   type AgentFactory,
@@ -39,6 +40,7 @@ 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 FlashOptions,
   focusWithFlash,
@@ -79,7 +81,11 @@ export {
   type RouteWithParams,
 } from "./tools/route_map.js";
 export { createStateHookTools, type StateHook } from "./tools/state_hook.js";
-export { type ConfirmationRequest, requestConfirmation } from "./ui/confirmation_card.js";
+export {
+  type ConfirmationOptions,
+  type ConfirmationRequest,
+  requestConfirmation,
+} from "./ui/confirmation_card.js";
 export { prettifyToolName } from "./ui/prettify_tool_name.js";
 export { type RenderMarkdownOptions, renderMarkdown } from "./ui/render_markdown.js";
 export {

package/src/ui/confirmation_card.ts

@@ -18,6 +18,16 @@ function actionButton(modifier: string, label: string): HTMLButtonElement {
   return button;
 }
 
+/** Options for {@link requestConfirmation}. */
+export interface ConfirmationOptions {
+  /**
+   * Aborting this signal resolves the card as declined (buttons disabled,
+   * `data-resolved="declined"`) — the hook a Stop control uses to dismiss a
+   * pending confirmation when the user cancels the whole run.
+   */
+  signal?: AbortSignal;
+}
+
 /**
  * Append an inline confirmation card to ``host`` (the chat message list) and
  * resolve when the user decides.
@@ -31,6 +41,7 @@ function actionButton(modifier: string, label: string): HTMLButtonElement {
 export function requestConfirmation(
   host: Node & ParentNode,
   request: ConfirmationRequest,
+  options: ConfirmationOptions = {},
 ): Promise<boolean> {
   return new Promise<boolean>((resolve) => {
     const card = document.createElement("div");
@@ -53,7 +64,12 @@ export function requestConfirmation(
     const cancel = actionButton("cancel", "Cancel");
     const confirm = actionButton("confirm", "Confirm");
 
+    let settled = false;
     const close = (accepted: boolean): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
       cancel.disabled = true;
       confirm.disabled = true;
       card.setAttribute("data-resolved", accepted ? "confirmed" : "declined");
@@ -62,10 +78,16 @@ export function requestConfirmation(
 
     cancel.addEventListener("click", () => close(false));
     confirm.addEventListener("click", () => close(true));
+    options.signal?.addEventListener("abort", () => close(false), { once: true });
 
     actions.append(cancel, confirm);
     card.append(body, args, actions);
     host.appendChild(card);
+    if (options.signal?.aborted === true) {
+      // The run was cancelled before the card could ask; record the decline.
+      close(false);
+      return;
+    }
     confirm.focus();
   });
 }

package/src/ui/relative_time.ts

@@ -0,0 +1,28 @@
+/**
+ * A compact relative timestamp for a thread row — e.g. `"just now"`, `"5m ago"`,
+ * `"3h ago"`, `"2d ago"`, `"4w ago"`.
+ *
+ * `now` is injectable so callers (and tests) can pin the reference point; it
+ * defaults to the current time. A timestamp in the future (clock skew) reads as
+ * `"just now"`. Kept locale-independent on purpose so the rendered label is
+ * stable across environments.
+ */
+export function relativeTime(timestamp: number, now: number = Date.now()): string {
+  const seconds = Math.round((now - timestamp) / 1000);
+  if (seconds < 60) {
+    return "just now";
+  }
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m ago`;
+  }
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) {
+    return `${hours}h ago`;
+  }
+  const days = Math.round(hours / 24);
+  if (days < 7) {
+    return `${days}d ago`;
+  }
+  return `${Math.round(days / 7)}w ago`;
+}

package/src/ui/styles.ts

@@ -501,6 +501,19 @@ export const STYLES = `
   cursor: default;
 }
 
+/* The composer button doubles as the Stop control while a run is in flight. */
+.send[data-state="running"] {
+  background: var(--ag-ui-muted);
+}
+
+/* Muted "⏹ Stopped" line after a cancelled run — a note, not an error bubble. */
+.stopped-note {
+  align-self: flex-start;
+  color: var(--ag-ui-muted);
+  font-size: 12px;
+  padding: 2px 4px;
+}
+
 /* Inline confirmation card — lives in the transcript, no focus-stealing overlay. */
 .confirm {
   align-self: stretch;
@@ -631,4 +644,188 @@ export const STYLES = `
   font-size: 0.85em;
   color: var(--ag-ui-danger);
 }
+
+/* Chat-history drawer — a slide-over within the chat panel. */
+.drawer {
+  position: absolute;
+  inset: 0;
+  z-index: 5;
+  display: flex;
+}
+
+.drawer[hidden] {
+  display: none;
+}
+
+.drawer-backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(20, 20, 50, 0.32);
+}
+
+.drawer-panel {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: min(300px, 85%);
+  height: 100%;
+  background: var(--ag-ui-bg);
+  border-right: 1px solid var(--ag-ui-border);
+  box-shadow: var(--ag-ui-shadow);
+  overflow: hidden;
+}
+
+.drawer-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ag-ui-space);
+  padding: var(--ag-ui-pad);
+  border-bottom: 1px solid var(--ag-ui-border);
+}
+
+.drawer-title {
+  font-weight: 600;
+}
+
+.drawer-new {
+  border: 1px solid var(--ag-ui-border);
+  border-radius: var(--ag-ui-radius);
+  background: var(--ag-ui-bg);
+  color: var(--ag-ui-accent);
+  padding: 4px 10px;
+  font: inherit;
+  font-size: 0.85em;
+  cursor: pointer;
+}
+
+.drawer-list {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.drawer-empty {
+  padding: var(--ag-ui-pad);
+  font-size: 0.9em;
+  color: var(--ag-ui-muted);
+}
+
+.drawer-row {
+  display: flex;
+  align-items: stretch;
+  border-bottom: 1px solid var(--ag-ui-border);
+}
+
+.drawer-row--active {
+  background: var(--ag-ui-assistant-bg);
+}
+
+.drawer-row-select {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 8px 12px;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.drawer-row-title {
+  font-weight: 600;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.drawer-row-time {
+  font-size: 0.72em;
+  color: var(--ag-ui-muted);
+}
+
+.drawer-row-preview {
+  font-size: 0.8em;
+  color: var(--ag-ui-muted);
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.drawer-row-actions {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 0 6px;
+}
+
+.drawer-row-rename,
+.drawer-row-delete {
+  border: none;
+  background: none;
+  color: var(--ag-ui-muted);
+  font-size: 0.9em;
+  padding: 4px;
+  cursor: pointer;
+}
+
+.drawer-rename-input {
+  flex: 1;
+  min-width: 0;
+  margin: 6px 10px;
+  padding: 4px 8px;
+  border: 1px solid var(--ag-ui-accent);
+  border-radius: 6px;
+  background: var(--ag-ui-input-bg);
+  color: var(--ag-ui-fg);
+  font: inherit;
+}
+
+.drawer-confirm {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  font-size: 0.85em;
+}
+
+.drawer-confirm-label {
+  color: var(--ag-ui-danger);
+}
+
+.drawer-confirm-yes {
+  border: none;
+  border-radius: 6px;
+  background: var(--ag-ui-danger);
+  color: #ffffff;
+  padding: 3px 10px;
+  font: inherit;
+  cursor: pointer;
+}
+
+.drawer-confirm-no {
+  border: 1px solid var(--ag-ui-border);
+  border-radius: 6px;
+  background: none;
+  color: inherit;
+  padding: 3px 10px;
+  font: inherit;
+  cursor: pointer;
+}
+
+/* Embedded placement: an inline, flush side panel rather than a dimmed,
+   floating slide-over. */
+:host([placement="embedded"]) .drawer-backdrop {
+  background: none;
+}
+
+:host([placement="embedded"]) .drawer-panel {
+  width: 100%;
+  border-right: none;
+  box-shadow: none;
+}
 `;