@artooi/ag-ui-web-component 0.38.0 → 0.40.0

package/src/core/storage_scope.ts

@@ -0,0 +1,279 @@
+import { randomUUID } from "@ag-ui/client";
+import {
+  type ClientConversationStore,
+  SessionStorageStore,
+  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
+  // pre-namespacing global keys (back-compat). 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, which the element may therefore re-scope
+  // on a principal change. `null` when the host injected a store of its own
+  // kind, whose keying the element does not know and must not guess at.
+  #builtinStore: SessionStorageStore | null = null;
+
+  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` for a store of the
+   * host's own kind, which holds its data somewhere the element cannot see and
+   * has to scope itself.
+   */
+  rescopeStore(namespace: string): SessionStorageStore | null {
+    if (this.#builtinStore === null) {
+      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, falling back once to the legacy
+   * pre-namespacing global key (left in place) so an existing collapsed/theme
+   * preference survives the upgrade.
+   */
+  readScopedItem(base: string): string | null {
+    const scoped = sessionStorage.getItem(this.key(base));
+    if (scoped !== null || this.#storageNs === "") {
+      return scoped;
+    }
+    return sessionStorage.getItem(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 session value it used to be written to, so an existing
+   * position survives the upgrade rather than resetting once.
+   */
+  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. Losing where the panel sat is not
+   * worth a warning either -- unlike the transcript, which says so once,
+   * because losing that loses the conversation on the next reload.
+   */
+  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);
+  }
+
+  /**
+   * 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. The pre-namespacing global keys, as before: an element
+    // with neither an id nor an endpoint cannot send anything, so what it would
+    // be claiming 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

@@ -21,9 +21,8 @@ export type ToolOutcome = (typeof TOOL_OUTCOME)[keyof typeof TOOL_OUTCOME];
  * 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. `interrupted` is the concrete case today --
- * pydantic-ai emits it, this vocabulary does not carry it, and a future release
- * may add more. Forward compatibility is the point of the open field.
+ * 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) {
@@ -32,5 +31,8 @@ export function toolStatusFromOutcome(outcome: unknown): SettledStatus {
   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/utils.ts

@@ -1,6 +1,7 @@
 // Non-exported-from-index helpers shared by the core modules.
 
 import { randomUUID } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
 import type { ClientConversationStore } from "./conversation_store.js";
 
 /**
@@ -96,3 +97,111 @@ export function warnOnCrossOriginCredentials(
       "silence this notice. Reported once per origin.",
   );
 }
+
+/**
+ * The tokens of a comma-separated attribute value, trimmed, with empty ones
+ * dropped -- so `"scroll, drag,"` is `["scroll", "drag"]`.
+ *
+ * Shared by every attribute that names a set of opt-ins, so each one reads a
+ * stray space or a trailing comma the same way.
+ */
+export function commaTokens(value: string): string[] {
+  return value
+    .split(",")
+    .map((token) => token.trim())
+    .filter((token) => token !== "");
+}
+
+/**
+ * `messages` with a result for every tool call that has none, each placed at the
+ * end of the round that made the call.
+ *
+ * **Why every call.** Several model providers reject a request carrying a tool
+ * call with no result, and a conversation that sends one cannot continue. A run
+ * leaves calls unanswered in more ways than any one path can list: Stop while
+ * the stream is still arriving, a round ending on `RUN_ERROR`, a name no tool
+ * here owns, a server that never streamed a result, a page reloaded mid-run.
+ * Answering whatever is unanswered, rather than each of those where it happens,
+ * is what keeps a path nobody listed from sending one.
+ *
+ * **Where each result goes.** At the end of its round: the assistant turns
+ * carrying calls, then the results that follow them. That is the shape the run
+ * loop writes for a round it executed, and a provider reads a result only in the
+ * turn straight after the calls; appended at the end of history, it would sit
+ * behind a user turn or a reply the conversation has moved on to. A call with a
+ * result after a *later* turn is left alone, since it is answered.
+ *
+ * `answer` builds the one message for a call id, so the caller decides what is
+ * true to say and where the label for a reload goes. Calls in `except` are about
+ * to be answered by something else -- a resumed approval, or a navigation
+ * result -- and must not be answered twice.
+ *
+ * Returns `messages` itself when nothing is owed.
+ *
+ * Every condition deciding a round's end is one branch arc, which a coverage
+ * gate reports as covered with any part of it deleted. Each is held by a test in
+ * `ag_ui_chat_unanswered_tool_calls.test.ts`: a result continuing the round by
+ * "answers it after the round's own results"; a turn without calls closing it by
+ * "sends a not-finished result for a call that arrived before it"; a turn with
+ * calls after a result closing it by "answers each round's open call before the
+ * next round starts"; the answered check by "sends the decline Stop gave the
+ * open approval"; and the exclusion by "leaves the call it resumes for the
+ * server to answer".
+ */
+export function answerUnansweredCalls(
+  messages: readonly Message[],
+  answer: (toolCallId: string) => Message,
+  except: ReadonlySet<string> = new Set(),
+): readonly Message[] {
+  const answered = new Set<string>(except);
+  for (const message of messages) {
+    if (message.role === "tool") {
+      answered.add(message.toolCallId);
+    }
+  }
+  const result: Message[] = [];
+  let owed: string[] = [];
+  let afterResult = false;
+  for (const message of messages) {
+    const calls = message.role === "assistant" ? toolCallIds(message.toolCalls) : [];
+    const continuesRound = message.role === "tool" || (calls.length > 0 && !afterResult);
+    if (!continuesRound) {
+      result.push(...owed.map(answer));
+      owed = [];
+    }
+    result.push(message);
+    afterResult = message.role === "tool";
+    for (const id of calls) {
+      if (!answered.has(id)) {
+        // Marked as it is owed, so a store holding the same id twice gets one
+        // answer rather than two, which a provider rejects just the same.
+        answered.add(id);
+        owed.push(id);
+      }
+    }
+  }
+  if (result.length + owed.length === messages.length) {
+    return messages;
+  }
+  result.push(...owed.map(answer));
+  return result;
+}
+
+/**
+ * The ids of the tool calls an assistant turn carries, skipping anything without
+ * one.
+ *
+ * The field is read off the wire or out of a store, and neither is held to its
+ * declared type: a server dumping Python models sends `null` for no calls, and a
+ * stored conversation may be hand-edited or written by an older version. A throw
+ * here would cost the whole request, so a shapeless entry is passed over.
+ */
+function toolCallIds(value: unknown): string[] {
+  // `Object()` boxes a `null` or a primitive entry into something with no `id`,
+  // so one read covers every shape without a branch per shape.
+  return Array.isArray(value)
+    ? value
+        .map((call: unknown) => (Object(call) as { id?: unknown }).id)
+        .filter((id): id is string => typeof id === "string")
+    : [];
+}

package/src/skills/skill_catalog.ts

@@ -0,0 +1,166 @@
+import type { SkillsMenu } from "../ui/composer/skills_menu.js";
+import { fillUiString } from "../ui/fill_ui_string.js";
+import type { UiStrings } from "../ui/ui_strings.js";
+import { fillTemplate } from "./fill_template.js";
+import { parseSkills } from "./parse_skills.js";
+import type { Skill } from "./skill.js";
+
+/** What the skill catalog needs from the element that owns it. */
+export interface SkillCatalogHost {
+  /** The custom element, whose `data-skills-url` names the backend catalog. */
+  readonly element: HTMLElement;
+  /** The chips row and the slash palette the merged catalog is shown in. */
+  readonly menu: SkillsMenu;
+  /** The composer a picked skill's prompt is written into. */
+  readonly input: HTMLTextAreaElement;
+  /** The hint above the composer, saying what a skill still needs. */
+  readonly hint: HTMLElement;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** The host's `skillContext`, read at the moment of the pick. */
+  readonly context: () => Record<string, unknown>;
+  /** Read an opt-in flag attribute. */
+  readonly flag: (name: string) => boolean;
+  /** Parse a JSON-valued attribute, warning when it will not parse. */
+  readonly readJsonAttribute: (name: string) => unknown;
+  /** The fetch options every request the element makes carries. */
+  readonly fetchInit: (url: string) => RequestInit | undefined;
+  /** The element's public `sendMessage`. */
+  readonly send: (content: string) => void;
+  /** Send whatever the composer holds, as the Send button does. */
+  readonly submit: () => void;
+  /** Resize the composer to what it now holds. */
+  readonly autoGrow: () => void;
+}
+
+/**
+ * The element's skills: the three catalogs a skill can come from, merged into
+ * the chips and the slash palette, and what picking one does to the composer.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class SkillCatalog {
+  readonly #host: SkillCatalogHost;
+  // Skill catalog by source; merged backend → embed → client (later wins).
+  #backendSkills: readonly Skill[] = [];
+  #embedSkills: readonly Skill[] = [];
+  #clientSkills: readonly Skill[] = [];
+
+  constructor(host: SkillCatalogHost) {
+    this.#host = host;
+  }
+
+  /** The replacement behind `AgUiChat.setSkills`, whose doc is the contract. */
+  setClientSkills(skills: readonly Skill[]): void {
+    this.#clientSkills = skills;
+    this.#recompute();
+  }
+
+  /**
+   * Wire the skill surfaces: opt-in flags and the embedded catalog. The backend
+   * catalog is fetched from the element's startup, a microtask later, so it
+   * carries the host's transport configuration.
+   */
+  init(): void {
+    this.#host.menu.enableChips(this.#host.flag("data-prompt-chips"));
+    this.#host.menu.enableSlash(this.#host.flag("data-slash-commands"));
+    this.#embedSkills = this.#readEmbedded();
+    this.#recompute();
+  }
+
+  /** Fetch the backend skills catalog from `data-skills-url`, if set. */
+  async fetch(): Promise<void> {
+    const url = this.#host.element.getAttribute("data-skills-url");
+    if (url === null) {
+      return;
+    }
+    try {
+      const response = await fetch(url, this.#host.fetchInit(url));
+      this.#backendSkills = parseSkills(await response.json());
+      this.#recompute();
+    } catch {
+      // Network/parse failure: skills just stay as the embedded/client set.
+    }
+  }
+
+  /**
+   * Act on a picked skill.
+   *
+   * A skill with no `prompt` is server-resolved: picking it sends the bare
+   * `/name` token for the agent to expand, so the wording never reaches the
+   * browser. Prefer that shape — a skill often states a project's internal
+   * workflow most plainly, and a catalog endpoint is a plain GET.
+   *
+   * A skill carrying a `prompt` has the client fill its `{placeholder}`s from
+   * the page instead, which is right for placeholders only the page can supply.
+   *
+   * Either way a pick sends; `sendImmediately: false` opts into pre-filling the
+   * composer instead.
+   */
+  apply(skill: Skill): void {
+    const { input, hint } = this.#host;
+    if (skill.prompt === undefined) {
+      hint.hidden = true;
+      this.#host.send(`/${skill.name}`);
+      return;
+    }
+    const { text, missing } = fillTemplate(skill.prompt, this.#host.context());
+    if (missing.length > 0) {
+      // Hand the user something to work with rather than only a refusal. The
+      // partially-filled template goes into the composer with its unresolved
+      // `{placeholder}`s intact and the first one selected, so the next
+      // keystroke replaces it. Blocking with a hint alone left whatever the
+      // user had typed to open the palette — a lone "/" — sitting there, which
+      // says nothing about what the skill wanted or how to give it.
+      hint.textContent = fillUiString(this.#host.strings().skillNeeds, {
+        title: skill.title,
+        fields: missing.join(", "),
+      });
+      hint.hidden = false;
+      input.value = text;
+      this.#host.autoGrow();
+      input.focus();
+      this.#selectFirstPlaceholder(text);
+      return;
+    }
+    hint.hidden = true;
+    input.value = text;
+    this.#host.autoGrow();
+    if (skill.sendImmediately === false) {
+      input.focus();
+      return;
+    }
+    this.#host.submit();
+  }
+
+  /** Parse the inline `data-skills` JSON catalog (empty when absent/malformed). */
+  #readEmbedded(): readonly Skill[] {
+    // `parseSkills` drops anything that is not a well-formed skill, `null`
+    // included, so the absent and unparseable cases need no branch here.
+    return parseSkills(this.#host.readJsonAttribute("data-skills"));
+  }
+
+  /** Merge the three sources (backend → embed → client; later wins by name). */
+  #recompute(): void {
+    const merged = new Map<string, Skill>();
+    for (const skill of [...this.#backendSkills, ...this.#embedSkills, ...this.#clientSkills]) {
+      merged.set(skill.name, skill);
+    }
+    this.#host.menu.setSkills([...merged.values()]);
+  }
+
+  /**
+   * Put the caret on the first unresolved placeholder, selected.
+   *
+   * Typing then replaces it, which is the shortest path from "this skill needs
+   * a topic" to a sendable prompt.
+   */
+  #selectFirstPlaceholder(text: string): void {
+    // The first surviving brace *is* the first unresolved placeholder — a
+    // resolved one was substituted away — so this needs no search through the
+    // missing keys and no not-found branch to defend.
+    const start = text.indexOf("{");
+    this.#host.input.setSelectionRange(start, text.indexOf("}", start) + 1);
+  }
+}

package/src/skills/skill_name_from.ts

@@ -0,0 +1,19 @@
+import { LOAD_CAPABILITY_TOOL } from "../constants.js";
+import type { AgUiToolCall } from "../core/agui_client.js";
+
+/**
+ * The skill name a `load_capability` call activated, or `null` when the call is
+ * something else.
+ *
+ * Every deferred capability loads through this one tool, so the id is a skill
+ * name only when the project wired agent skills; another project's capability
+ * id surfaces here too. Acceptable for a muted notice, and better than a
+ * parallel signal — the id is exactly what the model selected.
+ */
+export function skillNameFrom(call: AgUiToolCall): string | null {
+  if (call.name !== LOAD_CAPABILITY_TOOL) {
+    return null;
+  }
+  const id = (call.args as { id?: unknown } | null | undefined)?.id;
+  return typeof id === "string" && id !== "" ? id : null;
+}