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

package/src/ui/tool_call_card.ts

@@ -42,6 +42,61 @@ function formatPayload(text: string): string {
   }
 }
 
+/**
+ * One region of a card's body, handed to a host {@link ToolPayloadFormatter}.
+ *
+ * A discriminated union rather than three positional parameters because the two
+ * halves do not carry the same thing: arguments are the parsed record the call
+ * was made with, and a result is the raw string the tool returned, which may not
+ * be JSON at all. Flattening both into one `payload` parameter would force every
+ * formatter to re-derive which it had before it could read it, and the
+ * arguments would arrive re-serialised for no reason.
+ *
+ * `toolName` is the raw tool name, not the card's `x-summary` label -- a
+ * formatter dispatches on identity, and the label is a display string a server
+ * may change.
+ */
+export type ToolPayload =
+  | {
+      readonly kind: "arguments";
+      readonly toolName: string;
+      readonly args: Record<string, unknown>;
+    }
+  | {
+      readonly kind: "result";
+      readonly toolName: string;
+      readonly status: SettledStatus;
+      readonly text: string;
+    };
+
+/**
+ * Renders one region of a tool card's body, for a host that would rather show a
+ * table or a summary line than a wall of pretty-printed JSON.
+ *
+ * Return a `Node` to take the region over, a `string` to replace its text, or
+ * `null` to fall through to the built-in pretty-print -- so a formatter that
+ * only cares about one tool, or only about results, declines the rest rather
+ * than reimplementing them.
+ *
+ * **Presentation only.** The model reads the tool result from its own copy of
+ * the message, which this never touches, so anything said here is said to the
+ * person and not to the agent. Translating a value -- an enum constant into a
+ * friendly label, an epoch into a date -- belongs on the server, where it also
+ * reaches the model's prose; doing it here would make the card and the answer
+ * beside it disagree about what happened.
+ *
+ * A returned string is set as text, never parsed as markup: this is not a
+ * second HTML channel into the transcript, and a host that wants elements
+ * builds them itself and returns the node.
+ */
+export type ToolPayloadFormatter = (payload: ToolPayload) => Node | string | null;
+
+/** Optional per-card wiring beyond the name, arguments, label and strings. */
+export interface ToolCallCardOptions {
+  /** Host presentation hook for both body regions. See {@link ToolPayloadFormatter}. */
+  readonly formatPayload?: ToolPayloadFormatter;
+}
+
 /**
  * A live tool-call card for the chat transcript.
  *
@@ -61,6 +116,12 @@ function formatPayload(text: string): string {
  * `--ag-ui-tool-icon-*` custom properties or the `tool-card-icon` part without
  * the card reaching into the host stylesheet.
  *
+ * Either region may be drawn by the host instead: `options.formatPayload` is
+ * asked about each one and pretty-prints as before whenever it declines. The
+ * arguments are offered from the constructor and the result from {@link settle},
+ * because that is when each exists -- so a formatter is asked twice per card,
+ * potentially long apart.
+ *
  * Pure DOM. The host appends {@link element} into its shadow root; all visible
  * text comes from {@link UiStrings}.
  */
@@ -83,6 +144,23 @@ export class ToolCallCard {
    */
   readonly approvalSlot: HTMLDivElement;
 
+  /**
+   * Where a *nested* run's progress renders — the sub-agent this call delegated
+   * to, narrating itself while the card waits.
+   *
+   * A slot rather than a rendered thing, on the same reasoning as
+   * {@link approvalSlot}: the card owns the position and something else owns the
+   * content. What makes the position right is that the wire keys a delegation on
+   * this card's own `toolCallId`, so the run being narrated is the one this card
+   * already stands for.
+   *
+   * Placed above the Details toggle rather than inside the body, because the
+   * body is what the display modes hide — and a progress line that only appears
+   * in `full` mode would leave exactly the stall it exists to end. Empty on every
+   * card that delegated nothing, and hidden while empty by the shadow CSS.
+   */
+  readonly subagentSlot: HTMLDivElement;
+
   readonly #status: HTMLSpanElement;
   readonly #decision: HTMLSpanElement;
   readonly #toggle: HTMLButtonElement;
@@ -98,6 +176,9 @@ export class ToolCallCard {
    * still exist when the user is asked to approve, edit or deny the call.
    */
   readonly args: Record<string, unknown>;
+  /** The raw tool name, kept for the payloads handed to {@link ToolPayloadFormatter}. */
+  readonly #name: string;
+  readonly #formatPayload: ToolPayloadFormatter | null;
   #settled = false;
 
   constructor(
@@ -105,9 +186,12 @@ export class ToolCallCard {
     args: Record<string, unknown>,
     summary?: string,
     strings: UiStrings = DEFAULT_UI_STRINGS,
+    options: ToolCallCardOptions = {},
   ) {
     this.#strings = strings;
     this.args = args;
+    this.#name = name;
+    this.#formatPayload = options.formatPayload ?? null;
 
     this.element = document.createElement("div");
     this.element.className = "tool-call";
@@ -146,7 +230,11 @@ export class ToolCallCard {
     head.append(icon, label, this.#status, this.#decision);
 
     const argsSection = this.#section("args", strings.argumentsLabel);
-    argsSection.body.textContent = JSON.stringify(args, null, 2);
+    this.#renderPayload(
+      argsSection.body,
+      { kind: "arguments", toolName: name, args },
+      JSON.stringify(args, null, 2),
+    );
     // Drop the region rather than frame an empty object.
     argsSection.root.hidden = Object.keys(args).length === 0;
 
@@ -175,7 +263,11 @@ export class ToolCallCard {
     this.approvalSlot.className = "tool-call-approval";
     this.approvalSlot.setAttribute("part", "tool-card-approval");
 
-    this.element.append(head, this.#toggle, body, this.approvalSlot);
+    this.subagentSlot = document.createElement("div");
+    this.subagentSlot.className = "tool-call-subagent";
+    this.subagentSlot.setAttribute("part", "tool-card-subagent");
+
+    this.element.append(head, this.subagentSlot, this.#toggle, body, this.approvalSlot);
   }
 
   /**
@@ -224,10 +316,44 @@ export class ToolCallCard {
     this.element.setAttribute("data-status", status);
     this.#status.textContent = statusLabels(this.#strings)[status];
     this.#resultLabel.textContent = resultLabels(this.#strings)[status];
-    this.#resultBody.textContent = formatPayload(text);
+    this.#renderPayload(
+      this.#resultBody,
+      { kind: "result", toolName: this.#name, status, text },
+      formatPayload(text),
+    );
     this.#resultSection.hidden = false;
   }
 
+  /**
+   * Fill one body region, offering it to the host formatter first.
+   *
+   * `fallback` is computed by the caller rather than here because the two
+   * regions build it differently -- arguments are already parsed, a result is a
+   * string that may or may not be JSON -- and because a formatter that takes
+   * the region over should not have paid for a pretty-print nobody sees. It is
+   * cheap either way; the point is that the built-in rendering stays written
+   * once, beside the payload it belongs to.
+   *
+   * The `data-formatted` marker is what the shadow CSS reads to relax the
+   * preformatted whitespace on a region a host owns -- a table inherits it as
+   * mangled cell spacing, a sentence as line breaks nobody typed. Marked for a
+   * returned string too: one rule, and a summary line wants ordinary wrapping
+   * as much as a table does.
+   */
+  #renderPayload(body: HTMLPreElement, payload: ToolPayload, fallback: string): void {
+    const rendered = this.#formatPayload === null ? null : this.#formatPayload(payload);
+    if (rendered === null) {
+      body.textContent = fallback;
+      return;
+    }
+    body.setAttribute("data-formatted", "true");
+    if (typeof rendered === "string") {
+      body.textContent = rendered;
+      return;
+    }
+    body.replaceChildren(rendered);
+  }
+
   /** Build one labelled region of the body: a heading plus a payload block. */
   #section(
     kind: string,

package/src/ui/ui_strings.ts

@@ -131,6 +131,18 @@ export interface UiStrings {
   /** Label on the toggle that expands a tool card's body. */
   details: string;
 
+  // ── Delegated sub-agent ─────────────────────────────────────────────────────
+  /**
+   * The delegation row's text before the server's own status line lands.
+   *
+   * A fallback, not a state: every announcement carries a pre-rendered `status`,
+   * and this only shows if one arrives unusable. The row is the expander, so it
+   * must never be blank.
+   */
+  subAgentWorking: string;
+  /** `aria-label` of the region holding the sub-agent's own tool calls. */
+  subAgentSteps: string;
+
   // ── Confirmation card ───────────────────────────────────────────────────────
   /** `aria-label` of the editable arguments field on an approval card. */
   approvalEditArgs: string;
@@ -319,6 +331,9 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   declinedLabel: "Declined",
   details: "Details",
 
+  subAgentWorking: "Working…",
+  subAgentSteps: "Steps the sub-agent took",
+
   approvalEditArgs: "Edit the arguments before approving",
   approvalArgsInvalid: "That is not valid JSON, so nothing was sent.",
   approvalArgsNotAnObject: "Arguments have to be a JSON object.",

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.29.0";
+export const VERSION: string = "0.30.0";