@runtypelabs/persona 3.16.0 → 3.18.0

package/dist/index.d.ts

@@ -91,6 +91,61 @@ interface AgentWidgetPlugin {
         defaultRenderer: () => HTMLElement;
         config: AgentWidgetConfig;
     }) => HTMLElement | null;
+    /**
+     * Custom renderer for `ask_user_question` tool calls.
+     *
+     * When a plugin returns an `HTMLElement`, it is inserted into the transcript
+     * in place of the default (which is no transcript bubble — the built-in
+     * renders a sheet over the composer). The built-in composer-overlay sheet
+     * is suppressed so the plugin's UI fully owns the interaction.
+     *
+     * Return `null` to fall through to the built-in overlay sheet.
+     *
+     * The context gives you a pre-parsed `payload` (may be partial while the
+     * tool call is still streaming — check `complete`) and two callbacks:
+     * `resolve(answer)` resumes the paused LOCAL tool with the user's answer,
+     * and `dismiss()` cancels with the sentinel `"(dismissed)"`.
+     *
+     * @example
+     * ```typescript
+     * renderAskUserQuestion: ({ payload, resolve, dismiss }) => {
+     *   const prompt = payload.questions?.[0];
+     *   if (!prompt) return null;
+     *   const root = document.createElement("div");
+     *   root.textContent = prompt.question ?? "";
+     *   (prompt.options ?? []).forEach((option) => {
+     *     const btn = document.createElement("button");
+     *     btn.textContent = option.label;
+     *     btn.addEventListener("click", () => resolve(option.label));
+     *     root.appendChild(btn);
+     *   });
+     *   return root;
+     * }
+     * ```
+     */
+    renderAskUserQuestion?: (context: {
+        message: AgentWidgetMessage;
+        /**
+         * Parsed `{ questions: [...] }` payload. May be partial while the tool
+         * call is still streaming; see `complete`. `null` when no payload has
+         * arrived yet.
+         */
+        payload: Partial<AskUserQuestionPayload> | null;
+        /** `true` once the tool-call args have fully streamed in. */
+        complete: boolean;
+        /**
+         * Resume the paused LOCAL tool with the user's answer. Posts to the
+         * resume endpoint, pipes the SSE stream back into the session, and
+         * appends a user-visible answer bubble to the transcript.
+         */
+        resolve: (answer: string) => void;
+        /**
+         * Cancel the question. Resumes with the sentinel `"(dismissed)"` so the
+         * server doesn't sit in `waiting_for_local` forever. Idempotent.
+         */
+        dismiss: () => void;
+        config: AgentWidgetConfig;
+    }) => HTMLElement | null;
     /**
      * Custom renderer for approval bubbles
      * Return null to use default renderer
@@ -384,6 +439,18 @@ interface MessageTokens {
     /** Border color between messages in the thread. */
     border?: TokenReference<'color'>;
 }
+/**
+ * Welcome / intro card rendered above the message list when no messages exist.
+ * Set `copy.showWelcomeCard: false` to hide it; use `layout.slots["body-top"]`
+ * to replace it wholesale.
+ */
+interface IntroCardTokens extends ComponentTokenSet {
+    background?: TokenReference<'color'>;
+    borderRadius?: TokenReference<'radius'>;
+    padding?: TokenReference<'spacing'>;
+    /** Box-shadow on the intro card (token ref or raw CSS, e.g. `none`). */
+    shadow?: string;
+}
 /** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
 interface CollapsibleWidgetTokens {
     /** Background for content areas. */
@@ -581,6 +648,8 @@ interface ComponentTokens {
     panel: PanelTokens;
     header: HeaderTokens;
     message: MessageTokens;
+    /** Welcome / intro card shown above the message list. */
+    introCard?: IntroCardTokens;
     /** Markdown surfaces (chat + artifact pane). */
     markdown?: MarkdownTokens;
     voice: VoiceTokens;
@@ -829,6 +898,31 @@ type AgentMessageMetadata = {
      * or `prompt` step inside the nested flow). Stable key for that step.
      */
     parentStepId?: string;
+    /**
+     * Set to `true` on a tool-variant message produced from a `step_await`
+     * event (`awaitReason: "local_tool_required"`). Signals to UI code that
+     * the tool call is a LOCAL tool and the server is paused waiting for a
+     * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
+     */
+    awaitingLocalTool?: boolean;
+    /**
+     * Set to `true` once the user has picked / typed / dismissed an answer for
+     * an `ask_user_question` tool call, so renderers stop re-mounting the
+     * answer-pill sheet for this tool call on subsequent render passes.
+     */
+    askUserQuestionAnswered?: boolean;
+    /**
+     * In-progress answers for a multi-question `ask_user_question` payload,
+     * keyed by question text. Persisted across refresh so the user lands back
+     * where they were if the page reloads mid-flow. Cleared once
+     * `askUserQuestionAnswered` flips to `true`.
+     */
+    askUserQuestionAnswers?: Record<string, string | string[]>;
+    /**
+     * Current page index for a multi-question `ask_user_question` payload's
+     * paginated stepper. Persists alongside `askUserQuestionAnswers`.
+     */
+    askUserQuestionIndex?: number;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -876,6 +970,8 @@ type AgentWidgetActionHandler = (action: AgentWidgetParsedAction, context: Agent
 type AgentWidgetStoredState = {
     messages?: AgentWidgetMessage[];
     metadata?: Record<string, unknown>;
+    artifacts?: PersonaArtifactRecord[];
+    selectedArtifactId?: string | null;
 };
 interface AgentWidgetStorageAdapter {
     load?: () => AgentWidgetStoredState | null | Promise<AgentWidgetStoredState | null>;
@@ -1272,6 +1368,151 @@ type AgentWidgetReasoningDisplayFeature = {
      */
     loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
+/**
+ * Reveal animation applied to assistant message text while it is streaming.
+ *
+ * Built-in types always available:
+ * - `none` — text appears as tokens arrive (default).
+ * - `typewriter` — characters fade in with a blinking caret.
+ * - `pop-bubble` — the bubble scales in; text streams normally afterward.
+ * - `letter-rise` — per-char translateY + fade reveal.
+ * - `word-fade` — per-word blur + translateY fade-in.
+ *
+ * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
+ * - `wipe`, `glyph-cycle`.
+ *
+ * Custom types are allowed — register a plugin with any string name and
+ * reference it by that name in `type`.
+ */
+type AgentWidgetStreamAnimationBuiltinType = "none" | "typewriter" | "word-fade" | "letter-rise" | "glyph-cycle" | "wipe" | "pop-bubble";
+type AgentWidgetStreamAnimationType = AgentWidgetStreamAnimationBuiltinType | (string & {});
+/**
+ * Placeholder shown inside a streaming assistant bubble before the first token arrives.
+ * - `none` — use the default typing-dots indicator (existing behavior).
+ * - `skeleton` — shimmer bars, replaced by streaming content once it starts.
+ */
+type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
+/**
+ * How much of the accumulated streaming content to display while tokens are
+ * still arriving. Trimming to a boundary means in-progress words or lines
+ * stay hidden until they complete — useful for animations that benefit from
+ * unit-complete reveals (e.g. wipe, glyph-cycle).
+ * - `none` — show every character as it arrives (default).
+ * - `word` — trim to the last whitespace boundary.
+ * - `line` — trim to the last newline boundary.
+ */
+type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
+/**
+ * Context passed to plugin lifecycle hooks. Carries the live DOM references
+ * and resolved animation settings for the currently-streaming message.
+ */
+type StreamAnimationContext = {
+    /** The `.persona-message-content` element owning the streamed text. */
+    container: HTMLElement;
+    /** The outer message bubble element. */
+    bubble: HTMLElement;
+    /** ID of the streaming message. */
+    messageId: string;
+    /** Read-only reference to the message being streamed. */
+    message: AgentWidgetMessage;
+    /** Effective `speed` from `streamAnimation.speed`. */
+    speed: number;
+    /** Effective `duration` from `streamAnimation.duration`. */
+    duration: number;
+};
+/**
+ * Pluggable stream animation. Third-party packages and inline registrations
+ * implement this interface to add custom reveal effects.
+ *
+ * Lifecycle:
+ * - When the widget mounts and detects a plugin (either passed via config or
+ *   auto-registered in the IIFE bundle), it injects `styles` once into the
+ *   widget's style host.
+ * - For each streaming assistant message whose `type` matches `name`, the
+ *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
+ *   and — if `useCaret` is true — appends a blinking caret.
+ * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
+ *   and `data-preserve-animation` to safely mutate per-char or per-word spans
+ *   without idiomorph clobbering in-flight work.
+ */
+type StreamAnimationPlugin = {
+    /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
+    name: string;
+    /** Class added to `.persona-message-content` while streaming. */
+    containerClass?: string;
+    /** Class added to the bubble element (e.g. a one-shot scale animation). */
+    bubbleClass?: string;
+    /** Wrap mode applied to text nodes during streaming. @default "none" */
+    wrap?: "none" | "char" | "word";
+    /**
+     * HTML tags whose descendant text is skipped during wrapping. Defaults to
+     * `["pre", "code", "a", "script", "style"]` — useful for keeping code
+     * blocks legible and link click-targets intact. Plugins that want to
+     * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
+     * the list.
+     */
+    skipTags?: string[];
+    /** Append a blinking caret after the last rendered char/word. */
+    useCaret?: boolean;
+    /** CSS string injected into the widget style host on first activation. */
+    styles?: string;
+    /**
+     * Optional custom buffering strategy. Returns the portion of `content`
+     * that should be rendered during streaming. Use this for buffering
+     * schemes beyond the built-in `word` / `line` strategies.
+     */
+    bufferContent?: (content: string, message: AgentWidgetMessage) => string;
+    /**
+     * Fires once when the plugin is first activated inside a widget instance.
+     * Use this to set up MutationObservers or other long-lived listeners.
+     * Return an optional cleanup function that runs on widget destroy.
+     */
+    onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
+    /** Fires after each render that reaches the live DOM. */
+    onAfterRender?: (ctx: StreamAnimationContext) => void;
+    /** Fires when a streamed message's `streaming` flag flips to false. */
+    onStreamComplete?: (ctx: StreamAnimationContext) => void;
+    /**
+     * Report whether the plugin still has in-flight animation work for a
+     * message. When `true`, the widget keeps rendering the message in its
+     * "streaming-animated" mode even after `message.streaming` flips false —
+     * preventing the final non-animated render from yanking the rug out from
+     * under unfinished per-char cycles or reveals.
+     */
+    isAnimating?: (message: AgentWidgetMessage) => boolean;
+};
+type AgentWidgetStreamAnimationFeature = {
+    /** Reveal animation to apply while streaming. @default "none" */
+    type?: AgentWidgetStreamAnimationType;
+    /** Pre-first-token placeholder. @default "none" */
+    placeholder?: AgentWidgetStreamAnimationPlaceholder;
+    /**
+     * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
+     * and per-unit plugin animations. Each arriving character/word animates from
+     * invisible to visible over this duration, independent of its position — the
+     * streaming cadence itself provides the visible stagger.
+     * @default 120
+     */
+    speed?: number;
+    /**
+     * Total duration of container-level animations (`pop-bubble` and custom
+     * plugin animations), in milliseconds.
+     * @default 1800
+     */
+    duration?: number;
+    /**
+     * Trim the accumulated streaming content to a word or line boundary before
+     * rendering. Hides in-progress units until they complete.
+     * @default "none"
+     */
+    buffer?: AgentWidgetStreamAnimationBuffer;
+    /**
+     * Extra animation plugins available to this widget instance. Keys are
+     * plugin names; the matching plugin activates when `type` is set to that
+     * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
+     */
+    plugins?: Record<string, StreamAnimationPlugin>;
+};
 type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
     showToolCalls?: boolean;
@@ -1286,6 +1527,115 @@ type AgentWidgetFeatureFlags = {
     eventStream?: EventStreamConfig;
     /** Optional artifact sidebar (split pane / mobile drawer) */
     artifacts?: AgentWidgetArtifactsFeature;
+    /** Reveal animation for streaming assistant text. */
+    streamAnimation?: AgentWidgetStreamAnimationFeature;
+    /**
+     * Built-in interactive answer-pill sheet shown when the assistant invokes
+     * the `ask_user_question` tool. Slides up over the composer with tappable
+     * pills + optional free-text input.
+     */
+    askUserQuestion?: AgentWidgetAskUserQuestionFeature;
+};
+/**
+ * Single selectable option in an `ask_user_question` prompt.
+ * Mirrors Anthropic's AskUserQuestion schema.
+ */
+type AskUserQuestionOption = {
+    /** Pill label (required). */
+    label: string;
+    /** Optional long-form description (shown as a subtitle on tap-hover). */
+    description?: string;
+    /** Optional rich preview — reserved for future rendering; ignored in v1. */
+    preview?: string;
+};
+/**
+ * A single question in an `ask_user_question` tool call.
+ * The tool may carry 1–8 prompts. When more than one is supplied, the built-in
+ * renderer paginates them as a "Question N of M" stepper with Back / Next /
+ * Submit-all controls; single-question payloads render without stepper chrome.
+ */
+type AskUserQuestionPrompt = {
+    /** The question text shown to the user. */
+    question: string;
+    /** Optional short header label (≤12 chars) used as a compact group title. */
+    header?: string;
+    /** 2–4 selectable options. */
+    options: AskUserQuestionOption[];
+    /** When true, the user can pick multiple options and submit together. Default false. */
+    multiSelect?: boolean;
+    /** When true, a free-text "Other…" pill expands to an input. Default true. */
+    allowFreeText?: boolean;
+};
+/** Parsed payload of an `ask_user_question` tool call. */
+type AskUserQuestionPayload = {
+    /** 1–8 questions. Anything beyond the renderer's cap is truncated with a console warning. */
+    questions: AskUserQuestionPrompt[];
+};
+/**
+ * Style overrides for the answer-pill sheet. All values are raw CSS strings
+ * and are plumbed through as CSS custom properties on the sheet root.
+ */
+type AgentWidgetAskUserQuestionStyles = {
+    sheetBackground?: string;
+    sheetBorder?: string;
+    sheetShadow?: string;
+    pillBackground?: string;
+    pillBackgroundSelected?: string;
+    pillTextColor?: string;
+    pillTextColorSelected?: string;
+    pillBorderRadius?: string;
+    customInputBackground?: string;
+};
+/**
+ * Feature config for the built-in `ask_user_question` answer-pill sheet.
+ * When a tool call with the name `ask_user_question` arrives, the widget
+ * renders an interactive sheet over the composer in place of the generic
+ * tool bubble.
+ */
+type AgentWidgetAskUserQuestionFeature = {
+    /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
+    enabled?: boolean;
+    /** Slide-in animation duration in ms. Defaults to 180. */
+    slideInMs?: number;
+    /** Label for the free-text pill. Defaults to "Other…". */
+    freeTextLabel?: string;
+    /** Placeholder text in the free-text input. Defaults to "Type your answer…". */
+    freeTextPlaceholder?: string;
+    /** Button label for submitting multi-select / free-text answers. Defaults to "Send". */
+    submitLabel?: string;
+    /** Button label advancing to the next question in grouped (paginated) payloads. Defaults to "Next". */
+    nextLabel?: string;
+    /** Button label moving back to the previous question in grouped payloads. Defaults to "Back". */
+    backLabel?: string;
+    /** Button label submitting all answers from the final page of a grouped payload. Defaults to "Submit all". */
+    submitAllLabel?: string;
+    /**
+     * In grouped (multi-question) mode, auto-advance to the next page after a
+     * single-select pill pick or free-text submit on intermediate pages.
+     * Defaults to `true`. The final page never auto-submits — users always
+     * confirm with an explicit "Submit all" click. Multi-select pages always
+     * require an explicit Next regardless of this setting.
+     */
+    groupedAutoAdvance?: boolean;
+    /**
+     * Visual layout for the option list.
+     * - `"rows"` (default) — full-width stacked rows with always-visible
+     *   descriptions, right-edge number badges (single-select) or checkboxes
+     *   (multi-select), and an always-visible inline "Other" input.
+     * - `"pills"` — legacy compact pill list with horizontal wrap; description
+     *   surfaces as a tooltip and the "Other…" pill expands on click.
+     */
+    layout?: "rows" | "pills";
+    /**
+     * Button label for skipping the current question in grouped payloads.
+     * Defaults to "Skip". On intermediate pages Skip advances without recording
+     * an answer; on the final page Skip submits the partial answer record
+     * (skipped questions absent from the resolved object). For single-question
+     * payloads Skip behaves like dismiss.
+     */
+    skipLabel?: string;
+    /** Style overrides for the sheet and pills. */
+    styles?: AgentWidgetAskUserQuestionStyles;
 };
 type SSEEventRecord = {
     id: string;
@@ -1574,6 +1924,10 @@ type AgentWidgetSendButtonConfig = {
     backgroundColor?: string;
     textColor?: string;
     size?: string;
+    /** Lucide icon name shown while a response is streaming. Clicking the button in this state aborts the stream. Default: "square". */
+    stopIconName?: string;
+    /** Tooltip text shown while streaming. Default: "Stop generating". */
+    stopTooltipText?: string;
 };
 /** Optional composer UI state for custom `renderComposer` implementations. */
 type AgentWidgetComposerConfig = {
@@ -3089,11 +3443,21 @@ type AgentWidgetConfig = {
         welcomeSubtitle?: string;
         inputPlaceholder?: string;
         sendButtonLabel?: string;
+        /** Button label shown in text mode while a response is streaming. Default: "Stop". */
+        stopButtonLabel?: string;
         /**
          * When false, the welcome / intro card is not shown above the message list.
          * @default true
          */
         showWelcomeCard?: boolean;
+        /**
+         * Per-stop-reason copy for the inline notice rendered on assistant
+         * bubbles when the runtime reports a non-natural stop (e.g. the agent
+         * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
+         * optional — keys you omit fall back to the built-in defaults. Set a
+         * key to an empty string to suppress the notice for that reason.
+         */
+        stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
     };
     /**
      * Semantic design tokens (`palette`, `semantic`, `components`).
@@ -3127,6 +3491,17 @@ type AgentWidgetConfig = {
     autoFocusInput?: boolean;
     launcher?: AgentWidgetLauncherConfig;
     initialMessages?: AgentWidgetMessage[];
+    /**
+     * Artifacts to hydrate into the pane at init. Typically populated from
+     * `storageAdapter.load()` alongside `initialMessages` so the artifact pane
+     * survives a page refresh.
+     */
+    initialArtifacts?: PersonaArtifactRecord[];
+    /**
+     * Which artifact id (if any) should be selected in the pane at init. Paired
+     * with `initialArtifacts`.
+     */
+    initialSelectedArtifactId?: string | null;
     suggestionChips?: string[];
     suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
     debug?: boolean;
@@ -3591,6 +3966,21 @@ type AgentWidgetApproval = {
     resolvedAt?: number;
 };
 type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
+/**
+ * Per-turn / per-step stop reason emitted by the runtime on
+ * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
+ * owned by the upstream Runtype API — do not extend without coordination.
+ *
+ * - `end_turn` — natural completion (no affordance needed)
+ * - `max_tool_calls` — agent loop tripped the configured tool-call ceiling
+ * - `length` — provider hit max output tokens
+ * - `content_filter` — provider content filter intervened
+ * - `error` — provider/runtime error (prefer existing error rendering)
+ * - `unknown` — explicitly reported but uninformative
+ *
+ * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
+ */
+type StopReasonKind = 'end_turn' | 'max_tool_calls' | 'length' | 'content_filter' | 'error' | 'unknown';
 /**
  * Represents a message in the chat conversation.
  *
@@ -3677,6 +4067,17 @@ type AgentWidgetMessage = {
      * Contains execution context like iteration number and turn ID.
      */
     agentMetadata?: AgentMessageMetadata;
+    /**
+     * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+     * (agent-loop path) or the last `step_complete` for a prompt step
+     * (dispatch / flow path). Absent when the API did not report a value.
+     *
+     * When set to a non-natural value (`max_tool_calls`, `length`,
+     * `content_filter`, `error`), the widget renders an inline notice on
+     * the assistant bubble. See `config.copy.stopReasonNotice` to override
+     * the default copy.
+     */
+    stopReason?: StopReasonKind;
 };
 /**
  * Options for injecting a message into the conversation.
@@ -3970,6 +4371,22 @@ declare class AgentWidgetClient {
         executionId: string;
         approvalId: string;
     }, decision: 'approved' | 'denied'): Promise<Response>;
+    /**
+     * Resume a paused flow execution by supplying outputs for LOCAL
+     * (client-executed) tools. Used by the built-in `ask_user_question`
+     * answer-pill sheet, but generic enough for any LOCAL tool.
+     *
+     * Posts to the upstream `/resume` endpoint (the dispatch URL with
+     * `/dispatch` replaced by `/resume` — works for both direct-to-Runtype
+     * and the persona proxy) and returns the raw Response so the caller can
+     * pipe its SSE body through `connectStream()`.
+     *
+     * @param executionId - The paused execution id carried on `step_await`.
+     * @param toolOutputs - Map keyed by tool name → the tool's result value.
+     */
+    resumeFlow(executionId: string, toolOutputs: Record<string, unknown>, options?: {
+        streamResponse?: boolean;
+    }): Promise<Response>;
     private buildAgentPayload;
     private buildPayload;
     /**
@@ -4232,6 +4649,37 @@ declare class AgentWidgetSession {
      * and pipes the response stream through connectStream().
      */
     resolveApproval(approval: AgentWidgetApproval, decision: 'approved' | 'denied'): Promise<void>;
+    /**
+     * Resolve a paused `ask_user_question` LOCAL tool call.
+     *
+     * When the server emits `step_await` for `ask_user_question`, the widget
+     * renders the answer-pill sheet and calls this method once the user
+     * picks. Steps:
+     *   1. POST the answer to `/resume` via `client.resumeFlow`.
+     *   2. Pipe the resulting SSE stream through `connectStream()` so the
+     *      paused agent execution continues.
+     *   3. Append a user-visible bubble with the answer text so the
+     *      transcript reads naturally.
+     */
+    /**
+     * Persist in-progress answers and the current page index for a multi-question
+     * `ask_user_question` payload, so a refresh resumes on the same page with
+     * prior answers intact. Called by ui.ts on every Back/Next/pick interaction.
+     */
+    persistAskUserQuestionProgress(toolMessage: AgentWidgetMessage, progress: {
+        answers: Record<string, string | string[]>;
+        currentIndex: number;
+    }): void;
+    /**
+     * Flip an `ask_user_question` tool message from awaiting → answered so
+     * render passes stop re-mounting its answer-pill sheet. Idempotent.
+     * When `answers` is provided, persists the full structured answer Record
+     * atomically with the answered flag — guarding against later events that
+     * could re-emit the tool message and clobber the per-pick persisted
+     * answers via top-level merge.
+     */
+    markAskUserQuestionResolved(toolMessage: AgentWidgetMessage, answers?: Record<string, string | string[]>): void;
+    resolveAskUserQuestion(toolMessage: AgentWidgetMessage, answer: string | Record<string, string | string[]>): Promise<void>;
     cancel(): void;
     clearMessages(): void;
     getArtifacts(): PersonaArtifactRecord[];
@@ -4244,6 +4692,7 @@ declare class AgentWidgetSession {
     private emitArtifactsState;
     private applyArtifactStreamEvent;
     hydrateMessages(messages: AgentWidgetMessage[]): void;
+    hydrateArtifacts(artifacts: PersonaArtifactRecord[], selectedId?: string | null): void;
     private handleEvent;
     private setStatus;
     private setStreaming;
@@ -4405,6 +4854,10 @@ type Controller = {
     upsertArtifact: (manual: PersonaArtifactManualUpsert) => PersonaArtifactRecord | null;
     selectArtifact: (id: string) => void;
     clearArtifacts: () => void;
+    /** Read current artifacts (useful on init to rebuild host-side tab state after hydration). */
+    getArtifacts: () => PersonaArtifactRecord[];
+    /** Read the currently selected artifact id (paired with `getArtifacts`). */
+    getSelectedArtifactId: () => string | null;
     /**
      * Focus the chat input. Returns true if focus succeeded, false if panel is closed
      * (launcher mode) or textarea is unavailable.
@@ -4427,6 +4880,39 @@ type AgentWidgetInitHandle = AgentWidgetController & {
 };
 declare const initAgentWidget: (options: AgentWidgetInitOptions) => AgentWidgetInitHandle;
 
+declare const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
+declare const isAskUserQuestionMessage: (message: AgentWidgetMessage) => boolean;
+/**
+ * Parse an `ask_user_question` tool-variant message into a partial payload.
+ * Safe to call mid-stream — will walk the tool call's `chunks` via
+ * `partial-json` and return `{ payload: null, complete: false }` when there
+ * isn't enough data yet. `complete` flips to `true` once the tool call
+ * reports status `"complete"`.
+ *
+ * Exported for plugin authors implementing `renderAskUserQuestion`.
+ */
+declare const parseAskUserQuestionPayload: (message: AgentWidgetMessage) => {
+    payload: Partial<AskUserQuestionPayload> | null;
+    complete: boolean;
+};
+/**
+ * Create the small in-transcript stub for an `ask_user_question` tool call.
+ * The stub is passive — the interactive sheet is mounted separately into
+ * the composer overlay via `ensureAskUserQuestionSheet`.
+ */
+declare const createAskUserQuestionBubble: (message: AgentWidgetMessage, config?: AgentWidgetConfig) => HTMLElement;
+/**
+ * Mount or update the interactive answer-pill sheet for a given message.
+ * Idempotent — if a sheet already exists for the tool-call id, it is hydrated
+ * in-place instead of remounted, so streaming updates don't flicker.
+ */
+declare const ensureAskUserQuestionSheet: (message: AgentWidgetMessage, config: AgentWidgetConfig | undefined, overlay: HTMLElement | null | undefined) => void;
+/**
+ * Remove the sheet for a specific tool-call id, or all sheets if omitted.
+ * Runs a slide-out transition before removing.
+ */
+declare const removeAskUserQuestionSheet: (overlay: HTMLElement | null | undefined, toolCallId?: string) => void;
+
 type WidgetHostLayoutMode = "direct" | "docked";
 type WidgetHostLayout = {
     mode: WidgetHostLayoutMode;
@@ -5075,6 +5561,16 @@ declare class PluginRegistry {
 }
 declare const pluginRegistry: PluginRegistry;
 
+/**
+ * Register a custom stream animation plugin globally. Subsequent widget
+ * instances can reference the plugin by `name` in `features.streamAnimation.type`.
+ * Per-widget plugin overrides via `features.streamAnimation.plugins` take
+ * precedence over the global registry.
+ */
+declare const registerStreamAnimationPlugin: (plugin: StreamAnimationPlugin) => void;
+declare const unregisterStreamAnimationPlugin: (name: string) => void;
+declare const listRegisteredStreamAnimations: () => string[];
+
 interface DropdownMenuItem {
     id: string;
     label: string;
@@ -5833,6 +6329,13 @@ interface ComposerElements {
     actionsRow: HTMLElement;
     leftActions: HTMLElement;
     rightActions: HTMLElement;
+    /**
+     * Swap the send button between its idle ("send") appearance and its
+     * streaming ("stop") appearance. In icon mode this swaps the SVG; in text
+     * mode it swaps the button label. Tooltip text is updated when a tooltip
+     * element is present.
+     */
+    setSendButtonMode: (mode: "send" | "stop") => void;
 }
 interface ComposerBuildContext {
     config?: AgentWidgetConfig;
@@ -5880,4 +6383,4 @@ declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
 declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
 declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
 
-export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComboButtonHandle, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateComboButtonOptions, type CreateDropdownOptions, type CreateIconButtonOptions, type CreateLabelButtonOptions, type CreateStandardBubbleOptions, type CreateThemeOptions, type CreateToggleGroupOptions, DEFAULT_COMPONENTS, DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH, DEFAULT_FLOATING_LAUNCHER_WIDTH, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DemoCarouselHandle, type DemoCarouselItem, type DemoCarouselOptions, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LabelButtonTokens, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDemoCarousel, createDirectivePostprocessor, createDropdownMenu, createFlexibleJsonStreamParser, createIconButton, createImagePart, createJsonStreamParser, createLabelButton, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createToggleGroup, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, markdownPostprocessor, mergeWithDefaults, normalizeContent, pluginRegistry, reducedMotionPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, validateImageFile, validateTheme };
+export { ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, type AskUserQuestionOption, type AskUserQuestionPayload, type AskUserQuestionPrompt, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComboButtonHandle, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateComboButtonOptions, type CreateDropdownOptions, type CreateIconButtonOptions, type CreateLabelButtonOptions, type CreateStandardBubbleOptions, type CreateThemeOptions, type CreateToggleGroupOptions, DEFAULT_COMPONENTS, DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH, DEFAULT_FLOATING_LAUNCHER_WIDTH, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DemoCarouselHandle, type DemoCarouselItem, type DemoCarouselOptions, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LabelButtonTokens, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type StreamAnimationContext, type StreamAnimationPlugin, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createAskUserQuestionBubble, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDemoCarousel, createDirectivePostprocessor, createDropdownMenu, createFlexibleJsonStreamParser, createIconButton, createImagePart, createJsonStreamParser, createLabelButton, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createToggleGroup, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, ensureAskUserQuestionSheet, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isAskUserQuestionMessage, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };