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

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"]),
+  };
+}

package/src/ui/suggestion_chips.ts

@@ -0,0 +1,73 @@
+import type { UiStrings } from "./ui_strings.js";
+
+/**
+ * Most prompts one push may draw.
+ *
+ * **Keep in step with `MAX_SUGGESTIONS` in django-ag-ui's
+ * `agent/suggestions_activity.py`**, which raises past it. Mirroring is the
+ * whole point: this side silently draws no more than its limit and has no
+ * channel to report the difference, so a producer that does not know the same
+ * number ships suggestions that never appear. That is the hole the chart bounds
+ * exist to close, and it was found there by shipping it.
+ */
+export const MAX_SUGGESTIONS = 4;
+
+/** Longest one prompt may be. Mirrored for the same reason as the count. */
+export const MAX_SUGGESTION_CHARS = 120;
+
+/** The `prompts` a `suggestions` activity carries, or `null` when it carries none. */
+export function suggestionPrompts(content: unknown): string[] | null {
+  if (typeof content !== "object" || content === null) {
+    return null;
+  }
+  const raw = (content as { prompts?: unknown }).prompts;
+  if (!Array.isArray(raw)) {
+    return null;
+  }
+  const prompts = raw
+    .filter((prompt): prompt is string => typeof prompt === "string")
+    .map((prompt) => prompt.trim())
+    .filter((prompt) => prompt !== "" && prompt.length <= MAX_SUGGESTION_CHARS)
+    .slice(0, MAX_SUGGESTIONS);
+  return prompts.length === 0 ? null : prompts;
+}
+
+/**
+ * Draw follow-up prompts as chips that send themselves when clicked.
+ *
+ * Returns `null` when nothing survives, which is the registry's signal to draw
+ * nothing rather than an empty row -- the same contract the chart renderer uses
+ * for a spec it cannot draw.
+ *
+ * Buttons rather than links or list items: each one performs an action in the
+ * page, and the thing it sends is the label, so the accessible name is the
+ * prompt itself and needs no `aria-label` restating it.
+ */
+export function renderSuggestionChips(
+  content: unknown,
+  strings: UiStrings,
+  onPick: (prompt: string) => void,
+): HTMLElement | null {
+  const prompts = suggestionPrompts(content);
+  if (prompts === null) {
+    return null;
+  }
+  const row = document.createElement("div");
+  row.className = "suggestions";
+  row.setAttribute("part", "suggestions");
+  // A group, labelled: without it a screen reader meets a row of unrelated
+  // buttons with no hint that they are the assistant's offer rather than the
+  // page's own controls.
+  row.setAttribute("role", "group");
+  row.setAttribute("aria-label", strings.suggestions);
+  for (const prompt of prompts) {
+    const chip = document.createElement("button");
+    chip.type = "button";
+    chip.className = "suggestion-chip";
+    chip.setAttribute("part", "suggestion-chip");
+    chip.textContent = prompt;
+    chip.addEventListener("click", () => onPick(prompt));
+    row.appendChild(chip);
+  }
+  return row;
+}

package/src/ui/thread_drawer.ts

@@ -1,5 +1,5 @@
 import type { ThreadMeta } from "../core/conversation_store.js";
-import { relativeTime } from "./relative_time.js";
+import { type RelativeTimeFormatter, relativeTime } from "./relative_time.js";
 import { DEFAULT_UI_STRINGS, type UiStrings } from "./ui_strings.js";
 
 /** Actions the host ({@link AgUiChat}) wires to the drawer's rows. */
@@ -35,6 +35,7 @@ export class ThreadDrawer {
   readonly #heading: HTMLSpanElement;
   readonly #newButton: HTMLButtonElement;
   readonly #list: HTMLDivElement;
+  #formatRelativeTime: RelativeTimeFormatter | null = null;
   #strings: UiStrings;
   #threads: readonly ThreadMeta[] = [];
   #activeId = "";
@@ -91,6 +92,25 @@ export class ThreadDrawer {
   }
 
   /** Re-localize the drawer's chrome and rows (the host calls this on connect). */
+  /**
+   * Replace the timestamp formatter, or restore the built-in with `null`.
+   *
+   * The built-in is deliberately locale-neutral -- there is no `Intl` anywhere
+   * in this component, so it never disagrees with a host's own formatting by
+   * guessing a locale. That is a defensible default and a poor requirement, so
+   * this is the way out.
+   */
+  setRelativeTimeFormatter(format: RelativeTimeFormatter | null): void {
+    this.#formatRelativeTime = format;
+  }
+
+  /** This row's timestamp, through the host's formatter when it set one. */
+  #formatTime(timestamp: number): string {
+    return this.#formatRelativeTime !== null
+      ? this.#formatRelativeTime(timestamp)
+      : relativeTime(timestamp, undefined, this.#strings);
+  }
+
   setStrings(strings: UiStrings): void {
     this.#strings = strings;
     this.#panel.setAttribute("aria-label", strings.chatHistory);
@@ -202,7 +222,7 @@ export class ThreadDrawer {
     const time = document.createElement("span");
     time.className = "drawer-row-time";
     time.setAttribute("part", "drawer-row-time");
-    time.textContent = relativeTime(meta.updatedAt, undefined, this.#strings);
+    time.textContent = this.#formatTime(meta.updatedAt);
     const preview = document.createElement("span");
     preview.className = "drawer-row-preview";
     preview.setAttribute("part", "drawer-row-preview");

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;
@@ -90,6 +168,17 @@ export class ToolCallCard {
   readonly #resultLabel: HTMLSpanElement;
   readonly #resultBody: HTMLPreElement;
   readonly #strings: UiStrings;
+  /**
+   * The arguments this call was made with.
+   *
+   * Retained rather than only rendered, because an approval interrupt names a
+   * `toolCallId` and nothing else -- so this card is the only place the args
+   * 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(
@@ -97,8 +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";
@@ -137,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;
 
@@ -166,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);
   }
 
   /**
@@ -215,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

@@ -33,6 +33,18 @@ export interface UiStrings {
   // ── Messages region ─────────────────────────────────────────────────────────
   /** `aria-label` of the scrolling message log. */
   conversation: string;
+  /** The button offering to return to the foot of the transcript. */
+  jumpToLatest: string;
+  /** Announced when a turn starts. Screen-reader only; never rendered. */
+  announceResponding: string;
+  /** Announced when the answer has finished arriving. Screen-reader only. */
+  announceAnswerReady: string;
+  /** Announced when a card is waiting for the user's decision. Token: `{count}`. */
+  announceAwaitingDecision: string;
+  /** Announced when the user stopped the run. Screen-reader only. */
+  announceStopped: string;
+  /** Announced when the run failed. Screen-reader only. */
+  announceFailed: string;
   /** `aria-label` of the "thinking" pending indicator, and the thoughts region's
    * header while the model is still reasoning. */
   thinking: string;
@@ -48,6 +60,10 @@ export interface UiStrings {
   declinedAction: string;
   /** A navigating tool's card text while the page reloads. */
   navigating: string;
+  /** Notice shown when the server replaced the conversation wholesale. */
+  historyReplaced: string;
+  /** Notice shown when a pushed chart could not be drawn and was removed. */
+  chartUndrawable: string;
   /** Missing-placeholder skill hint. Tokens: `{title}`, `{fields}`. */
   skillNeeds: string;
   /** Notice shown when the agent condensed earlier turns. Token: `{count}`. */
@@ -115,9 +131,45 @@ 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;
+  /** Shown when the edited arguments are not valid JSON. */
+  approvalArgsInvalid: string;
+  /** Shown when the edited arguments parse but are not a JSON object. */
+  approvalArgsNotAnObject: string;
+  /** `aria-label` of the follow-up suggestion chips row. */
+  suggestions: string;
+  /** `aria-label` of a message's action row. */
+  messageActions: string;
+  /** The offer that floats beside a selection in the transcript. */
+  quoteSelection: string;
+  /** Copy this message (button `title` / `aria-label`). Its confirmation and
+   * failure text are the code block's `copied` / `copyFailed`, which say the
+   * same thing about the same clipboard. */
+  copyMessage: string;
+  /** Ask for a different answer to the same question. */
+  retryMessage: string;
+  /** Rate this answer as good. */
+  feedbackUp: string;
+  /** Rate this answer as poor. */
+  feedbackDown: string;
   /** `aria-label` of the inline confirmation card. */
   confirmAction: string;
+  /** Waive confirmation for this tool for the rest of the session. Token: `{tool}`. */
+  confirmAlways: string;
   /** Generic confirmation prompt when a tool has no `x-confirm`. Token: `{tool}`. */
   confirmRun: string;
   /** Confirm button. */
@@ -229,6 +281,12 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   forkedRun: "branched",
 
   conversation: "Conversation",
+  jumpToLatest: "Jump to latest",
+  announceResponding: "Assistant is responding",
+  announceAnswerReady: "Assistant answered",
+  announceAwaitingDecision: "{count} action is waiting for your approval",
+  announceStopped: "Response stopped",
+  announceFailed: "The response failed",
   thinking: "Assistant is thinking…",
   thoughts: "Thoughts",
   stopped: "⏹ Stopped",
@@ -236,6 +294,9 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   noResult: "No result returned.",
   declinedAction: "User declined the action.",
   navigating: "Navigating…",
+  historyReplaced:
+    "The server replaced this conversation's history. Reload to see the updated transcript.",
+  chartUndrawable: "A chart could not be drawn from the data sent, so it was removed.",
   historyCompacted: "Earlier turns condensed to fit the context window ({count} removed)",
   usingSkill: "Using skill {name}",
   runInterrupted: "The previous response didn’t finish — the page changed before it arrived.",
@@ -270,7 +331,21 @@ 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.",
+  suggestions: "Suggested follow-ups",
+  messageActions: "Message actions",
+  quoteSelection: "Quote",
+  copyMessage: "Copy message",
+  retryMessage: "Try again",
+  feedbackUp: "Good answer",
+  feedbackDown: "Poor answer",
   confirmAction: "Confirm action",
+  confirmAlways: "Always allow",
   confirmRun: "Run “{tool}”?",
   confirm: "Confirm",
   cancel: "Cancel",

package/src/version.ts

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