@artooi/ag-ui-web-component 0.25.2 → 0.26.1

package/src/core/ag_ui_chat.ts

@@ -1,6 +1,7 @@
 import type { Context, Interrupt, Message, Tool } from "@ag-ui/core";
 import {
   ATTACHMENT_EVENT,
+  CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
   DEFAULT_ATTACHMENT_MAX_BYTES,
   ICON_ATTACH,
@@ -23,6 +24,7 @@ import {
 import { fillTemplate } from "../skills/fill_template.js";
 import { parseSkills } from "../skills/parse_skills.js";
 import type { Skill } from "../skills/skill.js";
+import type { ChartRenderer } from "../tools/client_tool_registry.js";
 import { type ClientTool, ClientToolRegistry } from "../tools/client_tool_registry.js";
 import { isDestructive } from "../tools/is_destructive.js";
 import { isNavigates } from "../tools/is_navigates.js";
@@ -39,6 +41,9 @@ import {
 import { attachCopyButtons } from "../ui/attach_copy_buttons.js";
 import { renderAttachmentChips } from "../ui/attachment_chips.js";
 import { AttachmentTray } from "../ui/attachment_tray.js";
+import { renderChart } from "../ui/chart_block.js";
+import { chartSpecFrom } from "../ui/chart_spec_from.js";
+import { CHART_TOOL_NAME, createChartTool } from "../ui/chart_tool.js";
 import { CheckpointMenu, type CheckpointVerb } from "../ui/checkpoint_menu.js";
 import { type ConfirmationRequest, requestConfirmation } from "../ui/confirmation_card.js";
 import { prettifyToolName } from "../ui/prettify_tool_name.js";
@@ -392,6 +397,15 @@ export class AgUiChat extends HTMLElement {
    * (`TOOL_CALL_RESULT`), so the post-run executeTool sweep doesn't overwrite
    * the real output with the generic "executed on the server" fallback.
    */
+  /** Whether a server-pushed chart activity is drawn. Off unless asked for. */
+  #chartActivity = false;
+
+  /** Card elements by call id, so a rendering handler can find its own card. */
+  readonly #cardElements = new Map<string, HTMLElement>();
+
+  /** Chart blocks by activity message id, so an update redraws in place. */
+  readonly #activityBlocks = new Map<string, HTMLElement>();
+
   readonly #serverSettled = new Set<string>();
   /**
    * Tool calls made during the current interaction, in the order they started,
@@ -1662,6 +1676,8 @@ export class AgUiChat extends HTMLElement {
     this.#hidePending();
     this.#toolCards.clear();
     this.#serverSettled.clear();
+    this.#cardElements.clear();
+    this.#activityBlocks.clear();
     this.#initialMessages = [];
     this.#attachTray?.clear();
     // Keep the empty-state region; everything else clears.
@@ -1822,7 +1838,29 @@ export class AgUiChat extends HTMLElement {
         if (this.#noticeIfSkillLoad(restored)) {
           continue;
         }
-        this.#cardFor(restored);
+        this.#cardElements.set(restored.id, this.#cardFor(restored).element);
+        // Only `render` is replayed, never `handler`. A restored transcript
+        // redraws what the call drew; it must not re-run what the call *did*.
+        // Only the renderer is handed over, never the tool. The guarantee that
+        // a reload cannot re-run a tool's *effect* is worth more than a comment
+        // saying so: this signature cannot reach `handler`, so a later
+        // maintainer adding a "no render? fall back to the handler" convenience
+        // here has to change the type first, which is exactly the moment the
+        // question should be asked.
+        const render = this.#resolveTool(restored.name)?.render;
+        if (render !== undefined) {
+          this.#renderToolOutput(render, restored);
+        }
+      }
+      return;
+    }
+    if (message.role === "activity") {
+      // The client materialises a pushed activity as a message of its own, so a
+      // chart's data is in the transcript already and survives a reload. Only
+      // the drawing had to be put back.
+      const activity = message as unknown as { activityType?: unknown; content?: unknown };
+      if (activity.activityType === CHART_ACTIVITY_TYPE && this.#chartActivity) {
+        this.#drawActivityChart(message.id, activity.content);
       }
       return;
     }
@@ -2539,6 +2577,10 @@ export class AgUiChat extends HTMLElement {
     }
     const card = this.#cardFor(call);
     this.#toolCards.delete(call.id);
+    // Kept after the card leaves `#toolCards`: a tool that renders into the
+    // transcript places itself against its own card, and by the time it runs the
+    // card is no longer reachable by id.
+    this.#cardElements.set(call.id, card.element);
     const tool = this.#resolveTool(call.name);
     if (tool === null) {
       // Not a client tool. A server-side tool's real output arrives via
@@ -2613,7 +2655,14 @@ export class AgUiChat extends HTMLElement {
       this.conversationStore.saveCheckpoint(this.#threadId, { toolCallId: call.id });
     }
     try {
-      const result = await tool.handler(call.args);
+      // The call id lets a handler that renders into the transcript find its
+      // own card; handlers that only act on the page ignore it.
+      const result = await tool.handler(call.args, call.id);
+      // Drawn from the arguments rather than the result, so the live path and
+      // the replay path render the same thing from the same input.
+      if (tool.render !== undefined) {
+        this.#renderToolOutput(tool.render, call);
+      }
       if (navigates) {
         card.settle(TOOL_CALL_STATUS.DONE, this.#strings.navigating);
         return { content: "", halt: true };
@@ -2775,7 +2824,13 @@ export class AgUiChat extends HTMLElement {
         this.#runTools.push({ id: call.id, name: call.name });
         this.#cardFor(call);
       },
-      onActivity: (activityType, content) => {
+      onActivity: (activityType, content, messageId) => {
+        if (activityType === CHART_ACTIVITY_TYPE) {
+          if (this.#chartActivity) {
+            this.#drawActivityChart(messageId, content);
+          }
+          return;
+        }
         if (activityType !== COMPACTION_ACTIVITY_TYPE) {
           return;
         }
@@ -2811,6 +2866,11 @@ export class AgUiChat extends HTMLElement {
         // that shipped in the same release is what makes showing them safe now.
         this.#showPending();
       },
+      onActivityChanged: (messageId, activityType, content) => {
+        if (activityType === CHART_ACTIVITY_TYPE && this.#chartActivity) {
+          this.#drawActivityChart(messageId, content);
+        }
+      },
       onRunEnd: () => {
         // Per-round end; the button stays on Stop until the whole interaction
         // settles — the user must be able to cancel between tool rounds.
@@ -2983,6 +3043,108 @@ export class AgUiChat extends HTMLElement {
     this.#messages.scrollTop = this.#messages.scrollHeight;
   }
 
+  /**
+   * Turn on chart rendering, by whichever route this consumer wants.
+   *
+   * Both routes converge on one renderer deliberately. Built apart they become
+   * two chart implementations with two sets of bugs, and the choice between them
+   * is about *where the data lives* rather than how a bar should look:
+   *
+   * - `"tool"` registers the built-in `render_chart`. The agent decides a chart
+   *   helps and calls it, so the numbers are in its context and it can discuss
+   *   them afterwards. Costs one model round, and works over any transport.
+   * - `"activity"` draws a server-pushed `ACTIVITY_SNAPSHOT` of type `chart`.
+   *   No round trip, and the data never enters the model's context at all —
+   *   which is what makes it the one for a large or sensitive dataset. Only this
+   *   route can update a chart in place as the server computes.
+   *
+   * Off unless asked for, both of them: a component that renders whatever
+   * arrives is not something to switch on for everybody.
+   */
+  enableCharts(routes: readonly ("tool" | "activity")[] = ["tool", "activity"]): void {
+    const first = !this.#chartActivity && !this.#toolRegistry.has(CHART_TOOL_NAME);
+    if (routes.includes("activity")) {
+      this.#chartActivity = true;
+    }
+    if (routes.includes("tool")) {
+      this.registerTool(createChartTool());
+    }
+    // Called after the element is connected, the history has already replayed
+    // and every chart in it was skipped -- charts were off at the time. That is
+    // the ordinary way to call this (you have to query the element to call
+    // anything on it), so redrawing rather than documenting an ordering rule is
+    // the only answer that does not make the obvious usage wrong.
+    if (first && this.isConnected) {
+      this.reload();
+    }
+  }
+
+  /**
+   * Place a tool's rendered node against its own card.
+   *
+   * Anchored rather than appended because a client tool's handler does not run
+   * until the round is over: appending would put the node after everything the
+   * model said next, visibly detached from the call that produced it, and in a
+   * different order than the same transcript takes on reload. The card was
+   * created inline, in the right place, so anchoring makes *when* the handler
+   * runs stop mattering.
+   */
+  #renderToolOutput(render: ChartRenderer, call: AgUiToolCall): void {
+    let node: Node | null;
+    try {
+      node = render(call.args);
+    } catch (error) {
+      // `render` is consumer code and this runs inside the history replay, where
+      // a throw abandons the loop and takes every later turn of the transcript
+      // with it -- silently, and again on every reload. A chart that fails to
+      // draw is worth losing; the rest of the conversation is not. Reported so
+      // the failure is findable rather than merely survived.
+      console.warn(`ag-ui-chat: render failed for tool ${call.name}`, error);
+      return;
+    }
+    if (node === null) {
+      return;
+    }
+    // `after` rather than an insert-or-append branch: both callers set the card
+    // element immediately before calling, and a parentless anchor makes `after`
+    // a no-op, so the alternative would be a branch nothing can reach.
+    this.#cardElements.get(call.id)?.after(node);
+    this.#afterTranscriptGrew();
+  }
+
+  /** Draw, or redraw in place, the chart for one activity message. */
+  #drawActivityChart(messageId: string, content: unknown): void {
+    const spec = chartSpecFrom(content);
+    const block = spec === null ? null : renderChart(spec);
+    if (block === null) {
+      // The server superseded this chart with something undrawable. Leaving the
+      // old one up is the worst available answer: it shows numbers that have
+      // been retracted, reading as current, and a reload then drops the chart
+      // entirely because the *stored* content is the version we could not draw.
+      // Live and reload should agree, and both should say "gone" rather than
+      // one of them lying.
+      this.#activityBlocks.get(messageId)?.remove();
+      this.#activityBlocks.delete(messageId);
+      return;
+    }
+    const existing = this.#activityBlocks.get(messageId);
+    if (existing === undefined) {
+      this.#ensureGroup().appendChild(block);
+    } else {
+      // Replaced rather than appended: a server redrawing a chart under the same
+      // id means *this chart changed*, and a second copy below the first would
+      // read as two measurements instead of one that moved.
+      existing.replaceWith(block);
+    }
+    this.#activityBlocks.set(messageId, block);
+    this.#afterTranscriptGrew();
+  }
+
+  #afterTranscriptGrew(): void {
+    this.#updateEmptyState();
+    this.#messages.scrollTop = this.#messages.scrollHeight;
+  }
+
   #cardFor(call: AgUiToolCall): ToolCallCard {
     const existing = this.#toolCards.get(call.id);
     if (existing !== undefined) {

package/src/core/agui_client.ts

@@ -83,7 +83,18 @@ export interface AgUiClientHandlers {
    * as opposed to work the agent asked for. `django-ag-ui` emits one with
    * `activityType: "compaction"` when it condensed the history.
    */
-  onActivity(activityType: string, content: unknown): void;
+  onActivity(activityType: string, content: unknown, messageId: string): void;
+  /**
+   * An activity's content changed in place — a snapshot re-sent under the same
+   * `messageId` with `replace`, or an `ACTIVITY_DELTA` whose JSON patch
+   * `@ag-ui/client` has already applied.
+   *
+   * Reported after the client has updated its own message, so `content` is the
+   * result rather than the instruction. That is the whole reason this is a
+   * separate callback: the raw delta event fires *before* the patch lands, and
+   * a subscriber acting on it would redraw from stale content.
+   */
+  onActivityChanged(messageId: string, activityType: string, content: unknown): void;
   /** Fired when a reasoning model starts emitting its chain-of-thought. */
   onReasoningStart(): void;
   /** Fired on every reasoning token; ``buffer`` is the full reasoning text so far. */
@@ -397,6 +408,9 @@ export class AgUiClient {
   #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
     const closed = this.#closedMessageIds;
+    // Charts whose patch has been dispatched but not yet applied. Scoped to the
+    // subscriber, so it cannot outlive the run that created it.
+    const pendingDeltas = new Set<string>();
     return {
       onRunInitialized() {
         h.onRunStart();
@@ -434,8 +448,42 @@ export class AgUiClient {
       onToolCallResultEvent({ event }) {
         h.onToolResult(event.toolCallId, event.content);
       },
-      onActivitySnapshotEvent({ event }) {
-        h.onActivity(event.activityType, event.content);
+      onActivitySnapshotEvent({ event, messages }) {
+        // A snapshot for an id already in the list is a replacement, not a new
+        // activity: the client has swapped its content in place, and a second
+        // append would leave the superseded one on screen.
+        const known = messages.some(
+          (message) => message.id === event.messageId && message.role === "activity",
+        );
+        if (known) {
+          h.onActivityChanged(event.messageId, event.activityType, event.content);
+          return;
+        }
+        h.onActivity(event.activityType, event.content, event.messageId);
+      },
+      // Deliberately does *not* read the message here. `@ag-ui/client`
+      // dispatches this subscriber **before** applying the patch, so the
+      // message still holds its previous content: redrawing from it would leave
+      // the chart one revision behind for the life of the run, and disagreeing
+      // with what a reload shows. Note which chart moved and read the result on
+      // the change that follows.
+      onActivityDeltaEvent({ event }) {
+        pendingDeltas.add(event.messageId);
+      },
+      // Emitted after the client has written the patched messages, which is the
+      // first moment the result exists. Only the ids marked above are looked at,
+      // so an ordinary text delta does not walk the transcript.
+      onMessagesChanged({ messages }) {
+        if (pendingDeltas.size === 0) {
+          return;
+        }
+        for (const id of pendingDeltas) {
+          const message = messages.find((entry) => entry.id === id);
+          if (message !== undefined && message.role === "activity") {
+            h.onActivityChanged(id, message.activityType, message.content);
+          }
+        }
+        pendingDeltas.clear();
       },
       // `@ag-ui/client` maps the deprecated THINKING_* events onto these
       // REASONING_* callbacks, so the reasoning family alone covers both

package/src/index.ts

@@ -2,6 +2,7 @@
 
 export {
   ATTACHMENT_EVENT,
+  CHART_ACTIVITY_TYPE,
   COMPACTION_ACTIVITY_TYPE,
   ELEMENT_TAG,
   LOAD_CAPABILITY_TOOL,
@@ -129,6 +130,13 @@ export {
   type ApprovalRequest,
   requestApproval,
 } from "./ui/approval_card.js";
+// Charts. `CHART_ACTIVITY_TYPE` above is the wire name a server sets on an
+// ACTIVITY_SNAPSHOT; these are the shape it carries and the renderer itself,
+// for a host building its own visual on the same seam.
+export type { ChartKind, ChartSeries, ChartSpec } from "./ui/chart_block.js";
+export { renderChart } from "./ui/chart_block.js";
+export { chartSpecFrom } from "./ui/chart_spec_from.js";
+export { CHART_TOOL_NAME } from "./ui/chart_tool.js";
 export { CheckpointMenu, type CheckpointVerb } from "./ui/checkpoint_menu.js";
 export {
   type ConfirmationOptions,

package/src/tools/client_tool_registry.ts

@@ -7,11 +7,44 @@ import type { Tool } from "@ag-ui/core";
  * `handler` receives the parsed arguments and returns a result that is
  * JSON-serialised into the AG-UI tool-result message sent back to the agent.
  */
+/**
+ * Draws one call from its arguments alone.
+ *
+ * Named separately so the replay path can take *this* and never the tool that
+ * owns it: a function of this type cannot reach a `handler`, which is what
+ * makes "a reload never re-runs a tool's effect" a property of the code rather
+ * than a note asking maintainers to be careful.
+ */
+export type ChartRenderer = (args: Record<string, unknown>) => Node | null;
+
 export interface ClientTool {
   name: string;
   description: string;
   parameters: Record<string, unknown>;
-  handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+  /**
+   * Run the tool. `callId` identifies the call being executed, for a handler
+   * that renders into the transcript and needs to place itself against its own
+   * card; handlers that only act on the page ignore it.
+   */
+  handler: (args: Record<string, unknown>, callId?: string) => unknown | Promise<unknown>;
+  /**
+   * Draw this call, from its arguments alone.
+   *
+   * Optional, and **the only half that is replayed**. A restored transcript
+   * redraws by calling `render`; it never calls {@link handler}. That is what
+   * keeps a replayable tool apart from an effectful one *structurally* rather
+   * than by promise: the restore path holds no reference to the half that acts,
+   * so re-running `fill_field` on every reload is not a mistake anyone can make.
+   *
+   * The contract this must keep, because it runs again on every restore:
+   *
+   * - a pure function of `args` — no host state, no network, no clock;
+   * - deterministic, so a reload reproduces what was there before;
+   * - free of effects outside the node it returns, which the component places.
+   *
+   * Return `null` for arguments that say nothing worth drawing.
+   */
+  render?: ChartRenderer;
 }
 
 /**