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

package/src/ui/progress/subagent_progress.ts

@@ -0,0 +1,200 @@
+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`.
+   * Without this a run that hands work to a sub-agent reads as a stall, the
+   * card sitting at "running…" for the child's whole duration, so the narration
+   * goes *into* that card rather than 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/subagent_update.ts

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ *
+ * **The three lifecycle phases are still accepted here, deliberately.** A current
+ * server sends only `tool_call` and `tool_result` on this carrier -- the
+ * delegation's lifetime moved to the protocol's `SUBAGENT_*` events -- but a
+ * server one release older sends all five, and this element is published and
+ * vendored separately from it. Continuing to narrow the older shape costs
+ * nothing (the panel needs those phases as visual states regardless) and is the
+ * difference between a mixed-version pair that degrades and one that shows a
+ * delegation which never opens.
+ *
+ * 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"]),
+  };
+}

package/src/ui/progress/thoughts_block.ts

@@ -0,0 +1,165 @@
+import { fillUiString } from "../fill_ui_string.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
+
+/** Below this, a reasoning block is too short to time and its header reads `thoughts`. */
+const TIMED_FROM_MS = 1000;
+
+/**
+ * A muted "thinking" region for a reasoning model's streamed chain-of-thought.
+ *
+ * Sits at the top of the current answer group. Its header reads `thinking`
+ * while the model reasons, and {@link settle} stops the clock and names how
+ * long it took ("Thought for 4s"). {@link stream} replaces the body with the
+ * running buffer, which opens expanded and folds away on {@link collapse},
+ * once the answer's first text token arrives.
+ *
+ * The header is a disclosure only while there is text behind it. A provider
+ * that reasons without sending any -- redacted thinking, or reasoning with
+ * its summaries off -- still opens and closes a block, and a toggle there
+ * folded and unfolded an empty, ruled box. Until the buffer has text the
+ * header is a plain label and the body is not drawn; the first text turns the
+ * label into the toggle, and the body comes with it.
+ *
+ * Pure DOM. The host inserts {@link element}; all visible chrome text comes
+ * from {@link UiStrings}. The clock is injectable so the timing is testable.
+ */
+export class ThoughtsBlock {
+  /** The block's root element; insert this at the top of the answer group. */
+  readonly element: HTMLDivElement;
+
+  readonly #label: HTMLSpanElement;
+  readonly #body: HTMLPreElement;
+  readonly #toggle: HTMLButtonElement;
+  readonly #strings: UiStrings;
+  readonly #now: () => number;
+  /** When the running round started, or `null` once {@link settle} stopped the clock. */
+  #startedAt: number | null;
+  /** The reasoning time of the rounds already settled, in milliseconds. */
+  #elapsed = 0;
+  #collapsed = false;
+  #hasText = false;
+
+  /**
+   * Build the block as reasoning starts, which is when its clock starts.
+   *
+   * @param strings - The resolved string table.
+   * @param now - The clock, in milliseconds; `performance.now` unless a test
+   *   supplies its own.
+   */
+  constructor(
+    strings: UiStrings = DEFAULT_UI_STRINGS,
+    now: () => number = () => performance.now(),
+  ) {
+    this.#strings = strings;
+    this.#now = now;
+    this.#startedAt = now();
+
+    this.element = document.createElement("div");
+    this.element.className = "thoughts";
+    this.element.setAttribute("part", "thoughts");
+    // Lets CSS animate the header while the model is still reasoning; dropped
+    // when the block settles.
+    this.element.setAttribute("data-streaming", "");
+
+    this.#toggle = document.createElement("button");
+    this.#toggle.type = "button";
+    this.#toggle.className = "thoughts-toggle";
+    this.#toggle.setAttribute("part", "thoughts-toggle");
+    this.#toggle.setAttribute("aria-expanded", "true");
+
+    this.#label = document.createElement("span");
+    this.#label.className = "thoughts-label";
+    this.#label.setAttribute("part", "thoughts-label");
+    this.#label.textContent = strings.thinking;
+
+    this.#body = document.createElement("pre");
+    this.#body.className = "thoughts-body";
+    this.#body.setAttribute("part", "thoughts-body");
+    this.#body.hidden = true;
+
+    this.#toggle.addEventListener("click", () => {
+      this.#setCollapsed(!this.#collapsed);
+    });
+
+    // The label stands alone until there is text for the toggle to open onto.
+    this.element.append(this.#label, this.#body);
+  }
+
+  /**
+   * A further round of reasoning in the same turn, after a tool call settled
+   * the first: restart the clock and the live header. The rounds' times add
+   * up. Ignored while the clock is already running.
+   */
+  begin(): void {
+    if (this.#startedAt !== null) {
+      return;
+    }
+    this.#startedAt = this.#now();
+    this.element.setAttribute("data-streaming", "");
+    this.#label.textContent = this.#strings.thinking;
+  }
+
+  /** Replace the reasoning body with the running buffer (the full text so far). */
+  stream(buffer: string): void {
+    this.#body.textContent = buffer;
+    this.#setHasText(buffer.trim() !== "");
+  }
+
+  /**
+   * Stop the clock and settle the header to how long the reasoning took.
+   *
+   * Called when reasoning ends, or by whatever arrives first in its place --
+   * the answer's text, a tool call, or the turn ending -- so the live label
+   * never outlives the reasoning. Idempotent: only the first call after a
+   * start counts.
+   */
+  settle(): void {
+    if (this.#startedAt === null) {
+      return;
+    }
+    this.#elapsed += this.#now() - this.#startedAt;
+    this.#startedAt = null;
+    this.element.removeAttribute("data-streaming");
+    this.#label.textContent =
+      this.#elapsed < TIMED_FROM_MS
+        ? this.#strings.thoughts
+        : fillUiString(this.#strings.thoughtFor, {
+            seconds: Math.round(this.#elapsed / TIMED_FROM_MS),
+          });
+  }
+
+  /**
+   * Fold the region away when the answer's first text token arrives, settling
+   * the header first. Idempotent, since the per-token text handler calls it
+   * repeatedly.
+   */
+  collapse(): void {
+    this.settle();
+    if (this.#collapsed) {
+      return;
+    }
+    this.#setCollapsed(true);
+  }
+
+  /** Swap the header between the plain label and the toggle around it. */
+  #setHasText(hasText: boolean): void {
+    if (hasText === this.#hasText) {
+      return;
+    }
+    this.#hasText = hasText;
+    if (hasText) {
+      this.#toggle.append(this.#label);
+      this.element.prepend(this.#toggle);
+    } else {
+      this.#toggle.remove();
+      this.element.prepend(this.#label);
+    }
+    this.#setCollapsed(this.#collapsed);
+  }
+
+  #setCollapsed(collapsed: boolean): void {
+    this.#collapsed = collapsed;
+    this.#body.hidden = collapsed || !this.#hasText;
+    this.#toggle.setAttribute("aria-expanded", String(!collapsed));
+  }
+}

package/src/ui/progress/thoughts_styles.ts

@@ -0,0 +1,74 @@
+// The collapsible reasoning region over an assistant turn.
+export const THOUGHTS_STYLES: string = `
+/* ── Thoughts region ────────────────────────────────────────────
+   A muted, collapsible chain-of-thought at the top of the answer group: open
+   while the model reasons, folded once the answer text starts. A block with
+   no text is a label alone, with no toggle and no body. */
+.thoughts {
+  align-self: stretch;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--_muted);
+}
+
+.thoughts-toggle {
+  align-self: flex-start;
+  border: none;
+  padding: 0;
+  background: none;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--_muted);
+  cursor: pointer;
+}
+
+.thoughts-toggle::before {
+  content: var(--_disclosure-expanded) " ";
+}
+
+.thoughts-toggle[aria-expanded="false"]::before {
+  content: var(--_disclosure-collapsed) " ";
+}
+
+/* The label is the whole header while the reasoning has no text, a plain line
+   with nothing to open; once there is text it sits inside the toggle, which
+   sets the same weight. */
+.thoughts-label {
+  align-self: flex-start;
+  font-weight: 600;
+}
+
+/* A gentle pulse on the label while reasoning is still streaming. */
+.thoughts[data-streaming] .thoughts-label {
+  animation: ag-ui-thoughts-pulse 1.4s ease-in-out infinite;
+}
+
+@keyframes ag-ui-thoughts-pulse {
+  0%, 100% { opacity: 0.55; }
+  50% { opacity: 1; }
+}
+
+.thoughts-body {
+  margin: 0;
+  padding: 4px 0 4px 10px;
+  border-left: 2px solid var(--_border);
+  max-height: 220px;
+  overflow: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+  font-family: inherit;
+}
+
+.thoughts-body[hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .thoughts[data-streaming] .thoughts-label {
+    animation: none;
+  }
+}
+`;