@artooi/ag-ui-web-component 0.31.0 → 0.32.0

package/src/core/ag_ui_chat.ts

@@ -22,6 +22,7 @@ import {
   RUN_FINISHED_EVENT,
   STATE_EVENT,
   SUBAGENT_CUSTOM_NAME,
+  SUBAGENT_PHASE,
   SUBMIT_EVENT,
   SUGGESTIONS_ACTIVITY_TYPE,
   TOGGLE_EVENT,
@@ -82,7 +83,7 @@ import { renderRunNotice } from "../ui/run_notice.js";
 import { SkillsMenu } from "../ui/skills_menu.js";
 import { createStickToBottom, type StickToBottom } from "../ui/stick_to_bottom.js";
 import { STYLES } from "../ui/styles.js";
-import { SubAgentPanel } from "../ui/subagent_panel.js";
+import { SubAgentPanel, type SubAgentPhase, type SubAgentUpdate } from "../ui/subagent_panel.js";
 import { subAgentUpdate } from "../ui/subagent_update.js";
 import { renderSuggestionChips } from "../ui/suggestion_chips.js";
 import { ThoughtsBlock } from "../ui/thoughts_block.js";
@@ -630,6 +631,17 @@ export class AgUiChat extends HTMLElement {
    * 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>();
   /**
    * Call ids whose card was already settled from a streamed server-side result
    * (`TOOL_CALL_RESULT`), so the post-run executeTool sweep doesn't overwrite
@@ -2473,6 +2485,7 @@ export class AgUiChat extends HTMLElement {
     // the correct half of that split -- a delegation that was live before this
     // transcript was wiped is not live now.
     this.#subagentPanels.clear();
+    this.#subagentRunDelegations.clear();
     this.#serverSettled.clear();
     this.#cardElements.clear();
     this.#activityBlocks.clear();
@@ -3945,6 +3958,32 @@ export class AgUiChat extends HTMLElement {
           }),
         );
       },
+      // The delegation's own lifetime, on the protocol's events rather than the
+      // CUSTOM channel its steps ride. Both end at the same panel.
+      onSubAgentStarted: (subagentRunId, agent, parentToolCallId) => {
+        // 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.#applySubAgent({
+          delegationId: parentToolCallId,
+          agent: agent === "" ? null : agent,
+          phase: SUBAGENT_PHASE.STARTED,
+          status: this.#strings.subAgentDelegatedTo.replace("{agent}", agent),
+          tool: null,
+        });
+      },
+      onSubAgentFinished: (subagentRunId) => {
+        this.#closeSubAgent(subagentRunId, SUBAGENT_PHASE.FINISHED, null);
+      },
+      onSubAgentError: (subagentRunId, message) => {
+        // 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.
+        this.#closeSubAgent(subagentRunId, SUBAGENT_PHASE.FAILED, message);
+      },
       onMessagesSnapshot: () => {
         // Honoured for persistence and announced, not re-rendered.
         //
@@ -4144,6 +4183,57 @@ export class AgUiChat extends HTMLElement {
     if (update === null) {
       return;
     }
+    this.#applySubAgent(update);
+  }
+
+  /**
+   * 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 #reportSubAgent}: 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.
+   */
+  /**
+   * 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.
+   */
+  #closeSubAgent(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.#applySubAgent({
+      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 {
+    return agent === null
+      ? this.#strings.subAgentWorking
+      : this.#strings.subAgentFinished.replace("{agent}", agent);
+  }
+
+  #applySubAgent(update: SubAgentUpdate): void {
     const card = this.#toolCards.get(update.delegationId);
     if (card === undefined) {
       return;

package/src/core/agui_client.ts

@@ -127,6 +127,31 @@ export interface AgUiClientHandlers {
    * be the thing the open field exists to avoid.
    */
   onCustomEvent(name: string, value: unknown): void;
+  /**
+   * A delegated sub-agent started, inside the run.
+   *
+   * The protocol's own event, unlike the steps that follow it on
+   * {@link SUBAGENT_CUSTOM_NAME}. `parentToolCallId` links the delegation to the
+   * `delegate_task` call that spawned it -- the field AG-UI provides for the
+   * "agents as tools" shape -- and is `null` when the server did not send one,
+   * which a host reads as a delegation it has nothing to attach to.
+   *
+   * `subagentRunId` names the child run and is the only id the two closing
+   * events carry, so a host that wants to close what it opened has to remember
+   * the pairing.
+   */
+  onSubAgentStarted(subagentRunId: string, name: string, parentToolCallId: string | null): void;
+  /** The delegation named by `subagentRunId` completed. */
+  onSubAgentFinished(subagentRunId: string): void;
+  /**
+   * The delegation named by `subagentRunId` failed.
+   *
+   * `message` is server text and required by the protocol, but it is not an
+   * exception's words: `django-ag-ui` sends only which sub-agent failed, on the
+   * same reasoning that redacts a `RUN_ERROR`. Render it as text, never as
+   * markup.
+   */
+  onSubAgentError(subagentRunId: string, message: string): void;
   onError(message: string): void;
   /**
    * Fired when the user cancelled the run ({@link AgUiClient.cancel}) — the
@@ -567,6 +592,22 @@ export class AgUiClient {
       onCustomEvent({ event }) {
         h.onCustomEvent(event.name, event.value);
       },
+      // The delegation lifecycle. Forwarded rather than interpreted here, for
+      // the reason every other subscriber in this block is thin: this file
+      // adapts the protocol to the handler surface, and what a delegation looks
+      // like on screen is the element's business.
+      //
+      // `parentToolCallId` is optional on the wire and normalised to `null` so
+      // the handler has one absent-value to check rather than two.
+      onSubagentStartedEvent({ event }) {
+        h.onSubAgentStarted(event.subagentRunId, event.name, event.parentToolCallId ?? null);
+      },
+      onSubagentFinishedEvent({ event }) {
+        h.onSubAgentFinished(event.subagentRunId);
+      },
+      onSubagentErrorEvent({ event }) {
+        h.onSubAgentError(event.subagentRunId, event.message);
+      },
       onMessagesSnapshotEvent({ event }) {
         h.onMessagesSnapshot(event.messages as readonly Message[]);
       },

package/src/ui/styles.ts

@@ -524,6 +524,15 @@ export const STYLES = `
    floating circle that would escape the host's layout. */
 :host([collapsed]) {
   pointer-events: none;
+  /* A collapsed host has to be allowed to shrink, and in the layout hosts
+     actually use it is not. Every collapse path here works by letting the host
+     size to its content -- the in-flow ones set height: auto, the floating one
+     leaves only the launcher -- and a flex or grid parent whose align-items is
+     the default stretch value overrides all of it. The panel then hides and the box
+     it occupied stays: a header bar over several hundred pixels of nothing.
+     Every known consumer hit this, because putting the element in a flex column
+     beside the page content is the obvious way to embed it. */
+  align-self: start;
 }
 
 :host([collapsed]) .chat {

package/src/ui/subagent_panel.ts

@@ -82,6 +82,18 @@ 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.
    *
@@ -94,6 +106,7 @@ export class SubAgentPanel {
   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");
@@ -151,6 +164,7 @@ export class SubAgentPanel {
   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) {

package/src/ui/subagent_update.ts

@@ -5,6 +5,15 @@
  * 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

package/src/ui/ui_strings.ts

@@ -140,6 +140,25 @@ export interface UiStrings {
    * must never be blank.
    */
   subAgentWorking: string;
+  /**
+   * The row's line while a delegation is running. Token: `{agent}`.
+   *
+   * Worded here rather than on the wire, unlike the two step phases. The
+   * protocol's `SUBAGENT_STARTED` carries the sub-agent's `name` and no rendered
+   * status -- which is the better shape for a localised UI, and the reason this
+   * string exists at all.
+   */
+  subAgentDelegatedTo: string;
+  /** The row's line once a delegation completed. Token: `{agent}`. */
+  subAgentFinished: string;
+  /**
+   * The row's line for a delegation that failed and named no agent.
+   *
+   * A fallback only: `SUBAGENT_ERROR` carries a required `message`, which the
+   * server fills with the sub-agent's name and nothing else, and that text is
+   * what the row shows. This covers a server that sent an empty one.
+   */
+  subAgentFailed: string;
   /** `aria-label` of the region holding the sub-agent's own tool calls. */
   subAgentSteps: string;
 
@@ -332,6 +351,9 @@ export const DEFAULT_UI_STRINGS: UiStrings = {
   details: "Details",
 
   subAgentWorking: "Working…",
+  subAgentDelegatedTo: "Delegated to {agent}",
+  subAgentFinished: "{agent} finished",
+  subAgentFailed: "The sub-agent failed",
   subAgentSteps: "Steps the sub-agent took",
 
   approvalEditArgs: "Edit the arguments before approving",

package/src/version.ts

@@ -1 +1 @@
-export const VERSION: string = "0.31.0";
+export const VERSION: string = "0.32.0";