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

package/dist/ui/tool_call_card.d.ts

@@ -8,6 +8,56 @@ export type ToolDisplayMode = (typeof TOOL_DISPLAY)[keyof typeof TOOL_DISPLAY];
 export type UnsettledStatus = typeof TOOL_CALL_STATUS.PENDING | typeof TOOL_CALL_STATUS.DEFERRED;
 /** The terminal states a card settles into (everything unsettled excluded). */
 export type SettledStatus = Exclude<ToolCallStatus, UnsettledStatus>;
+/**
+ * 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.
  *
@@ -27,6 +77,12 @@ export type SettledStatus = Exclude<ToolCallStatus, UnsettledStatus>;
  * `--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}.
  */
@@ -48,7 +104,31 @@ export declare class ToolCallCard {
      * Empty until used, and hidden while empty by the shadow CSS.
      */
     readonly approvalSlot: HTMLDivElement;
-    constructor(name: string, args: Record<string, unknown>, summary?: string, strings?: UiStrings);
+    /**
+     * 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;
+    /**
+     * 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>;
+    constructor(name: string, args: Record<string, unknown>, summary?: string, strings?: UiStrings, options?: ToolCallCardOptions);
     /**
      * Move between the two states that are not an outcome — `pending` (running)
      * and `deferred` (gated, waiting on a person).

package/dist/ui/tool_call_card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool_call_card.d.ts","sourceRoot":"","sources":["../../src/ui/tool_call_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEtF,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE/E,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC,OAAO,GAAG,OAAO,gBAAgB,CAAC,QAAQ,CAAC;AAEjG,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;AA+BrE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;;IACvB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IAWtC,YACE,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,SAA8B,EAuExC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAMlC;IAED;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAKlD;IAED,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAYhD;CAoCF"}
+{"version":3,"file":"tool_call_card.d.ts","sourceRoot":"","sources":["../../src/ui/tool_call_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEtF,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE/E,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,OAAO,gBAAgB,CAAC,OAAO,GAAG,OAAO,gBAAgB,CAAC,QAAQ,CAAC;AAEjG,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;AA+BrE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEN;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;AAElF,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,YAAY;;IACvB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IAStC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMvC,YACE,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,SAA8B,EACvC,OAAO,GAAE,mBAAwB,EAkFlC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAMlC;IAED;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAKlD;IAED,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAgBhD;CAkEF"}

package/dist/ui/ui_strings.d.ts

@@ -30,6 +30,18 @@ export interface UiStrings {
     toggleTheme: string;
     /** `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;
@@ -45,6 +57,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}`. */
@@ -107,8 +123,42 @@ export interface UiStrings {
     declinedLabel: string;
     /** Label on the toggle that expands a tool card's body. */
     details: string;
+    /**
+     * 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;
+    /** `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. */

package/dist/ui/ui_strings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui_strings.d.ts","sourceRoot":"","sources":["../../src/ui/ui_strings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ui_strings.d.ts","sourceRoot":"","sources":["../../src/ui/ui_strings.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artooi/ag-ui-web-component",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Framework-free <ag-ui-chat> Web Component over the AG-UI protocol. Drop-in chat sidebar with a pluggable client-side tool registry, DOM driver primitives, animations, and destructive-action confirmation modal.",
   "type": "module",
   "main": "./dist/index.js",

package/src/constants.ts

@@ -54,6 +54,110 @@ export const ATTACHMENT_EVENT = "ag-ui-attachments";
  */
 export const RUN_FINISHED_EVENT = "ag-ui-run-finished";
 
+/**
+ * The agent sent an AG-UI `CUSTOM` event. `detail` is {@link CustomAgentDetail}.
+ *
+ * `CUSTOM` is one of exactly two carriers whose payload name the protocol leaves
+ * an open string, and it is the **imperative** one: something for the host page
+ * to *do*, with no place in the transcript. Its sibling `ACTIVITY_SNAPSHOT`
+ * carries transcript **content**, which is why that one is materialised into a
+ * message, persisted, and replayed on restore while this one is not.
+ *
+ * That asymmetry is the rule for choosing between them. Content has a place in
+ * the conversation and should replay; an imperative has no place and no meaning
+ * once acted on, so replaying it on a thread load would be a bug. Anything that
+ * must survive a reload belongs on the other carrier.
+ *
+ * The element takes no view of what a name means -- it forwards every one. A
+ * host that does not recognise a name ignores the event, which is the graceful
+ * outcome the open field exists for.
+ */
+export const CUSTOM_AGENT_EVENT = "ag-ui-custom";
+
+/**
+ * The agent named resources its write has moved. `detail` is
+ * {@link InvalidateDetail}.
+ *
+ * A convention on top of {@link CUSTOM_AGENT_EVENT}, not a second channel: the
+ * wire carries an ordinary AG-UI `CUSTOM` event whose `name` is
+ * {@link INVALIDATE_CUSTOM_NAME}, and this is that one name routed to its own
+ * DOM event so a host does not have to string-match. Every other name still
+ * arrives as `ag-ui-custom`.
+ *
+ * Fires **as each announcement arrives**, during the run, which is what makes a
+ * long multi-step run feel live: the list refreshes as the third of eight writes
+ * lands rather than when everything finishes. {@link RUN_FINISHED_EVENT} carries
+ * the same keys again at the end, de-duplicated, for a host that would rather
+ * refetch once.
+ */
+export const INVALIDATE_EVENT = "ag-ui-invalidate";
+
+/**
+ * Fired when the user rates an assistant message from its action row.
+ *
+ * `detail` is a {@link FeedbackDetail}: the rated message's text and the
+ * rating. **Nothing is stored** -- a rating belongs to whatever the host
+ * already uses to hold product signals, and a write-only table inside a chat
+ * widget is a schema nobody reads.
+ */
+export const FEEDBACK_EVENT = "ag-ui-feedback";
+
+/**
+ * The `activity_type` carrying server-pushed follow-up prompts.
+ *
+ * Matches django-ag-ui's `SUGGESTIONS_ACTIVITY_TYPE`. A convention inside the
+ * protocol's open `activity_type` field, not an extension of it -- so a client
+ * that has never heard of it ignores the event, and this one is not privileged.
+ */
+export const SUGGESTIONS_ACTIVITY_TYPE = "suggestions";
+
+/**
+ * The AG-UI `CUSTOM` event `name` that carries an invalidation.
+ *
+ * Matched exactly. Namespaced so it cannot collide with a host's own custom
+ * events, which share the field.
+ */
+export const INVALIDATE_CUSTOM_NAME = "ag_ui.invalidate";
+
+/**
+ * The AG-UI `CUSTOM` event `name` carrying a delegated sub-agent's progress.
+ *
+ * Matched exactly, and namespaced the way {@link INVALIDATE_CUSTOM_NAME} is, so
+ * it cannot collide with a host's own custom events on the same open field.
+ *
+ * Routed to the delegating tool card rather than dispatched to the page: the
+ * payload keys on the **parent's own `delegate_task` call id**, so what it
+ * describes is already on screen and the progress belongs beside it. Every other
+ * name still reaches the host as {@link CUSTOM_AGENT_EVENT}.
+ *
+ * Deliberately on the imperative carrier and not on an activity, which means it
+ * is **never persisted and never replayed**. That is the right half of the
+ * split: a delegation that was live an hour ago is not live now, and replaying
+ * its progress on a thread restore would be a lie about a run that is over. On a
+ * reload mid-run the nested detail is gone and the tool card remains.
+ */
+export const SUBAGENT_CUSTOM_NAME = "ag_ui.subagent";
+
+/**
+ * The phases one delegation moves through, as the server spells them.
+ *
+ * Exactly one `STARTED` opens a delegation and exactly one `FINISHED` or
+ * `FAILED` closes it; the two tool phases repeat in between, once per call the
+ * child makes and once per result it gets back.
+ *
+ * `FAILED` carries **no exception text**, deliberately — the same reasoning that
+ * redacts a `RUN_ERROR`, since an exception's words are written for an operator.
+ * The detail rides the ordinary `TOOL_CALL_RESULT` for that delegation, on the
+ * card the progress is already attached to.
+ */
+export const SUBAGENT_PHASE = {
+  STARTED: "started",
+  TOOL_CALL: "tool_call",
+  TOOL_RESULT: "tool_result",
+  FINISHED: "finished",
+  FAILED: "failed",
+} as const;
+
 /** Roles a chat message can take. */
 export const MESSAGE_ROLE = {
   USER: "user",
@@ -93,9 +197,32 @@ export const X_NAVIGATES_KEY = "x-navigates";
  */
 export const READ_PAGE_TOOL = "read_page";
 
-/** Upper bound on frontend tool-call → re-run rounds within one send. */
+/**
+ * Default upper bound on frontend tool-call → re-run rounds within one send.
+ * Overridable via `data-max-tool-rounds`, or `AgUiClientConfig.maxToolRounds`
+ * for a host driving the client directly.
+ */
 export const MAX_TOOL_ROUNDS = 10;
 
+/**
+ * The actions a finished assistant message's row can carry, and the tokens
+ * `data-message-actions` selects them by.
+ *
+ * All three are on when the attribute is absent. Naming them individually
+ * rather than shipping one on/off switch is what the three differ over: feedback
+ * is only useful to a host listening for {@link FEEDBACK_EVENT}, retry re-runs
+ * the agent and a constrained surface may not permit that, and copy is the one
+ * nobody objects to. A single switch would make dropping either of the first two
+ * cost the third, and a host that only wanted one gone would rebuild the row
+ * from `attachMessageActions` -- reimplementing the part names, the accessible
+ * grouping and the retry hand-off to lose two buttons.
+ */
+export const MESSAGE_ACTIONS = {
+  COPY: "copy",
+  RETRY: "retry",
+  FEEDBACK: "feedback",
+} as const;
+
 /**
  * Lifecycle status of a rendered tool-call card. A card opens as `PENDING`
  * while the call runs, then settles to `DONE`, `ERROR`, or `DECLINED`.
@@ -221,3 +348,13 @@ export const ICON_FILE_TEXT = `<svg class="glyph" viewBox="0 0 24 24" aria-hidde
  * event, which is the graceful outcome.
  */
 export const CHART_ACTIVITY_TYPE = "chart";
+
+/**
+ * How long a screen-reader status stays in the announcer before it is emptied.
+ *
+ * Long enough for a reader to pick the change up, short enough that the region
+ * is empty again before the next status lands. Emptying is what makes an
+ * identical consecutive message announce at all -- a live region is read on
+ * *change*, and setting the same string twice is not one.
+ */
+export const ANNOUNCE_CLEAR_MS = 150;