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

package/src/ui/placement/small_viewport_styles.ts

@@ -0,0 +1,70 @@
+// The one shape every placement takes on a phone-sized viewport.
+export const SMALL_VIEWPORT_STYLES: string = `
+/* Small viewports: one shape, reached from whichever placement the host chose.
+
+   A phone is not an eighth placement, it is an override that collapses the
+   others onto one of them. The host picked a placement for the desktop it was
+   designing; a 380x560 panel with a 24px margin is not a smaller version of
+   that decision, it is most of the screen with a frame drawn round it.
+
+   The breakpoint is a literal because a custom property cannot be read in a
+   media query -- which is exactly why there is an opt-out. Everything the block
+   sets is a token a host can re-state, but the *trigger* is unreachable, so a
+   host whose layout wants a different threshold, or none, sets
+   data-small-viewport="off" and keeps its desktop shape at every width. 600px is above every common phone in portrait and below every
+   tablet in landscape, and it is a width rather than a pointer test on purpose:
+   a touch laptop is coarse-pointered and wide, a narrow desktop window is
+   fine-pointered and small, and conflating the two gets both wrong. What the
+   pointer decides is which controls make sense, further down.
+
+   The size the user dragged is deliberately not read here. The desktop
+   placements read it before the host token, and this block restates the sizes
+   without it, so a persisted or freshly dragged size cannot change the shape
+   of a phone, and a window narrowed after a drag goes full-bleed.
+
+   Two placements are left alone. "page" is already this shape. "embedded" sits
+   in a box the host sized and placed, and taking that over would break the app
+   shell it was embedded into -- the host is the only party that knows whether
+   its column should become the whole screen. */
+@media (max-width: 600px) {
+  :host([placement="floating"]:not([data-small-viewport="off"])),
+  :host([placement="bottom-left"]:not([data-small-viewport="off"])),
+  :host([placement="sidebar"]:not([data-small-viewport="off"])),
+  :host([placement="side"]:not([data-small-viewport="off"])),
+  :host(:not([placement]):not([data-small-viewport="off"])),
+  :host([placement=""]:not([data-small-viewport="off"])) {
+    --_inset: var(
+      --ag-ui-inset,
+      calc(var(--_viewport-inset-top) + var(--_keyboard-inset-top)) var(--_viewport-inset-right)
+        calc(var(--_viewport-inset-bottom) + var(--_keyboard-inset))
+        var(--_viewport-inset-left)
+    );
+    --_width: var(--ag-ui-width, var(--_viewport-width));
+    --_height: var(--ag-ui-height, var(--_viewport-height));
+    --_max-width: var(--ag-ui-max-width, var(--_viewport-width));
+    --_max-height: var(--ag-ui-max-height, var(--_viewport-height));
+    --_panel-radius: var(--ag-ui-panel-radius, 0);
+    --_shadow: var(--ag-ui-shadow, none);
+  }
+
+  /* Nothing to resize once the panel is the screen, and the grips would sit
+     under the thumbs holding the phone. */
+  :host([placement="floating"]:not([data-small-viewport="off"])) .resize-handle,
+  :host([placement="bottom-left"]:not([data-small-viewport="off"])) .resize-handle,
+  :host([placement="sidebar"]:not([data-small-viewport="off"])) .resize-handle,
+  :host([placement="side"]:not([data-small-viewport="off"])) .resize-handle,
+  :host(:not([placement]):not([data-small-viewport="off"])) .resize-handle,
+  :host([placement=""]:not([data-small-viewport="off"])) .resize-handle {
+    display: none;
+  }
+
+  /* The bottom bar shows only while collapsed. With the panel open the panel
+     is the screen, its header's minimise control is the way back, and a
+     second strip fixed to the bottom edge would sit under the keyboard while
+     the composer has focus. Hidden by display, so the bar measures 0 and the
+     host's padding goes with it. */
+  :host([data-collapsed-to="bar"]:not([collapsed]):not([data-small-viewport="off"])) .dock-bar {
+    display: none;
+  }
+}
+`;

package/src/ui/placement/surface_for.ts

@@ -0,0 +1,183 @@
+import type { ResizeAxis } from "./resize_handle.js";
+
+/**
+ * What a collapsed panel shrinks to, stamped on the element as
+ * data-collapsed-to so the stylesheet draws it.
+ *
+ * - `launcher` -- the round button in a corner.
+ * - `rail` -- the slim full-height edge the sidebar docks against; the same
+ *   launcher element, shaped by the stylesheet.
+ * - `header` -- the in-flow collapse: the body hides and the header bar stays
+ *   in the host's layout, so there is no launcher at all.
+ * - `bar` -- `collapse-to="bar"` over a placement that would otherwise
+ *   collapse to `launcher`: a strip along the bottom edge, the panel rising
+ *   from its right end.
+ * - `none` -- `collapse-to="none"` over any collapsible placement: collapsed
+ *   is hidden, and the host's own control brings the panel back.
+ * - `null` -- no collapsed state. `page` is a dedicated route rather than a
+ *   panel on someone else's page, so there is no "away" for it to go to:
+ *   collapsing it left a strip of application chrome fixed over a route with
+ *   no owner, and it hides the launcher, so the usual way back did not exist.
+ *   The header drops its collapse control here, but a control removed from
+ *   the UI is not a state removed from the model: the property, the attribute
+ *   and a value restored from storage all still reach it, so every one of
+ *   those paths asks this record; the stylesheet covers the one path that
+ *   never does, an attribute written straight onto the element.
+ */
+export type CollapseTarget = "launcher" | "rail" | "header" | "bar" | "none" | null;
+
+/**
+ * Everything the script needs to know about one display surface, in one
+ * record, so a placement's behaviour is read in one place rather than
+ * assembled from a table per question.
+ *
+ * The stylesheet still carries each surface's look (one module per placement
+ * under this directory); this is the part of a surface that code decides.
+ */
+export interface Surface {
+  /** What collapsing shrinks the panel to; `null` when it cannot collapse. */
+  readonly collapseTo: CollapseTarget;
+  /**
+   * Whether a gesture may move the launcher. The rest have nowhere to put it:
+   * the rail is a docked edge, `header` and `null` have no launcher, a
+   * full-bleed panel covers the screen it would be opening into, and the bar
+   * and the host's own control are not a launcher at all.
+   */
+  readonly launcherDraggable: boolean;
+  /**
+   * Whether the header drag and `moveTo` may move the open panel. The same
+   * answer as {@link launcherDraggable} for every placement on its own; the two
+   * part under `collapse-to="bar"` and `"none"`, where a corner panel still
+   * moves like one but has no launcher left to drag.
+   */
+  readonly panelMovable: boolean;
+  /**
+   * Which axes the resize grips may change. A full-bleed layout is the whole
+   * viewport by definition and cannot be resized; a docked panel owns its
+   * height, leaving only its inner edge.
+   */
+  readonly resizeAxis: ResizeAxis;
+  /**
+   * Whether a first mount with nothing stored starts collapsed. Only the
+   * corner placements do: a launcher is the resting state of every corner chat
+   * in the field, and mounting open put a 380x560 panel over the host page's
+   * corner on a visitor's first load, uninvited. The placements that place
+   * themselves start open -- a host that docks a sidebar has already decided
+   * the widget belongs on screen, and one that embeds it has given it a box.
+   *
+   * Separate from {@link launcherDraggable} although the two agree today:
+   * "has a launcher to rest on" and "the launcher can be moved" are different
+   * questions, and a surface with a fixed launcher would answer them apart.
+   */
+  readonly startsCollapsed: boolean;
+  /**
+   * What the header's maximize control grows: both axes for a corner or docked
+   * panel, the width for a side column, and `null` where there is no control
+   * (a surface that already fills its box, or that the host sized).
+   */
+  readonly maximizes: "both" | "width" | null;
+}
+
+const CORNER: Surface = {
+  collapseTo: "launcher",
+  launcherDraggable: true,
+  panelMovable: true,
+  resizeAxis: "both",
+  startsCollapsed: true,
+  maximizes: "both",
+};
+
+const DOCKED: Surface = {
+  collapseTo: "launcher",
+  launcherDraggable: false,
+  panelMovable: false,
+  resizeAxis: "width",
+  startsCollapsed: false,
+  maximizes: "width",
+};
+
+/**
+ * One record per `placement` value. Absent (`null`) and empty are the default
+ * floating corner, as the stylesheet treats them.
+ */
+const SURFACES: ReadonlyMap<string | null, Surface> = new Map<string | null, Surface>([
+  [null, CORNER],
+  ["", CORNER],
+  ["floating", CORNER],
+  ["bottom-left", CORNER],
+  ["side", DOCKED],
+  ["sidebar", { ...DOCKED, collapseTo: "rail" }],
+  [
+    "full",
+    {
+      collapseTo: "launcher",
+      launcherDraggable: false,
+      panelMovable: false,
+      resizeAxis: "none",
+      startsCollapsed: false,
+      maximizes: null,
+    },
+  ],
+  [
+    "page",
+    {
+      collapseTo: null,
+      launcherDraggable: false,
+      panelMovable: false,
+      resizeAxis: "none",
+      startsCollapsed: false,
+      maximizes: null,
+    },
+  ],
+  [
+    "embedded",
+    {
+      collapseTo: "header",
+      launcherDraggable: false,
+      panelMovable: false,
+      resizeAxis: "both",
+      startsCollapsed: false,
+      maximizes: null,
+    },
+  ],
+]);
+
+/**
+ * A value no record names. The stylesheet lays it out as the default corner,
+ * but the script has never treated an unknown value as one: its launcher stays
+ * put and it mounts open, so a typo in a host's markup does not start moving
+ * or hiding a panel the host meant to show.
+ */
+const UNKNOWN: Surface = {
+  collapseTo: "launcher",
+  launcherDraggable: false,
+  panelMovable: false,
+  resizeAxis: "both",
+  startsCollapsed: false,
+  maximizes: null,
+};
+
+/**
+ * The surface `placement` and `collapse-to` describe together. Read per
+ * interaction by every caller, because both are live attributes.
+ *
+ * `collapse-to` only ever replaces the round launcher or the whole collapsed
+ * state, never a placement's own shape: `bar` applies where the placement
+ * collapses to `launcher`, so the sidebar keeps its rail and an embedded chat
+ * its header bar, and `none` applies to every collapsible placement. Absent,
+ * `auto` and any other value leave the placement as it was. Both turn the
+ * launcher drag off, because there is no launcher left to drag, and keep the
+ * placement's own answer for moving the panel: a corner panel rises from the
+ * bar or the anchor until the user drags it somewhere else, and a placement
+ * that owns its position keeps owning it.
+ */
+export function surfaceFor(placement: string | null, collapseTo: string | null = null): Surface {
+  const surface = SURFACES.get(placement) ?? UNKNOWN;
+  if (collapseTo === "bar" && surface.collapseTo === "launcher") {
+    return { ...surface, collapseTo: "bar", launcherDraggable: false };
+  }
+  if (collapseTo === "none" && surface.collapseTo !== null) {
+    return { ...surface, collapseTo: "none", launcherDraggable: false };
+  }
+  return surface;
+}

package/src/ui/progress/prettify_tool_name.ts

@@ -0,0 +1,16 @@
+/**
+ * Prettify a raw tool name for display: separators become spaces and the
+ * first letter is capitalised — `list_projects` → "List projects",
+ * `invoices.retrieve` → "Invoices retrieve".
+ *
+ * Final fallback of the tool-card label chain (`x-summary` →
+ * `toolSummaries` → fetched catalog → this). Purely cosmetic: the original
+ * name still rides on the card's dataset for debugging.
+ */
+export function prettifyToolName(name: string): string {
+  const spaced = name.replace(/[._-]+/g, " ").trim();
+  if (spaced === "") {
+    return name;
+  }
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}

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/run_notice.ts

@@ -0,0 +1,61 @@
+/**
+ * A muted one-line notice about something the run did (history condensed, a
+ * skill loaded), rendered inline between turns.
+ *
+ * Distinct from a tool card, which reports work the agent asked for and
+ * settles, and from an error, which is a failure. A notice never settles and
+ * takes no action of its own.
+ *
+ * It may carry exactly one control, and only ever an undo. That is a narrower
+ * rule than "no controls", which is what this said until the agent could move
+ * the panel it speaks from: something that rearranges the user's window without
+ * being asked has to be both visible and reversible, and a notice is already
+ * the surface that says what the run did. Anything the user has to *decide* is
+ * a confirmation card instead -- the difference is that this reports something
+ * already done.
+ */
+export function renderRunNotice(
+  icon: string,
+  text: string,
+  kind: string,
+  undo?: { readonly label: string; readonly onActivate: () => void },
+): HTMLDivElement {
+  const notice = document.createElement("div");
+  notice.className = `run-notice run-notice--${kind}`;
+  notice.setAttribute("part", `run-notice run-notice-${kind}`);
+  // status, not alert: informational, so it must not interrupt a screen reader
+  // mid-sentence. Polite announcements land after the current utterance.
+  notice.setAttribute("role", "status");
+
+  const glyph = document.createElement("span");
+  glyph.className = "run-notice-icon";
+  glyph.setAttribute("part", "run-notice-icon");
+  glyph.textContent = icon;
+  // Decorative: the adjacent text already says what happened, so announcing the
+  // glyph's name would only add noise.
+  glyph.setAttribute("aria-hidden", "true");
+
+  const label = document.createElement("span");
+  label.className = "run-notice-text";
+  label.setAttribute("part", "run-notice-text");
+  label.textContent = text;
+
+  notice.append(glyph, label);
+
+  if (undo !== undefined) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "run-notice-undo";
+    button.setAttribute("part", "run-notice-undo");
+    button.textContent = undo.label;
+    button.addEventListener("click", () => {
+      // One use. The state it restores is the state as it was when the notice
+      // was written, so offering it twice would put back something that has
+      // since moved again.
+      button.disabled = true;
+      undo.onActivate();
+    });
+    notice.append(button);
+  }
+  return notice;
+}

package/src/ui/progress/run_notice_styles.ts

@@ -0,0 +1,52 @@
+// The one-line notice a run leaves in the transcript, with its undo.
+export const RUN_NOTICE_STYLES: string = `
+.run-notice {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  align-self: flex-start;
+  max-width: 100%;
+  margin: 2px 0;
+  padding: 3px 10px;
+  border: 1px dashed var(--_border);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--_muted);
+  font-size: 0.8em;
+  line-height: 1.4;
+}
+
+.run-notice-icon {
+  flex: none;
+  opacity: 0.75;
+}
+
+/* The one control a notice may carry. Quiet, because it reports something
+   already done rather than asking for a decision. */
+.run-notice-undo {
+  flex: 0 0 auto;
+  margin-inline-start: auto;
+  padding: 2px 8px;
+  border: 1px solid var(--_border);
+  border-radius: var(--_radius);
+  background: var(--_bg);
+  color: var(--_accent);
+  font: inherit;
+  font-size: 0.9em;
+  cursor: pointer;
+}
+
+.run-notice-undo:hover:not(:disabled) {
+  background: var(--_hover);
+}
+
+.run-notice-undo:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.run-notice-text {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+`;

package/src/ui/progress/subagent_panel.ts

@@ -0,0 +1,227 @@
+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 child agent's name, as the last update that carried one gave it.
+   *
+   * Read back rather than only written to the DOM, because the two carriers
+   * split the name away from the close: `SUBAGENT_STARTED` names the agent and
+   * `SUBAGENT_FINISHED` carries only an id, so whoever words the closing line
+   * has to recover the name from what the delegation already told it.
+   */
+  get agent(): string | null {
+    return this.#agent;
+  }
+
+  /**
+   * 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>();
+  #agent: string | null = null;
+
+  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.#agent = update.agent;
+      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));
+  }
+}