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

package/src/ui/progress/run_announcer.ts

@@ -0,0 +1,67 @@
+import { ANNOUNCE_CLEAR_MS } from "../../constants.js";
+
+/**
+ * The screen-reader-only status region, and the one short thing it says at a
+ * time about how a run is going.
+ *
+ * The transcript cannot do this job. It is rewritten on every animation frame
+ * while an answer streams, so as a live region it re-announced the whole
+ * answer tens of times per turn -- not merely unhelpful but actively hostile.
+ * The published fix for this exact bug (Microsoft's Bot Framework WebChat
+ * #3236) is architectural rather than a matter of tuning attributes: demote the
+ * visible transcript out of live-region duty and put one synthesised status per
+ * event into a separate invisible region. MDN and Scott O'Hara prescribe the
+ * same empty-region-then-inject shape.
+ *
+ * Roughly four calls land per turn -- responding, answered, a card is waiting,
+ * stopped or failed -- so the user is told what happened and reads the answer
+ * itself by navigating the log, at their own pace, rather than having it
+ * shouted at them a token at a time.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance. The element places {@link region} in its shadow root.
+ */
+export class RunAnnouncer {
+  /** The invisible `role="status"` region the statuses are written into. */
+  readonly region = document.createElement("div");
+  /** Pending clear of {@link region}; see {@link announce} for why it is cleared at all. */
+  #timer: ReturnType<typeof setTimeout> | null = null;
+
+  /** Stamp the region's live-region semantics, before the element places it. */
+  mount(): void {
+    this.region.className = "sr-only";
+    this.region.setAttribute("role", "status");
+    this.region.setAttribute("aria-live", "polite");
+    // Atomic: each announcement replaces the last and is read whole. Without
+    // it a reader may announce only the changed words between two statuses.
+    this.region.setAttribute("aria-atomic", "true");
+  }
+
+  /**
+   * Say one short thing to a screen reader, without touching the transcript.
+   *
+   * **The clear is load-bearing, twice.** A reader announces a live region when
+   * its content *changes*, so setting the same string twice running -- two turns
+   * in a row both starting -- is not a change and is silently not announced.
+   * Emptying first makes the next set a change again. It also stops a stale
+   * status being read out when a reader later lands on the region.
+   */
+  announce(message: string): void {
+    if (this.#timer !== null) {
+      clearTimeout(this.#timer);
+    }
+    this.region.textContent = message;
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      this.region.textContent = "";
+    }, ANNOUNCE_CLEAR_MS);
+  }
+
+  /** Cancel a pending clear, so no timer outlives the element's connection. */
+  dispose(): void {
+    if (this.#timer !== null) {
+      clearTimeout(this.#timer);
+      this.#timer = null;
+    }
+  }
+}

package/src/ui/progress/subagent_progress.ts

@@ -0,0 +1,201 @@
+import { SUBAGENT_PHASE } from "../../constants.js";
+import { fillUiString } from "../fill_ui_string.js";
+import type { UiStrings } from "../ui_strings.js";
+import { SubAgentPanel, type SubAgentPhase, type SubAgentUpdate } from "./subagent_panel.js";
+import { subAgentUpdate } from "./subagent_update.js";
+import type { ToolCallCard } from "./tool_call_card.js";
+
+/** What delegated progress needs from the element that owns it. */
+export interface SubAgentProgressHost {
+  /** The tool card drawn for a call id, which a delegation's panel hangs off. */
+  readonly card: (callId: string) => ToolCallCard | undefined;
+  /** The resolved string table. */
+  readonly strings: () => UiStrings;
+  /** Keep the transcript at its foot, if the reader is there. */
+  readonly follow: () => void;
+}
+
+/**
+ * A delegated sub-agent's progress, hung off the card that delegated: the live
+ * panels by delegation, and which delegation each child run belongs to.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class SubAgentProgress {
+  readonly #host: SubAgentProgressHost;
+  /**
+   * The live delegation panels, keyed by the **parent's** `delegate_task` call
+   * id — which is what the wire keys a sub-agent's progress on, so this map and
+   * the element's tool cards answer to the same key.
+   *
+   * Kept beside the cards rather than on them, so a card stays a card: the tool
+   * card holds the slot and this holds what went into it, the same division the
+   * approval prompt already uses.
+   */
+  readonly #subagentPanels = new Map<string, SubAgentPanel>();
+  /**
+   * Which delegation each live `subagentRunId` belongs to.
+   *
+   * The protocol's closing events -- `SUBAGENT_FINISHED` and `SUBAGENT_ERROR`
+   * -- carry the child's run id and nothing else, while everything drawn here
+   * is keyed on the parent's `delegate_task` call id. `SUBAGENT_STARTED` is the
+   * one event carrying both, so the pairing is recorded there and read back on
+   * the close. A close naming a run this never saw open is dropped, which is
+   * the same refusal a step for an undrawn card gets.
+   */
+  readonly #subagentRunDelegations = new Map<string, string>();
+
+  constructor(host: SubAgentProgressHost) {
+    this.#host = host;
+  }
+
+  /**
+   * Draw one step of a delegated sub-agent's progress, on the card that
+   * delegated.
+   *
+   * `delegationId` is the parent's own `delegate_task` tool-call id, so the
+   * attachment point is a card this element already drew on `TOOL_CALL_START`.
+   * That is the whole design: a run that hands work to a sub-agent used to read
+   * as a stall -- the card sat at "running…" for the child's entire duration --
+   * and the fix is to narrate *into* the thing that was already standing there,
+   * rather than to float a second element with the same identity.
+   *
+   * A progress event for a call this client never drew is dropped. It has no
+   * card to attach to, and inventing a floating one is precisely the alternative
+   * that was rejected: parent and child interleave in the transcript with
+   * nothing marking whose is whose, and the persisted transcript -- which never
+   * held the progress at all -- would not match what was on screen.
+   *
+   * Nothing here writes to the conversation store. `CUSTOM` never enters
+   * `agent.messages`, so a reload mid-run leaves the tool card and loses the
+   * nested detail, which is the intended behaviour rather than a gap.
+   */
+  report(value: unknown): void {
+    const update = subAgentUpdate(value);
+    if (update === null) {
+      return;
+    }
+    this.#apply(update);
+  }
+
+  /** Open a delegation, on `SUBAGENT_STARTED`. */
+  start(subagentRunId: string, agent: string, parentToolCallId: string | null): void {
+    // A delegation naming no parent call names no card, and a floating
+    // panel is exactly what attaching to the card was chosen over.
+    if (parentToolCallId === null) {
+      return;
+    }
+    this.#subagentRunDelegations.set(subagentRunId, parentToolCallId);
+    this.#apply({
+      delegationId: parentToolCallId,
+      agent: agent === "" ? null : agent,
+      phase: SUBAGENT_PHASE.STARTED,
+      status: fillUiString(this.#host.strings().subAgentDelegatedTo, { agent }),
+      tool: null,
+    });
+  }
+
+  /** Settle a delegation that completed, on `SUBAGENT_FINISHED`. */
+  finish(subagentRunId: string): void {
+    this.#close(subagentRunId, SUBAGENT_PHASE.FINISHED, null);
+  }
+
+  /** Settle a delegation that failed, on `SUBAGENT_ERROR`. */
+  fail(subagentRunId: string, message: string): void {
+    // The server's own words, which the contract keeps to the sub-agent's
+    // name. Passed through as the status line and set with textContent
+    // downstream, never parsed as markup.
+    //
+    // The message is required by the protocol and can still arrive empty,
+    // which would settle the row to a blank line -- a delegation that reads
+    // as having said nothing rather than as having failed. The fallback was
+    // written and documented in UiStrings and never wired up, so until now
+    // the only reader who knew it existed was the one reading the string
+    // table.
+    this.#close(
+      subagentRunId,
+      SUBAGENT_PHASE.FAILED,
+      message === "" ? this.#host.strings().subAgentFailed : message,
+    );
+  }
+
+  /**
+   * Forget every delegation. The panels go with the cards they hung off.
+   * Nothing restores them: the progress rode the imperative carrier and was
+   * never persisted, which is the correct half of that split -- a delegation
+   * that was live before this transcript was wiped is not live now.
+   */
+  clear(): void {
+    this.#subagentPanels.clear();
+    this.#subagentRunDelegations.clear();
+  }
+
+  /**
+   * Settle the delegation a closing lifecycle event names.
+   *
+   * `status` is the server's text on a failure and `null` on a success, where
+   * the wording is this element's own -- the protocol's finish event carries no
+   * message, which is the better shape for a localised UI and the reason
+   * {@link UiStrings.subAgentFinished} exists.
+   *
+   * The pairing is deliberately not deleted on close. A panel outlives the
+   * delegation it drew, the map is cleared with the transcript alongside the
+   * panels, and forgetting the id here would only make a duplicate close draw
+   * nothing instead of drawing the same settled row again.
+   */
+  #close(subagentRunId: string, phase: SubAgentPhase, status: string | null): void {
+    const delegationId = this.#subagentRunDelegations.get(subagentRunId);
+    if (delegationId === undefined) {
+      // A close naming a delegation this never saw open -- the same refusal a
+      // step for an undrawn card gets, and the same reason.
+      return;
+    }
+    const agent = this.#subagentPanels.get(delegationId)?.agent ?? null;
+    this.#apply({
+      delegationId,
+      agent,
+      phase,
+      status: status === null ? this.#finishedLine(agent) : status,
+      tool: null,
+    });
+  }
+
+  /** The row's line for a delegation that completed, named if its name is known. */
+  #finishedLine(agent: string | null): string {
+    const strings = this.#host.strings();
+    return agent === null
+      ? strings.subAgentWorking
+      : fillUiString(strings.subAgentFinished, { agent });
+  }
+
+  /**
+   * Fold one already-narrowed update into the delegation's panel.
+   *
+   * The join point of the two carriers, and the reason it is separate from
+   * {@link report}: a `CUSTOM` step arrives as `unknown` and has to be vouched
+   * for, while a lifecycle event arrives typed off the protocol and has nothing
+   * left to check. Both end up here, so the panel has one way in and the phases
+   * stay a single state machine regardless of which wire they came from.
+   */
+  #apply(update: SubAgentUpdate): void {
+    const card = this.#host.card(update.delegationId);
+    if (card === undefined) {
+      return;
+    }
+    let panel = this.#subagentPanels.get(update.delegationId);
+    if (panel === undefined) {
+      // Created on whichever phase arrives first rather than only on `started`.
+      // The contract says exactly one opens a delegation, and a client that
+      // insisted on it would answer a server that dropped one frame by showing
+      // nothing at all for the rest of the run.
+      panel = new SubAgentPanel(this.#host.strings());
+      this.#subagentPanels.set(update.delegationId, panel);
+      card.subagentSlot.appendChild(panel.element);
+    }
+    panel.report(update);
+    // The card grew, and the transcript is usually pinned to the foot while a
+    // run is in flight.
+    this.#host.follow();
+  }
+}

package/src/ui/progress/tool_call_card.ts

@@ -21,6 +21,7 @@ function statusLabels(strings: UiStrings): Record<ToolCallStatus, string> {
     [TOOL_CALL_STATUS.DONE]: strings.toolDone,
     [TOOL_CALL_STATUS.ERROR]: strings.toolError,
     [TOOL_CALL_STATUS.DECLINED]: strings.toolDeclined,
+    [TOOL_CALL_STATUS.INTERRUPTED]: strings.toolInterrupted,
   };
 }
 
@@ -30,6 +31,7 @@ function resultLabels(strings: UiStrings): Record<SettledStatus, string> {
     [TOOL_CALL_STATUS.DONE]: strings.resultLabel,
     [TOOL_CALL_STATUS.ERROR]: strings.errorLabel,
     [TOOL_CALL_STATUS.DECLINED]: strings.declinedLabel,
+    [TOOL_CALL_STATUS.INTERRUPTED]: strings.interruptedLabel,
   };
 }
 

package/src/ui/shell/adopt_styles.ts

@@ -0,0 +1,28 @@
+import { STYLES } from "../styles.js";
+
+/**
+ * Attach the stylesheet to `root` without an inline `<style>` element.
+ *
+ * A host with a strict `style-src` and no `'unsafe-inline'` drops an injected
+ * `<style>` silently: the component mounts, functions, and renders completely
+ * unstyled, with nothing in the console to point at. `adoptedStyleSheets`
+ * carries no inline-style origin, so it is unaffected by that policy.
+ *
+ * The sheet is constructed **per call**, which is once per mounted element,
+ * rather than shared at module scope. A shared sheet would additionally avoid
+ * re-parsing the stylesheet once per mounted element, which is what
+ * `adoptedStyleSheets` is usually reached for -- but a module-level singleton
+ * is exactly what this package forbids, and the CSP defect is fixed either way.
+ * Per instance is no worse than the `<style>` element it replaces, which also
+ * parsed once per mount.
+ *
+ * No fallback: constructible `CSSStyleSheet` is Chrome 73, Firefox 101 and
+ * Safari 16.4, all below this package's declared Safari 17 runtime target. A
+ * guard here would be code no supported browser can reach, and the only way
+ * to keep it would be to exempt it from the coverage gate.
+ */
+export function adoptStyles(root: ShadowRoot): void {
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(STYLES);
+  root.adoptedStyleSheets = [sheet];
+}

package/src/ui/shell/glyph_slot.ts

@@ -0,0 +1,12 @@
+/**
+ * A `<slot>` a host can project its own mark into, falling back to one of the
+ * built-in glyphs. The markup is an author-written constant, never user or
+ * server data, so it is assigned directly rather than sanitised.
+ */
+export function glyphSlot(slotName: string, className: string, markup: string): HTMLSlotElement {
+  const slot = document.createElement("slot");
+  slot.name = slotName;
+  slot.className = className;
+  slot.innerHTML = markup;
+  return slot;
+}

package/src/ui/shell/header_button.ts

@@ -0,0 +1,21 @@
+/**
+ * Build a header control button: a named slot a host can project markup into,
+ * with the built-in glyph as the slot's fallback.
+ *
+ * The slot is what lets a host replace the mark with its own `<img>` or
+ * `<svg>` rather than only restyle it through the `part`; the same
+ * slot-with-fallback idiom the header icon uses.
+ */
+export function headerButton(modifier: string, label: string, glyph: string): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `header-btn header-btn--${modifier}`;
+  button.setAttribute("part", `header-button ${modifier}-button`);
+  button.title = label;
+  button.setAttribute("aria-label", label);
+  const slot = document.createElement("slot");
+  slot.name = `icon-${modifier}`;
+  slot.append(document.createTextNode(glyph));
+  button.append(slot);
+  return button;
+}

package/src/ui/shell/icon_element.ts

@@ -0,0 +1,33 @@
+/**
+ * An icon holder wrapping a `<slot>` so a host can project custom markup;
+ * with an `<img>` as the slot's fallback when an icon URL is configured, or
+ * the given glyph markup when it is not.
+ *
+ * `iconUrl` is the caller's to read rather than defaulted here, because the
+ * three marks answer it differently: the header's is `data-icon-url`, the
+ * launcher's falls back to it from an attribute of its own, and the theme
+ * toggle never takes an image at all.
+ */
+export function iconElement(
+  slotName: string,
+  part: string,
+  fallbackGlyph: string | null,
+  iconUrl: string | null,
+): HTMLSpanElement {
+  const holder = document.createElement("span");
+  holder.className = "icon-holder";
+  holder.setAttribute("part", part);
+  const slot = document.createElement("slot");
+  slot.name = slotName;
+  if (iconUrl !== null) {
+    const img = document.createElement("img");
+    img.className = "icon-img";
+    img.src = iconUrl;
+    img.alt = "";
+    slot.append(img);
+  } else if (fallbackGlyph !== null) {
+    slot.innerHTML = fallbackGlyph;
+  }
+  holder.append(slot);
+  return holder;
+}

package/src/ui/shell/is_unread_badge_enabled.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether the launcher's unread badge is shown.
+ *
+ * The unread badge, unlike every other affordance here, is on by default:
+ * a collapsed widget is the one state where an answer can arrive with nothing
+ * on screen to say so. `data-unread-badge="false"` turns it off for a host
+ * that drives its own chrome from the `ag-ui-unread` event.
+ */
+export function isUnreadBadgeEnabled(element: Element): boolean {
+  return element.getAttribute("data-unread-badge") !== "false";
+}

package/src/ui/shell/read_launcher_icon_url.ts

@@ -0,0 +1,9 @@
+/**
+ * The launcher's own image URL. `data-launcher-icon-url` lets the collapsed
+ * button carry a different mark from the header's — a product logo reads at
+ * 22px in a header bar but rarely at 26px in a circle — and falls back to the
+ * header icon so a single `data-icon-url` still feeds both.
+ */
+export function readLauncherIconUrl(element: Element): string | null {
+  return element.getAttribute("data-launcher-icon-url") ?? element.getAttribute("data-icon-url");
+}