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

package/src/core/attachment.ts

@@ -0,0 +1,62 @@
+import type { Message } from "@ag-ui/core";
+import { metadataOrTopLevel } from "./utils.js";
+
+/**
+ * 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`: the file uploads out-of-band to the
+ * attachments endpoint, the server hands back this ref, and the agent reads the
+ * content server-side via the `read_attachment` tool.
+ */
+export interface AttachmentRef {
+  /** Opaque, owner-scoped handle the server resolves back to bytes. */
+  readonly id: string;
+  /** Original filename, for display on the chip. */
+  readonly name: string;
+  /** Declared content type (a hint — the server is authoritative). */
+  readonly mime: string;
+  /** Size in bytes. */
+  readonly size: number;
+  /** Optional direct fetch URL (the owner-checked download endpoint). */
+  readonly url?: string;
+}
+
+/**
+ * The attachment refs a user message carries.
+ *
+ * `AgUiClient.send` writes them into the message's `metadata`, under
+ * `attachments`. That is the one place they survive the trip: `@ag-ui/client`
+ * 1.0 strips every key its schemas do not declare from the outgoing input, so
+ * refs written at the top level of the message never reach the server, while
+ * `metadata` is declared open by key and sent as it is. The server reads them
+ * from there to tell the agent which files it can read, and the default store
+ * round-trips them, so a restored conversation re-renders its chips.
+ *
+ * A conversation stored by an earlier release has them at the top level, so
+ * that is read when the metadata has none. An older server reads only the top
+ * level, so against one the agent is never told about a file at all.
+ *
+ * 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 = metadataOrTopLevel(message, "attachments");
+  return Array.isArray(refs) ? refs.filter(isAttachmentRef) : [];
+}
+
+/** Whether an unknown value is a structurally valid {@link AttachmentRef}. */
+function isAttachmentRef(value: unknown): value is AttachmentRef {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const ref = value as Record<string, unknown>;
+  return (
+    typeof ref["id"] === "string" &&
+    typeof ref["name"] === "string" &&
+    typeof ref["mime"] === "string" &&
+    typeof ref["size"] === "number" &&
+    (ref["url"] === undefined || typeof ref["url"] === "string")
+  );
+}

package/src/core/chat_registry.ts

@@ -0,0 +1,53 @@
+/**
+ * The `<ag-ui-chat>` elements connected to this document, oldest first.
+ *
+ * The highlight ring is drawn in the host's page, outside every chat, so a
+ * token set on a chat never reaches it through the cascade. A free `flash()`
+ * still has to answer "which widget is this ring speaking for", and that is a
+ * question about the live elements rather than about any one of them.
+ *
+ * Module-level on purpose, and the second piece of shared mutable state the
+ * repository's `CLAUDE.md` records, beside the claimed storage namespaces. See
+ * the conditions it states, and how this one meets them, before adding a
+ * third.
+ */
+const CONNECTED_CHATS = new Set<HTMLElement>();
+
+/**
+ * One chat's place in the document's list of connected chats.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, which joins on connect and leaves on
+ * disconnect, so the list holds exactly the elements that are in a document
+ * now. Typed as `HTMLElement` rather than the element's class, because the DOM
+ * driver reads it and must not import the element.
+ */
+export class ChatRegistration {
+  readonly #chat: HTMLElement;
+
+  constructor(chat: HTMLElement) {
+    this.#chat = chat;
+  }
+
+  /**
+   * Join, as the most recently connected chat. An element moved in the DOM
+   * left on disconnect before it reconnected, so it rejoins at the end and no
+   * entry needs removing first.
+   */
+  join(): void {
+    CONNECTED_CHATS.add(this.#chat);
+  }
+
+  /** Leave. The previous chat, if one is still connected, becomes the latest. */
+  leave(): void {
+    CONNECTED_CHATS.delete(this.#chat);
+  }
+
+  /** The most recently connected chat still in the document, or `null`. */
+  static latest(): HTMLElement | null {
+    let latest: HTMLElement | null = null;
+    for (const chat of CONNECTED_CHATS) {
+      latest = chat;
+    }
+    return latest;
+  }
+}

package/src/core/client_seed.ts

@@ -0,0 +1,27 @@
+import type { Message } from "@ag-ui/core";
+
+/**
+ * What differs between the clients one conversation builds -- its own, and one
+ * per checkpoint continuation. Everything else about a client comes from the
+ * element's single construction, so an option added for one reaches the other.
+ */
+export interface ClientSeed {
+  /** Where the client's runs are sent. */
+  readonly endpoint: string;
+  /** The history the agent starts from, and sends with its first run. */
+  readonly initialMessages: readonly Message[];
+  /**
+   * The conversation this client's own history continues, which every save
+   * writes ahead of it.
+   *
+   * Empty for the conversation's own client, whose history is the whole
+   * conversation. A continuation's history is only the turn it adds and its
+   * answer -- the endpoint supplies the rest from its snapshot -- and a store
+   * keeps one list per thread, so a save of that history alone would replace
+   * the conversation with its last exchange, and not saving it lost the
+   * exchange on the next reload.
+   */
+  readonly follows: readonly Message[];
+  /** Handed the whole conversation each time the client saves it, as written. */
+  readonly onSaved?: (conversation: readonly Message[]) => void;
+}

package/src/core/conversation_store.ts

@@ -0,0 +1,478 @@
+import { randomUUID } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
+import { STORAGE_ROOT } from "../constants.js";
+import { prettifyToolName } from "../ui/progress/prettify_tool_name.js";
+
+/**
+ * A checkpoint recorded just before a navigating tool reloads the page.
+ *
+ * The reload destroys the in-memory run loop, so the element persists this
+ * marker first; on the next mount it supplies the tool's result and resumes.
+ */
+export interface NavigationCheckpoint {
+  /** The tool-call id whose result must be supplied after the reload. */
+  readonly toolCallId: string;
+}
+
+/**
+ * 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;
+  readonly title: string;
+  readonly updatedAt: number;
+  readonly preview: string;
+  /**
+   * Whether the thread holds an answer the user has not seen, as a server store
+   * knows it (from a last-read timestamp). Optional: a store that cannot tell
+   * leaves it out, and the element counts only what finishes in this page.
+   */
+  readonly unread?: boolean;
+}
+
+/**
+ * Client-side persistence seam for the conversation and a pending-navigation
+ * checkpoint, keyed by `thread_id`.
+ *
+ * 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 backs the chat-history drawer; deleting a thread reuses
+ * {@link clear}, and "new chat" is {@link newThread} — which leaves the
+ * conversation it moves off of intact, for the drawer to offer back.
+ */
+export interface ClientConversationStore {
+  /** The active conversation id, generated and persisted on first read. */
+  threadId(): string;
+  /**
+   * Start a fresh conversation, make it active, and return its id.
+   *
+   * Existing threads are left where they are: "new chat" adds one, and
+   * {@link clear} is the only method that takes one away.
+   *
+   * Optional: for a store without it, the caller mints the id itself and
+   * hands it to {@link setActiveThread}, which loses only the store's own
+   * record that the thread is new (see {@link isUnsent}).
+   */
+  newThread?(): string;
+  /** Load the persisted message history, or `null` when none exists. */
+  loadMessages(threadId: string): Promise<readonly Message[] | null>;
+  /** 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 (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;
+  /**
+   * Whether `threadId` was minted here and has never been saved — a thread in
+   * which nothing has been sent yet.
+   *
+   * Exists so a server-backed store can skip asking a server for history that
+   * cannot be there: the element mints an id on first mount and immediately tries
+   * to restore it, which answers `404` and logs one in the console on every first
+   * visit. Nothing is wrong, and it looks exactly like something being wrong.
+   *
+   * Optional, and deliberately narrow. A store that cannot tell omits it and the
+   * fetch happens as before, which is also the right answer for a store that
+   * holds nothing locally: "I have no messages for this id" is not the same claim
+   * as "this id is new", and only the store that minted the id can make the
+   * second one. A thread picked from the drawer was never minted here, so it is
+   * still fetched.
+   */
+  isUnsent?(threadId: string): boolean;
+  /**
+   * Record that the user has seen `threadId`'s answers.
+   *
+   * The element calls it when a thread with unseen answers is on screen with
+   * the panel expanded, and when an answer finishes there in view. A server
+   * store maps it to its read endpoint, and should report the thread with
+   * `unread: false` from {@link listThreads} afterwards. It is called inside the
+   * element's expand and thread-change paths, so it must not throw: a store that
+   * writes to a server sends the request without awaiting it and handles its own
+   * failure, the way a failed save is handled.
+   *
+   * Optional: a store without it still has its threads counted and cleared in
+   * the page; nothing is recorded beyond it.
+   */
+  markRead?(threadId: string): void;
+}
+
+const THREAD_SUFFIX = "thread";
+const THREADS_SUFFIX = "threads";
+const MESSAGES_SUFFIX = "messages:";
+const CHECKPOINT_SUFFIX = "checkpoint:";
+// Marks an id this store minted and nothing has been sent in yet. Dropped on
+// the first save, so it never outlives the one question it answers.
+const MINTED_SUFFIX = "minted:";
+
+const TITLE_LIMIT = 60;
+const PREVIEW_LIMIT = 100;
+const DEFAULT_TITLE = "New conversation";
+// A message that is one skill's name and nothing else, as a server-resolved skill sends.
+const SKILL_TOKEN = /^\/([A-Za-z0-9][\w.-]*)$/;
+
+/**
+ * Whether its owner has warned about a refused write yet. Each store and each
+ * storage scope holds one, so an origin-wide, persistent refusal (a full quota
+ * stays full) warns once per owner, not once per persisted turn or, on the
+ * resize path, per keystroke.
+ */
+export interface WriteFailureReport {
+  reported: boolean;
+}
+
+/**
+ * `sessionStorage.setItem` that survives a store which refuses to write.
+ *
+ * `setItem` throws on an exhausted quota (a long conversation, or one turn
+ * carrying a large tool result) and in privacy modes that deny storage
+ * altogether. Every write here is a *durability* concern — surviving a reload —
+ * and none of them is worth an exception, because of where they are called
+ * from: the element persists the transcript from inside the run loop, so an
+ * unguarded throw escapes as a run error and tells the user the agent failed
+ * when nothing but the browser's storage did. On the cancel path it escapes as
+ * an unhandled rejection instead.
+ *
+ * So a failed write loses the reload, never the conversation on screen, and
+ * says so once per `report`; without one, it says so on every refusal.
+ * Recovery is in the user's hands already: deleting the oversized thread from
+ * the history drawer is a `removeItem`, which frees the quota.
+ */
+export function writeStoredItem(
+  key: string,
+  value: string,
+  report: WriteFailureReport = { reported: false },
+): void {
+  try {
+    sessionStorage.setItem(key, value);
+  } catch {
+    if (report.reported) {
+      return;
+    }
+    report.reported = true;
+    console.warn(
+      "<ag-ui-chat>: the browser refused a sessionStorage write — the quota is " +
+        "full, or storage is disabled for this context. The conversation " +
+        "continues, but it will not survive a page reload. Deleting a long " +
+        "conversation from the history drawer frees the quota.",
+    );
+  }
+}
+
+/** The storage-key root for a namespace; `""` is the root of an element with nothing to key on. */
+function rootFor(namespace: string): string {
+  return namespace === "" ? STORAGE_ROOT : `${STORAGE_ROOT}@${namespace}`;
+}
+
+/** 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.
+ * 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, 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.
+ */
+export class SessionStorageStore implements ClientConversationStore {
+  readonly #root: string;
+  readonly #writeFailure: WriteFailureReport = { reported: false };
+
+  constructor(namespace = "") {
+    this.#root = rootFor(namespace);
+  }
+
+  /**
+   * Move every key a store owns out of `from`'s namespace and into `to`'s.
+   *
+   * `<ag-ui-chat>` adopts an element-scoped conversation into a
+   * principal-scoped one the first time a `user-key` arrives, which is a host
+   * naming the user who was already there rather than a handover.
+   *
+   * Only this store's own suffixes move — the element's `collapsed` / `size` /
+   * `theme` keys share the global root and are deliberately left where they
+   * are. A value already present at the destination wins: the destination is
+   * the durable record and the source is the stray this move exists to clear.
+   * A refused write warns once per call.
+   */
+  static adopt(from: string, to: string): void {
+    const fromRoot = `${rootFor(from)}:`;
+    const toRoot = `${rootFor(to)}:`;
+    const writeFailure: WriteFailureReport = { reported: false };
+    for (const [key, suffix] of ownedKeys(fromRoot)) {
+      const value = sessionStorage.getItem(key);
+      const destination = toRoot + suffix;
+      if (value !== null && sessionStorage.getItem(destination) === null) {
+        writeStoredItem(destination, value, writeFailure);
+      }
+      sessionStorage.removeItem(key);
+    }
+  }
+
+  /**
+   * Forget everything a store holds for `namespace`.
+   *
+   * The logout primitive: `<ag-ui-chat>` calls it when its `user-key` changes,
+   * and a host driving its own store can call it from its own sign-out path.
+   * Deliberately narrow — it removes only keys under this exact namespace whose
+   * suffix parses as one this store writes, so it can never reach another
+   * element's conversation or the host's own `sessionStorage` entries.
+   */
+  static purge(namespace: string): void {
+    for (const [key] of ownedKeys(`${rootFor(namespace)}:`)) {
+      sessionStorage.removeItem(key);
+    }
+  }
+
+  threadId(): string {
+    return sessionStorage.getItem(this.#key(THREAD_SUFFIX)) ?? this.newThread();
+  }
+
+  newThread(): string {
+    const id = randomUUID();
+    this.#write(this.#key(THREAD_SUFFIX), id);
+    this.#write(this.#key(MINTED_SUFFIX + id), "1");
+    return id;
+  }
+
+  isUnsent(threadId: string): boolean {
+    return (
+      sessionStorage.getItem(this.#key(MINTED_SUFFIX + threadId)) !== null &&
+      sessionStorage.getItem(this.#key(MESSAGES_SUFFIX + threadId)) === null
+    );
+  }
+
+  loadMessages(threadId: string): Promise<readonly Message[] | null> {
+    return Promise.resolve(this.#readJson<Message[]>(this.#key(MESSAGES_SUFFIX + threadId)));
+  }
+
+  saveMessages(threadId: string, messages: readonly Message[]): void {
+    this.#write(this.#key(MESSAGES_SUFFIX + threadId), JSON.stringify(messages));
+    sessionStorage.removeItem(this.#key(MINTED_SUFFIX + threadId));
+    this.#touchThread(threadId, messages);
+  }
+
+  loadCheckpoint(threadId: string): NavigationCheckpoint | null {
+    return this.#readJson<NavigationCheckpoint>(this.#key(CHECKPOINT_SUFFIX + threadId));
+  }
+
+  saveCheckpoint(threadId: string, checkpoint: NavigationCheckpoint | null): void {
+    const key = this.#key(CHECKPOINT_SUFFIX + threadId);
+    if (checkpoint === null) {
+      sessionStorage.removeItem(key);
+      return;
+    }
+    this.#write(key, JSON.stringify(checkpoint));
+  }
+
+  clear(threadId: string): void {
+    sessionStorage.removeItem(this.#key(MESSAGES_SUFFIX + threadId));
+    sessionStorage.removeItem(this.#key(CHECKPOINT_SUFFIX + threadId));
+    sessionStorage.removeItem(this.#key(MINTED_SUFFIX + threadId));
+    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(this.#key(THREAD_SUFFIX)) === threadId) {
+      sessionStorage.removeItem(this.#key(THREAD_SUFFIX));
+    }
+  }
+
+  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 {
+    this.#write(this.#key(THREAD_SUFFIX), 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[]>(this.#key(THREADS_SUFFIX)) ?? [];
+  }
+
+  #writeThreads(threads: readonly StoredThread[]): void {
+    const key = this.#key(THREADS_SUFFIX);
+    if (threads.length === 0) {
+      sessionStorage.removeItem(key);
+      return;
+    }
+    this.#write(key, JSON.stringify(threads));
+  }
+
+  #write(key: string, value: string): void {
+    writeStoredItem(key, value, this.#writeFailure);
+  }
+
+  /** This store's fully-qualified key for a suffix (namespaced when set). */
+  #key(suffix: string): string {
+    return `${this.#root}:${suffix}`;
+  }
+
+  /** Parse a stored JSON value, returning `null` when absent or corrupt. */
+  #readJson<T>(key: string): T | null {
+    const raw = sessionStorage.getItem(key);
+    if (raw === null) {
+      return null;
+    }
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Every `sessionStorage` key under `root` that this store wrote, as
+ * `[key, suffix]`.
+ *
+ * Collected into an array before the caller mutates anything: `sessionStorage`
+ * is enumerated by index, and removing an entry mid-loop shifts the ones after
+ * it out from under the cursor.
+ *
+ * The suffix test is what makes {@link SessionStorageStore.purge} safe to point
+ * at a namespace. It matters most for the global root, which the element's own
+ * `collapsed` / `size` / `theme` keys share — but it also means a namespace
+ * whose name happens to be a prefix of another cannot reach into it, since the
+ * remainder would have to parse as one of these suffixes.
+ */
+function ownedKeys(root: string): Array<readonly [string, string]> {
+  const found: Array<readonly [string, string]> = [];
+  for (let index = 0; index < sessionStorage.length; index += 1) {
+    const key = sessionStorage.key(index);
+    if (key === null || !key.startsWith(root)) {
+      continue;
+    }
+    const suffix = key.slice(root.length);
+    if (isOwnedSuffix(suffix)) {
+      found.push([key, suffix]);
+    }
+  }
+  return found;
+}
+
+/** Whether a key suffix belongs to the store (vs the element's own keys). */
+function isOwnedSuffix(suffix: string): boolean {
+  return (
+    suffix === THREAD_SUFFIX ||
+    suffix === THREADS_SUFFIX ||
+    suffix.startsWith(MESSAGES_SUFFIX) ||
+    suffix.startsWith(CHECKPOINT_SUFFIX) ||
+    suffix.startsWith(MINTED_SUFFIX)
+  );
+}
+
+/** The stored title: {@link threadTitleFrom}, or a placeholder for a thread with no user text. */
+function deriveTitle(messages: readonly Message[]): string {
+  const title = threadTitleFrom(messages);
+  return title === "" ? DEFAULT_TITLE : title;
+}
+
+/**
+ * A thread's title from its first user message, collapsed and truncated, or `""`
+ * when no user message has text.
+ *
+ * A first message that is exactly a skill's `/token` is named rather than
+ * quoted: `skillTitle(token)` when it knows the skill, else the token in words
+ * (`/summarize_draw` reads "Summarize draw").
+ */
+export function threadTitleFrom(
+  messages: readonly Message[],
+  skillTitle: (name: string) => string | undefined = () => undefined,
+): string {
+  for (const message of messages) {
+    if (message.role === "user") {
+      const text = cleanText(message.content);
+      if (text !== "") {
+        const token = SKILL_TOKEN.exec(text)?.[1];
+        const named = token === undefined ? text : (skillTitle(token) ?? prettifyToolName(token));
+        return truncate(named, TITLE_LIMIT);
+      }
+    }
+  }
+  return "";
+}
+
+/** 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()}…`;
+}