@artooi/ag-ui-web-component 0.29.0 → 0.30.0

package/src/ui/message_actions.ts

@@ -8,11 +8,16 @@ export interface MessageActionsOptions {
   /** Localized strings. */
   strings: UiStrings;
   /**
-   * The text Copy puts on the clipboard. A function rather than a string
-   * because a bubble's content is rewritten while it streams, and the bar is
-   * attached to the element rather than to a snapshot of it.
+   * The text Copy puts on the clipboard. Absent means no copy button.
+   *
+   * A function rather than a string because a bubble's content is rewritten
+   * while it streams, and the bar is attached to the element rather than to a
+   * snapshot of it. Optional for the same reason `onFeedback` is: what a button
+   * needs to do its job is also the statement that the button belongs here, so
+   * there is no second flag saying the same thing and no way for the two to
+   * disagree.
    */
-  text: () => string;
+  text?: () => string;
   /**
    * Report a rating for this message. Absent means no feedback buttons.
    *
@@ -35,13 +40,21 @@ export interface MessageActionsOptions {
  *
  * Idempotent -- a bubble already given a bar is skipped, so a re-render or a
  * second call cannot stack rows.
+ *
+ * Each button is present because the option it needs was passed: `text` for
+ * Copy, `onFeedback` for the rating pair. Passing neither builds an empty row,
+ * which is a caller's mistake rather than a state to guard against -- the
+ * element skips the call entirely when a host has turned both off.
  */
 export function attachMessageActions(bubble: HTMLElement, options: MessageActionsOptions): void {
   if (existingBar(bubble) !== null) {
     return;
   }
   const bar = messageActionBar(bubble, options.strings);
-  bar.appendChild(copyButton(options));
+  const text = options.text;
+  if (text !== undefined) {
+    bar.appendChild(copyButton(options.strings, text));
+  }
   if (options.onFeedback !== undefined) {
     bar.append(
       feedbackButton("up", options.strings.feedbackUp, options.onFeedback),
@@ -104,11 +117,10 @@ export function messageActionButton(
   return button;
 }
 
-function copyButton(options: MessageActionsOptions): HTMLButtonElement {
-  const { strings } = options;
+function copyButton(strings: UiStrings, text: () => string): HTMLButtonElement {
   const button = messageActionButton("copy", strings.copyMessage, "⎘");
   button.addEventListener("click", () => {
-    void navigator.clipboard.writeText(options.text()).then(
+    void navigator.clipboard.writeText(text()).then(
       () => flash(button, strings.copied, strings.copyMessage),
       // A denied clipboard permission is the common case, not an exception:
       // say so on the button rather than throwing into an unhandled rejection.

package/src/ui/styles.ts

@@ -1195,6 +1195,21 @@ export const STYLES = `
   color: var(--_fg);
 }
 
+/* A region a host formatter took over, marked by the card. Preformatted
+   whitespace is what makes the built-in block read as written, and it is the one
+   thing a host cannot want: a table inherits it as mangled cell spacing, and a
+   sentence as line breaks nobody typed.
+
+   Whitespace only. The card's own face, frame, padding and scroll cap stay,
+   because the card is one visual object -- the head row and the status pill are
+   monospaced too -- and a region that dropped the family would be the only part
+   of it wearing a different one. A host that wants that restyles the
+   tool-card-result part, which does not need the formatter at all. */
+.tool-call-args[data-formatted],
+.tool-call-result[data-formatted] {
+  white-space: normal;
+}
+
 /* Display modes are pure visibility over one DOM shape, selected from the host
    attribute rather than a value stamped on the card at build time, so flipping
    data-tool-display re-styles cards already on screen. See ToolCallCard.
@@ -1259,6 +1274,174 @@ export const STYLES = `
   display: flex;
 }
 
+/* A delegated sub-agent's progress, inside the card that delegated. Empty on
+   every card that delegated nothing, so it collapses rather than adding a gap
+   to each one -- the same shape the approval slot uses. */
+.tool-call-subagent:empty {
+  display: none;
+}
+
+.tool-call-subagent {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.subagent {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+
+/* The collapsed row is the status and the expander at once, which is what keeps
+   a ten-step child one row until somebody opens it. Full width and left-aligned,
+   because it is a line of the card rather than a button on it. */
+.subagent-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 2px 0;
+  border: none;
+  background: none;
+  font: inherit;
+  text-align: left;
+  color: var(--_muted);
+  cursor: pointer;
+}
+
+/* Nothing behind the row yet -- a delegation that failed before calling
+   anything. Drop the affordances rather than offer a control that expands onto
+   an empty region, which is the refusal the card's own toggle already makes. */
+.subagent-row:disabled {
+  cursor: default;
+}
+
+.subagent-row::after {
+  content: "▸";
+  flex: none;
+  margin-left: auto;
+  color: var(--_accent);
+}
+
+.subagent-row[aria-expanded="true"]::after {
+  content: "▾";
+}
+
+.subagent-row:disabled::after {
+  display: none;
+}
+
+/* Empty in the DOM; the glyph is drawn here from the panel's data-phase, so a
+   host re-themes it through the same tool-icon custom properties the card uses. */
+.subagent-icon {
+  flex: none;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 10px;
+  height: 10px;
+  font-size: 10px;
+  line-height: 1;
+}
+
+/* Anything that is not a terminal phase is the child still working. Selected by
+   what it is not, so a phase this client has not heard of still spins rather
+   than rendering as a blank. */
+.subagent[data-phase]:not([data-phase="finished"]):not([data-phase="failed"]) .subagent-icon {
+  border: 2px solid var(--_muted);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: ag-ui-tool-spin var(--_tool-spin-duration) linear infinite;
+}
+
+.subagent[data-phase="finished"] .subagent-icon::before {
+  content: var(--_tool-icon-done);
+  color: var(--_success);
+}
+
+.subagent[data-phase="failed"] .subagent-icon::before {
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .subagent .subagent-icon {
+    animation: none;
+  }
+}
+
+/* The server's own pre-rendered line. Shrinks and wraps rather than pushing the
+   chevron out of the card, which is what a fixed-width sibling in a flex row
+   does to a panel at sidebar width. */
+.subagent-status {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+/* The child's own calls. Indented and ruled, so the nesting is visible without
+   a second card frame around it. */
+.subagent-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-left: 4px;
+  padding-left: 10px;
+  border-left: 1px solid var(--_border);
+}
+
+.subagent-steps[hidden] {
+  display: none;
+}
+
+.subagent-step {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  color: var(--_muted);
+}
+
+.subagent-step-icon {
+  flex: none;
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 8px;
+  height: 8px;
+  font-size: 9px;
+  line-height: 1;
+}
+
+/* No outcome yet: the wire says null while the call is in flight, and the
+   absence of the attribute is how that arrives here. A hollow ring, not a
+   spinner -- several can be on screen at once and the row above already spins. */
+.subagent-step:not([data-ok]) .subagent-step-icon {
+  border: 1px solid var(--_muted);
+  border-radius: 50%;
+}
+
+.subagent-step[data-ok="true"] .subagent-step-icon::before {
+  content: var(--_tool-icon-done);
+  color: var(--_success);
+}
+
+.subagent-step[data-ok="false"] .subagent-step-icon::before {
+  content: var(--_tool-icon-error);
+  color: var(--_danger);
+}
+
+.subagent-step-name {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
 .tool-call-toggle {
   align-self: flex-start;
   border: none;

package/src/ui/subagent_panel.ts

@@ -0,0 +1,213 @@
+import type { SUBAGENT_PHASE } from "../constants.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
+
+/** One phase of a delegation's life, as the server spells it. */
+export type SubAgentPhase = (typeof SUBAGENT_PHASE)[keyof typeof SUBAGENT_PHASE];
+
+/**
+ * One tool call the child made, as the two tool phases report it.
+ *
+ * `ok` is a tri-state and stays one here rather than collapsing to a boolean:
+ * `null` is the call in flight, `true` a result the child accepted, `false` a
+ * result that came back to it. Flattening `null` into `false` would draw a
+ * running call as a failed one for as long as it runs.
+ */
+export interface SubAgentTool {
+  readonly toolCallId: string;
+  readonly name: string;
+  readonly ok: boolean | null;
+}
+
+/**
+ * One narrowed progress announcement about a delegation.
+ *
+ * Every field but `phase` and `delegationId` is nullable because the wire's
+ * `value` is `unknown` and a malformed announcement must not take the run down
+ * with it. `null` means "said nothing about this", never "said nothing was
+ * there" — the panel leaves what it already shows alone.
+ */
+export interface SubAgentUpdate {
+  /** The **parent's** `delegate_task` tool-call id, not the child's run id. */
+  readonly delegationId: string;
+  /** The child agent's name, for a host that wants to style or select by it. */
+  readonly agent: string | null;
+  readonly phase: SubAgentPhase;
+  /** The server's pre-rendered line. The collapsed row needs nothing else. */
+  readonly status: string | null;
+  /** Present on the two tool phases only. */
+  readonly tool: SubAgentTool | null;
+}
+
+/**
+ * The nested surface for one delegation: a collapsed status row that expands
+ * onto the child agent's own tool calls.
+ *
+ * ## Where it goes and why
+ *
+ * Into {@link ToolCallCard.subagentSlot} — the card the parent's own
+ * `delegate_task` call already drew. The wire keys progress on the *parent's*
+ * tool-call id, so the thing being narrated is already on screen; a floating
+ * element would have duplicated its identity and then had to explain the
+ * relationship. Attaching instead means the delegation reuses how tool cards
+ * already behave, and there is no second visual language to learn.
+ *
+ * ## The shape
+ *
+ * One row per delegation, live, carrying nothing but the server's own `status`
+ * line — which is what makes a ten-step child cost one row until somebody opens
+ * it. Two alternatives were rejected on the way here and both are worth naming:
+ * a bare status line is cheaper and gives up the detail entirely, and inline
+ * child cards in the transcript interleave parent and child with nothing marking
+ * whose is whose, in an order the persisted transcript will not reproduce.
+ *
+ * A child's steps are keyed by the child's own `toolCallId`, so the `tool_call`
+ * that opens one and the `tool_result` that settles it are the same row updated
+ * in place rather than two rows stacked.
+ *
+ * ## What it never does
+ *
+ * It never renders failure text. A `failed` phase carries none, on purpose; the
+ * detail arrives on the ordinary `TOOL_CALL_RESULT` and lands in the same card's
+ * result region, a few pixels below. Anything invented here would be this
+ * component guessing at words the server declined to send.
+ *
+ * Nothing here is persisted: the events ride the imperative carrier, so a thread
+ * restore rebuilds the tool card and not the delegation under it.
+ *
+ * Pure DOM, like the other widgets: the host appends {@link element}, and all
+ * chrome text comes from {@link UiStrings}. The status line is server text and
+ * is set with `textContent`, never parsed as markup.
+ */
+export class SubAgentPanel {
+  /** The panel's root; append this into the delegating card's slot. */
+  readonly element: HTMLDivElement;
+
+  /**
+   * The collapsed row, which is the expander as well as the status.
+   *
+   * Disabled while the child has called nothing, so a delegation that failed
+   * before it started offers no control that expands onto an empty region —
+   * the same refusal the card's own Details toggle already makes.
+   */
+  readonly #row: HTMLButtonElement;
+  readonly #status: HTMLSpanElement;
+  readonly #steps: HTMLDivElement;
+  /** The child's tool calls, keyed by the child's own call id. */
+  readonly #stepRows = new Map<string, HTMLDivElement>();
+
+  constructor(strings: UiStrings = DEFAULT_UI_STRINGS) {
+    this.element = document.createElement("div");
+    this.element.className = "subagent";
+    this.element.setAttribute("part", "subagent");
+
+    this.#row = document.createElement("button");
+    this.#row.type = "button";
+    this.#row.className = "subagent-row";
+    this.#row.setAttribute("part", "subagent-row");
+    this.#row.setAttribute("aria-expanded", "false");
+    this.#row.disabled = true;
+
+    // Left empty in the DOM, like the tool card's: the shadow CSS draws a
+    // spinner or a settled mark from the panel's data-phase, so a host themes
+    // the glyph without either side reaching into the other's stylesheet.
+    const icon = document.createElement("span");
+    icon.className = "subagent-icon";
+    icon.setAttribute("part", "subagent-icon");
+    icon.setAttribute("aria-hidden", "true");
+
+    this.#status = document.createElement("span");
+    this.#status.className = "subagent-status";
+    this.#status.setAttribute("part", "subagent-status");
+    // Seeded rather than left blank: an announcement whose status field is
+    // unusable must still leave a readable row, since the row is the control.
+    this.#status.textContent = strings.subAgentWorking;
+
+    this.#row.append(icon, this.#status);
+
+    this.#steps = document.createElement("div");
+    this.#steps.className = "subagent-steps";
+    this.#steps.setAttribute("part", "subagent-steps");
+    this.#steps.setAttribute("role", "list");
+    this.#steps.setAttribute("aria-label", strings.subAgentSteps);
+    this.#steps.hidden = true;
+
+    // The attribute is the state, as it is on the tool card: one place holds
+    // whether the region is open, and it is the one a screen reader reads.
+    this.#row.addEventListener("click", () => {
+      this.#setExpanded(this.#row.getAttribute("aria-expanded") !== "true");
+    });
+
+    this.element.append(this.#row, this.#steps);
+  }
+
+  /**
+   * Fold one announcement in.
+   *
+   * Every field is applied only when the update actually carried it, so a phase
+   * that says nothing about the agent or the status leaves both as they stand.
+   * That is what lets `finished` be two keys wide on the wire without blanking
+   * the row it closes.
+   */
+  report(update: SubAgentUpdate): void {
+    this.element.setAttribute("data-phase", update.phase);
+    if (update.agent !== null) {
+      this.element.setAttribute("data-agent", update.agent);
+    }
+    if (update.status !== null) {
+      this.#status.textContent = update.status;
+    }
+    if (update.tool !== null) {
+      this.#recordStep(update.tool);
+    }
+  }
+
+  /**
+   * Open or settle one of the child's calls, keyed by its own id.
+   *
+   * The absence of `data-ok` is what "still running" looks like, mirroring the
+   * wire's `null` rather than inventing a third value for it — so the attribute
+   * is removed on the way in and written on the way out.
+   */
+  #recordStep(tool: SubAgentTool): void {
+    const row = this.#stepRows.get(tool.toolCallId) ?? this.#createStep(tool);
+    if (tool.ok === null) {
+      row.removeAttribute("data-ok");
+      return;
+    }
+    row.setAttribute("data-ok", String(tool.ok));
+  }
+
+  #createStep(tool: SubAgentTool): HTMLDivElement {
+    const row = document.createElement("div");
+    row.className = "subagent-step";
+    row.setAttribute("part", "subagent-step");
+    row.setAttribute("role", "listitem");
+    row.setAttribute("data-tool-call-id", tool.toolCallId);
+
+    const icon = document.createElement("span");
+    icon.className = "subagent-step-icon";
+    icon.setAttribute("part", "subagent-step-icon");
+    icon.setAttribute("aria-hidden", "true");
+
+    const name = document.createElement("span");
+    name.className = "subagent-step-name";
+    name.setAttribute("part", "subagent-step-name");
+    // The child's raw tool name. Not prettified and not looked up in the tool
+    // catalog: a sub-agent's tools are its own and never reached the browser's
+    // schema, and the status line above quotes the same raw name, so relabelling
+    // here would make the two lines disagree about one call.
+    name.textContent = tool.name;
+
+    row.append(icon, name);
+    this.#steps.appendChild(row);
+    this.#stepRows.set(tool.toolCallId, row);
+    // There is something behind the row now, so it becomes a control.
+    this.#row.disabled = false;
+    return row;
+  }
+
+  #setExpanded(expanded: boolean): void {
+    this.#steps.hidden = !expanded;
+    this.#row.setAttribute("aria-expanded", String(expanded));
+  }
+}

package/src/ui/subagent_update.ts

@@ -0,0 +1,80 @@
+/**
+ * Narrow one `ag_ui.subagent` payload into a {@link SubAgentUpdate}.
+ *
+ * Kept out of the panel for the reason `chartSpecFrom` is kept out of the
+ * renderer: the panel's job is drawing, and a value that reaches it has already
+ * been vouched for.
+ *
+ * Defensive about the payload, not about the name. A `CUSTOM` event's `value` is
+ * `unknown` by the protocol, so a server can put anything there, and a malformed
+ * announcement must not take a run down with it — the same rule the invalidation
+ * channel applies to the same field. What is refused here is only what cannot be
+ * rendered at all: without a `delegationId` there is no card to attach to, and
+ * without a known `phase` there is no state to be in. Everything else degrades to
+ * `null`, which the panel reads as "said nothing about this".
+ */
+
+import { SUBAGENT_PHASE } from "../constants.js";
+import type { SubAgentPhase, SubAgentTool, SubAgentUpdate } from "./subagent_panel.js";
+
+const PHASES: readonly string[] = Object.values(SUBAGENT_PHASE);
+
+/** A record view of `value`, or `null` for anything that is not an object. */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  // `typeof null` is "object", and an array is one too — neither carries the
+  // keys below, and both arrive from a JSON decoder without any warning.
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+/** A non-empty string, or `null`. */
+function asText(value: unknown): string | null {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+/**
+ * The `tool` record the two tool phases carry.
+ *
+ * All-or-nothing: the contract states all three keys on every tool phase, so a
+ * partial record is a payload this client does not understand rather than a step
+ * to draw half of. A step row keyed by an empty id would also collide with the
+ * next one, silently merging two of the child's calls into one row.
+ */
+function asTool(value: unknown): SubAgentTool | null {
+  const record = asRecord(value);
+  if (record === null) {
+    return null;
+  }
+  const toolCallId = asText(record["toolCallId"]);
+  const name = asText(record["name"]);
+  const ok = record["ok"];
+  if (toolCallId === null || name === null) {
+    return null;
+  }
+  if (ok !== null && typeof ok !== "boolean") {
+    return null;
+  }
+  return { toolCallId, name, ok };
+}
+
+/** Narrow an `ag_ui.subagent` `CUSTOM` value, or `null` if it cannot be drawn. */
+export function subAgentUpdate(value: unknown): SubAgentUpdate | null {
+  const record = asRecord(value);
+  if (record === null) {
+    return null;
+  }
+  const delegationId = asText(record["delegationId"]);
+  const phase = record["phase"];
+  if (delegationId === null || typeof phase !== "string" || !PHASES.includes(phase)) {
+    return null;
+  }
+  return {
+    delegationId,
+    phase: phase as SubAgentPhase,
+    agent: asText(record["agent"]),
+    status: asText(record["status"]),
+    tool: asTool(record["tool"]),
+  };
+}