@artooi/agents-web-components 0.0.0-stage → 0.1.1

package/dist/ui/progress/subagent_progress.d.ts

@@ -0,0 +1,57 @@
+import type { UiStrings } from "../ui_strings.js";
+import type { ToolCallCard } from "./tool_call_card.js";
+/** What delegated progress needs from the element that owns it. */
+export interface SubAgentProgressHost {
+    /** The tool card drawn for a call id, which a delegation's panel hangs off. */
+    readonly card: (callId: string) => ToolCallCard | undefined;
+    /** The resolved string table. */
+    readonly strings: () => UiStrings;
+    /** Keep the transcript at its foot, if the reader is there. */
+    readonly follow: () => void;
+}
+/**
+ * A delegated sub-agent's progress, hung off the card that delegated: the live
+ * panels by delegation, and which delegation each child run belongs to.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export declare class SubAgentProgress {
+    #private;
+    constructor(host: SubAgentProgressHost);
+    /**
+     * Draw one step of a delegated sub-agent's progress, on the card that
+     * delegated.
+     *
+     * `delegationId` is the parent's own `delegate_task` tool-call id, so the
+     * attachment point is a card this element already drew on `TOOL_CALL_START`.
+     * Without this a run that hands work to a sub-agent reads as a stall, the
+     * card sitting at "running…" for the child's whole duration, so the narration
+     * goes *into* that card rather than a second element with the same identity.
+     *
+     * A progress event for a call this client never drew is dropped. It has no
+     * card to attach to, and inventing a floating one is precisely the alternative
+     * that was rejected: parent and child interleave in the transcript with
+     * nothing marking whose is whose, and the persisted transcript -- which never
+     * held the progress at all -- would not match what was on screen.
+     *
+     * Nothing here writes to the conversation store. `CUSTOM` never enters
+     * `agent.messages`, so a reload mid-run leaves the tool card and loses the
+     * nested detail, which is the intended behaviour rather than a gap.
+     */
+    report(value: unknown): void;
+    /** Open a delegation, on `SUBAGENT_STARTED`. */
+    start(subagentRunId: string, agent: string, parentToolCallId: string | null): void;
+    /** Settle a delegation that completed, on `SUBAGENT_FINISHED`. */
+    finish(subagentRunId: string): void;
+    /** Settle a delegation that failed, on `SUBAGENT_ERROR`. */
+    fail(subagentRunId: string, message: string): void;
+    /**
+     * Forget every delegation. The panels go with the cards they hung off.
+     * Nothing restores them: the progress rode the imperative carrier and was
+     * never persisted, which is the correct half of that split -- a delegation
+     * that was live before this transcript was wiped is not live now.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=subagent_progress.d.ts.map

package/dist/ui/progress/subagent_progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent_progress.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/subagent_progress.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAC;IAC5D,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,SAAS,CAAC;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,qBAAa,gBAAgB;;IAwB3B,YAAY,IAAI,EAAE,oBAAoB,EAErC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAM3B;IAED,gDAAgD;IAChD,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAcjF;IAED,kEAAkE;IAClE,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAElC;IAED,4DAA4D;IAC5D,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAgBjD;IAED;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAGZ;CAqEF"}

package/dist/ui/progress/subagent_update.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ *
+ * **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
+ * 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 type { SubAgentUpdate } from "./subagent_panel.js";
+/** Narrow an `ag_ui.subagent` `CUSTOM` value, or `null` if it cannot be drawn. */
+export declare function subAgentUpdate(value: unknown): SubAgentUpdate | null;
+//# sourceMappingURL=subagent_update.d.ts.map

package/dist/ui/progress/subagent_update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent_update.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/subagent_update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAA+B,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA4CvF,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAiBpE"}

package/dist/ui/progress/thoughts_block.d.ts

@@ -0,0 +1,57 @@
+import { type UiStrings } from "../ui_strings.js";
+/**
+ * A muted "thinking" region for a reasoning model's streamed chain-of-thought.
+ *
+ * Sits at the top of the current answer group. Its header reads `thinking`
+ * while the model reasons, and {@link settle} stops the clock and names how
+ * long it took ("Thought for 4s"). {@link stream} replaces the body with the
+ * running buffer, which opens expanded and folds away on {@link collapse},
+ * once the answer's first text token arrives.
+ *
+ * The header is a disclosure only while there is text behind it. A provider
+ * that reasons without sending any -- redacted thinking, or reasoning with
+ * its summaries off -- still opens and closes a block, and a toggle there
+ * folded and unfolded an empty, ruled box. Until the buffer has text the
+ * header is a plain label and the body is not drawn; the first text turns the
+ * label into the toggle, and the body comes with it.
+ *
+ * Pure DOM. The host inserts {@link element}; all visible chrome text comes
+ * from {@link UiStrings}. The clock is injectable so the timing is testable.
+ */
+export declare class ThoughtsBlock {
+    #private;
+    /** The block's root element; insert this at the top of the answer group. */
+    readonly element: HTMLDivElement;
+    /**
+     * Build the block as reasoning starts, which is when its clock starts.
+     *
+     * @param strings - The resolved string table.
+     * @param now - The clock, in milliseconds; `performance.now` unless a test
+     *   supplies its own.
+     */
+    constructor(strings?: UiStrings, now?: () => number);
+    /**
+     * A further round of reasoning in the same turn, after a tool call settled
+     * the first: restart the clock and the live header. The rounds' times add
+     * up. Ignored while the clock is already running.
+     */
+    begin(): void;
+    /** Replace the reasoning body with the running buffer (the full text so far). */
+    stream(buffer: string): void;
+    /**
+     * Stop the clock and settle the header to how long the reasoning took.
+     *
+     * Called when reasoning ends, or by whatever arrives first in its place --
+     * the answer's text, a tool call, or the turn ending -- so the live label
+     * never outlives the reasoning. Idempotent: only the first call after a
+     * start counts.
+     */
+    settle(): void;
+    /**
+     * Fold the region away when the answer's first text token arrives, settling
+     * the header first. Idempotent, since the per-token text handler calls it
+     * repeatedly.
+     */
+    collapse(): void;
+}
+//# sourceMappingURL=thoughts_block.d.ts.map

package/dist/ui/progress/thoughts_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thoughts_block.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/thoughts_block.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAKtE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAa;;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAcjC;;;;;;OAMG;IACH,YACE,OAAO,GAAE,SAA8B,EACvC,GAAG,GAAE,MAAM,MAAgC,EAmC5C;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAOZ;IAED,iFAAiF;IACjF,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG3B;IAED;;;;;;;OAOG;IACH,MAAM,IAAI,IAAI,CAab;IAED;;;;OAIG;IACH,QAAQ,IAAI,IAAI,CAMf;CAuBF"}

package/dist/ui/progress/thoughts_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const THOUGHTS_STYLES: string;
+//# sourceMappingURL=thoughts_styles.d.ts.map

package/dist/ui/progress/thoughts_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thoughts_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/thoughts_styles.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,eAAe,EAAE,MAwE7B,CAAC"}

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

@@ -0,0 +1,167 @@
+import { TOOL_CALL_STATUS, type TOOL_DISPLAY } from "../../constants.js";
+import { type UiStrings } from "../ui_strings.js";
+/** Any state a tool-call card can be in. */
+export type ToolCallStatus = (typeof TOOL_CALL_STATUS)[keyof typeof TOOL_CALL_STATUS];
+/** How much detail a card renders. */
+export type ToolDisplayMode = (typeof TOOL_DISPLAY)[keyof typeof TOOL_DISPLAY];
+/** The two states a card can sit in before an outcome exists. */
+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.
+ *
+ * Construction renders a status icon, the tool name, a status pill, and a body
+ * of two separately-headed regions — arguments and result — each with its own
+ * `part`. {@link settle} fills in the result and flips the pill. Both payloads
+ * are pretty-printed and never concatenated into one block.
+ *
+ * The card renders one DOM shape in every display mode and lets CSS decide what
+ * shows, selecting visibility from the host attribute rather than a value
+ * copied onto the card at construction. That is what lets `data-tool-display`
+ * be flipped on the host and re-read by every card already on screen; building
+ * a different structure per mode would leave existing cards stale.
+ *
+ * The leading icon carries no text: the shadow CSS draws its glyph or spinner
+ * from the card's `data-status`, so a host themes it through the
+ * `--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}.
+ */
+export declare class ToolCallCard {
+    #private;
+    /** The card's root element; append this into the message list. */
+    readonly element: HTMLDivElement;
+    /**
+     * Where a question about *this* call renders — the approval prompt for a
+     * server-side tool the run deferred.
+     *
+     * It belongs to the card rather than to the transcript because a run can defer
+     * several calls at once, and a prompt written per *tool* ("Add this event to
+     * the board?") is identical for every one of them. Rendered into the answer
+     * group they were three anonymous copies of one question, below the three
+     * cards they gated; rendered here, position identifies them and the arguments
+     * are already on screen above the question.
+     *
+     * Empty until used, and hidden while empty by the shadow CSS.
+     */
+    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;
+    /**
+     * 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).
+     *
+     * Ignored once {@link settle} has run: a card that was declined must not be
+     * talked back into looking live by a late event.
+     */
+    mark(status: UnsettledStatus): void;
+    /**
+     * Say whether a prompt is open on this call, a question it asked or a
+     * confirmation it needs. A flag of its own beside the status, which stays
+     * `pending`: the call is still running as far as the status goes, and a card
+     * display mode that reads the status draws it exactly as before. The step
+     * group reads the flag to tell a call waiting on a person from one working.
+     */
+    setAsking(asking: boolean): void;
+    /**
+     * Record that a human approved or declined this call, as a line in the card.
+     * The prompt disappears once answered, so this is the only lasting trace that
+     * the call was gated at all.
+     */
+    recordDecision(kind: "approved" | "declined"): void;
+    /** Whether {@link settle} has already run (so a terminal sweep can skip it). */
+    get settled(): boolean;
+    /**
+     * Flip the status pill to `status` and fill in the result region, whose
+     * heading names the outcome (result / error / declined).
+     *
+     * A blank `text` leaves the region out, as the constructor does for empty
+     * arguments: the call settled with nothing to show, so the card stays a
+     * status row and its toggle is not offered. The formatter is not asked about
+     * a result that is not there.
+     */
+    settle(status: SettledStatus, text: string): void;
+}
+//# sourceMappingURL=tool_call_card.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool_call_card.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/tool_call_card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEtE,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;AAiCrE;;;;;;;;;;;;;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,EAmFlC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAKlC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAE/B;IAED;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAKlD;IAED,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAqBhD;CAiFF"}

package/dist/ui/progress/tool_group_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const TOOL_GROUP_STYLES: string;
+//# sourceMappingURL=tool_group_styles.d.ts.map

package/dist/ui/progress/tool_group_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool_group_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/tool_group_styles.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,iBAAiB,EAAE,MAqR/B,CAAC"}

package/dist/ui/progress/tool_step_group.d.ts

@@ -0,0 +1,50 @@
+import { type ToolGroupDisplayMode } from "../../constants.js";
+import type { UiStrings } from "../ui_strings.js";
+/**
+ * Consecutive tool calls folded into one quiet row, "Worked through 5 steps",
+ * with the per-call cards one click down. Built by the transcript for each run
+ * of calls when the element's `toolDisplay` is `grouped`.
+ *
+ * The group owns no state of its own beyond its nodes and two facts: each
+ * step's label, and whether it has already opened itself for the current wait.
+ * Everything else is read back off the cards each time one changes.
+ *
+ * It opens itself while a step waits on the user, because a deferred step
+ * carries its approval prompt inside its card and a folded group would hide
+ * the very question it is asking. Once per wait, so the user can fold it
+ * again. A running sub-agent does not open it: the row names the sub-agent
+ * instead, beside the running mark.
+ */
+export declare class ToolStepGroup {
+    #private;
+    readonly element: HTMLDivElement;
+    constructor(strings: UiStrings, display: () => ToolGroupDisplayMode);
+    /**
+     * Add a card's element as the group's next step, under the label the card
+     * was built with.
+     *
+     * A step whose label an earlier step already has gets a repeat ordinal,
+     * "Fill field (2)", in an element of its own beside the card's name. The
+     * name itself is never rewritten, so a group flattened back into per-call
+     * cards by a card display mode shows exactly the label the card was built
+     * with, and the CSS hides the ordinal there.
+     */
+    add(card: HTMLElement, name: string): void;
+    /** Show or hide the per-step cards. */
+    setOpen(open: boolean): void;
+    /**
+     * Open the group now, for the wait that is about to start.
+     *
+     * The group opens itself from its mutation observer, which runs a tick after
+     * the card is marked deferred. The approval prompt is drawn, and takes focus,
+     * in the same tick as the mark, while the list is still out of the layout: the
+     * focus is dropped and the scroll it would cause never happens. So the caller
+     * that is about to draw the prompt opens the group first, and this marks the
+     * wait as already answered for, so the observer's later refresh does not open
+     * it again over a user who folded it.
+     */
+    reveal(): void;
+    /** Redraw the row from the cards, for a change the cards do not announce. */
+    refresh(): void;
+}
+//# sourceMappingURL=tool_step_group.d.ts.map

package/dist/ui/progress/tool_step_group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool_step_group.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/tool_step_group.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAgElD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa;;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAYjC,YAAY,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,oBAAoB,EAiDlE;IAED;;;;;;;;;OASG;IACH,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAczC;IAED,uCAAuC;IACvC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAG3B;IAmBD;;;;;;;;;;OAUG;IACH,MAAM,IAAI,IAAI,CAGb;IAsBD,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CA+Ed;CACF"}

package/dist/ui/progress/tool_step_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const TOOL_STEP_STYLES: string;
+//# sourceMappingURL=tool_step_styles.d.ts.map

package/dist/ui/progress/tool_step_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool_step_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/progress/tool_step_styles.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,EAAE,MAke9B,CAAC"}

package/dist/ui/shell/adopt_styles.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Attach the stylesheet to `root` without an inline `<style>` element.
+ *
+ * A host with a strict `style-src` and no `'unsafe-inline'` drops an injected
+ * `<style>` silently: the component mounts, functions, and renders completely
+ * unstyled, with nothing in the console to point at. `adoptedStyleSheets`
+ * carries no inline-style origin, so it is unaffected by that policy.
+ *
+ * The sheet is constructed **per call**, which is once per mounted element,
+ * rather than shared at module scope. A shared sheet would additionally avoid
+ * re-parsing the stylesheet once per mounted element, which is what
+ * `adoptedStyleSheets` is usually reached for -- but a module-level singleton
+ * is exactly what this package forbids, and the CSP defect is fixed either way.
+ * Per instance is no worse than the `<style>` element it replaces, which also
+ * parsed once per mount.
+ *
+ * `extra` is the element's `extraStyles`, adopted after the built-in sheet so
+ * a host's rules win at equal specificity. They are constructed sheets too, so
+ * they inherit the same CSP immunity.
+ *
+ * No fallback: constructible `CSSStyleSheet` is Chrome 73, Firefox 101 and
+ * Safari 16.4, all below this package's browser floor (Chrome 123, Firefox
+ * 120, Safari 17.5). A guard here would be code no supported browser can
+ * reach, and the only way to keep it would be to exempt it from the coverage
+ * gate.
+ */
+export declare function adoptStyles(root: ShadowRoot, extra?: readonly CSSStyleSheet[]): CSSStyleSheet;
+//# sourceMappingURL=adopt_styles.d.ts.map

package/dist/ui/shell/adopt_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/adopt_styles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,GAAE,SAAS,aAAa,EAAO,GAAG,aAAa,CAKjG"}

package/dist/ui/shell/build_header.d.ts

@@ -0,0 +1,45 @@
+import type { UiStrings } from "../ui_strings.js";
+/** What {@link buildHeader} needs from the element that owns the header. */
+export interface HeaderOptions {
+    /** The element itself, asked whether a host slotted an icon. */
+    readonly host: HTMLElement;
+    /** The title node, kept by the element so a later `title-text` can update it. */
+    readonly title: HTMLElement;
+    readonly titleText: string;
+    readonly iconUrl: string | null;
+    readonly strings: UiStrings;
+    /** Whether the server indexes runs, so there is anything to continue. */
+    readonly withCheckpoints: boolean;
+    /** The opt-in theme toggle, or `null` when the host did not ask for one. */
+    readonly themeToggle: HTMLButtonElement | null;
+    readonly signal: AbortSignal;
+    readonly onHistory: () => void;
+    readonly onCheckpoints: () => void;
+    readonly onNewChat: () => void;
+    readonly onCollapse: () => void;
+    readonly onMaximize: () => void;
+    readonly onToggleTheme: () => void;
+}
+/** The header, and the one control the element still needs a handle on. */
+export interface BuiltHeader {
+    readonly header: HTMLElement;
+    /**
+     * The checkpoints button, built whether or not it is shown: the click-away
+     * handler for the checkpoints popover has to exclude it either way.
+     */
+    readonly checkpoints: HTMLButtonElement;
+    /** The maximize control, built detached: the element adds it where a placement offers it. */
+    readonly maximize: HTMLButtonElement;
+    /** The collapse control, which the maximize control is placed before. */
+    readonly collapse: HTMLButtonElement;
+}
+/**
+ * Build the panel's title bar: the optional icon, the title, the host's
+ * header-actions slot, and the controls.
+ *
+ * Every control calls back into the element's public methods, so a host
+ * chrome driving them imperatively takes exactly the path the built-in button
+ * takes.
+ */
+export declare function buildHeader(options: HeaderOptions): BuiltHeader;
+//# sourceMappingURL=build_header.d.ts.map

package/dist/ui/shell/build_header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_header.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/build_header.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIlD,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;CACpC;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAiE/D"}

package/dist/ui/shell/build_launcher.d.ts

@@ -0,0 +1,33 @@
+import type { UiStrings } from "../ui_strings.js";
+/** The launcher's parts, owned by the element, and what fills them. */
+export interface LauncherOptions {
+    readonly launcher: HTMLButtonElement;
+    readonly badge: HTMLElement;
+    readonly railLabel: HTMLElement;
+    /** The bottom bar's wrapper, which holds the launcher and the history button. */
+    readonly bar: HTMLElement;
+    /** The bottom bar's history button, a sibling of the launcher in the bar. */
+    readonly barHistory: HTMLButtonElement;
+    /** The place beside the title, which its owner shows and hides. */
+    readonly barPlace: HTMLElement;
+    readonly titleText: string;
+    readonly iconUrl: string | null;
+    readonly strings: UiStrings;
+    readonly signal: AbortSignal;
+    readonly onOpen: () => void;
+    readonly onHistory: () => void;
+}
+/**
+ * Build what a collapsed widget shrinks to: a round floating button, the slim
+ * edge rail under `placement="sidebar"`, or the strip along the bottom edge
+ * under `collapse-to="bar"` -- one element, shaped by the stylesheet. The
+ * element mounts the bar wrapper as a sibling of the panel, so it survives the
+ * panel being hidden.
+ *
+ * The wrapper is there for the bar's history button: a button cannot nest in
+ * a button, so the strip is the launcher and the history button side by side.
+ * Outside the bar the wrapper draws no box and the history button is not
+ * drawn, so the launcher lays out against the host exactly as it did alone.
+ */
+export declare function buildLauncher(options: LauncherOptions): void;
+//# sourceMappingURL=build_launcher.d.ts.map

package/dist/ui/shell/build_launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_launcher.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/build_launcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CA2C5D"}

package/dist/ui/shell/collapse_glyph.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The collapse control's mark for the element's `data-collapse-icon`,
+ * `placement` and `data-side`, read live by the caller.
+ *
+ * Unset, or a value it does not name, follows the placement: a docked column
+ * (`sidebar`, and the undocumented `side`) hides sideways into its edge, so it
+ * takes the panel mark, and everything else -- the corners, `full`,
+ * `embedded`, an unknown placement -- keeps the chevron down. The panel mark
+ * points into the edge the panel docks to, so it is mirrored for either docked
+ * placement on `data-side="left"`, whether it was chosen or defaulted. The
+ * chevrons are absolute.
+ */
+export declare function collapseGlyph(choice: string | null, placement: string | null, side: string | null): string;
+//# sourceMappingURL=collapse_glyph.d.ts.map

package/dist/ui/shell/collapse_glyph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collapse_glyph.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/collapse_glyph.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,MAAM,CAgBR"}

package/dist/ui/shell/frame_styles.d.ts

@@ -0,0 +1,2 @@
+export declare const FRAME_STYLES: string;
+//# sourceMappingURL=frame_styles.d.ts.map

package/dist/ui/shell/frame_styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame_styles.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/frame_styles.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,EAAE,MAiJ1B,CAAC"}

package/dist/ui/shell/glyph_slot.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A `<slot>` a host can project its own mark into, falling back to one of the
+ * built-in glyphs. The markup is an author-written constant, never user or
+ * server data, so it is assigned directly rather than sanitised.
+ */
+export declare function glyphSlot(slotName: string, className: string, markup: string): HTMLSlotElement;
+//# sourceMappingURL=glyph_slot.d.ts.map

package/dist/ui/shell/glyph_slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyph_slot.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/glyph_slot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAM9F"}

package/dist/ui/shell/header_button.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Build a header control button: a named slot a host can project markup into,
+ * with the built-in glyph (static SVG markup from `constants.ts`) as the slot's
+ * fallback.
+ *
+ * The slot is what lets a host replace the mark with its own `<img>` or
+ * `<svg>` rather than only restyle it through the `part`; the same
+ * slot-with-fallback idiom the header icon uses.
+ */
+export declare function headerButton(modifier: string, label: string, glyph: string): HTMLButtonElement;
+//# sourceMappingURL=header_button.d.ts.map

package/dist/ui/shell/header_button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header_button.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/header_button.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAY9F"}

package/dist/ui/shell/icon_element.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An icon holder wrapping a `<slot>` so a host can project custom markup;
+ * with an `<img>` as the slot's fallback when an icon URL is configured, or
+ * the given glyph markup when it is not.
+ *
+ * `iconUrl` is the caller's to read rather than defaulted here, because the
+ * three marks answer it differently: the header's is `data-icon-url`, the
+ * launcher's falls back to it from an attribute of its own, and the theme
+ * toggle never takes an image at all.
+ */
+export declare function iconElement(slotName: string, part: string, fallbackGlyph: string | null, iconUrl: string | null): HTMLSpanElement;
+//# sourceMappingURL=icon_element.d.ts.map

package/dist/ui/shell/icon_element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon_element.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/icon_element.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,eAAe,CAiBjB"}

package/dist/ui/shell/is_unread_badge_enabled.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether the launcher's unread badge is shown.
+ *
+ * The unread badge, unlike every other affordance here, is on by default:
+ * a collapsed widget is the one state where an answer can arrive with nothing
+ * on screen to say so. `data-unread-badge="false"` turns it off for a host
+ * that drives its own chrome from the `ag-ui-unread` event.
+ */
+export declare function isUnreadBadgeEnabled(element: Element): boolean;
+//# sourceMappingURL=is_unread_badge_enabled.d.ts.map

package/dist/ui/shell/is_unread_badge_enabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is_unread_badge_enabled.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/is_unread_badge_enabled.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE9D"}

package/dist/ui/shell/read_launcher_icon_url.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The launcher's own image URL. `data-launcher-icon-url` lets the collapsed
+ * button carry a different mark from the header's — a product logo reads at
+ * 22px in a header bar but rarely at 26px in a circle — and falls back to the
+ * header icon so a single `data-icon-url` still feeds both.
+ */
+export declare function readLauncherIconUrl(element: Element): string | null;
+//# sourceMappingURL=read_launcher_icon_url.d.ts.map

package/dist/ui/shell/read_launcher_icon_url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_launcher_icon_url.d.ts","sourceRoot":"","sources":["../../../src/ui/shell/read_launcher_icon_url.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEnE"}