@runtypelabs/persona 4.23.1 → 4.24.0

package/dist/forms-ui.d.cts

@@ -21,6 +21,7 @@ interface ResolvedWelcomeConfig {
      * Optional on the interface, always populated by `resolveWelcomeConfig`:
      * a plugin literal built against an older minor must still type-check.
      */
+    layout?: "top" | "centered";
     anchor?: AgentWidgetWelcomeAnchor;
     /** Percentage string; validated, falls back to "44%". */
     anchorComposerTop?: string;
@@ -792,6 +793,8 @@ interface InputTokens extends ComponentTokenSet {
     backdropFilter?: string;
 }
 interface LauncherTokens extends ComponentTokenSet {
+    /** Distance from the viewport edges. Circle default: 20px; pill: 24px. */
+    offset?: string;
     size: string;
     iconSize: string;
     shadow: TokenReference<'shadow'>;
@@ -814,6 +817,15 @@ interface PanelTokens extends ComponentTokenSet {
     inset?: string;
     /** Background of the region revealed behind a detached panel. */
     canvasBackground?: string;
+    /** Chrome defaults by rendered panel mode. */
+    modes?: Partial<Record<'floating' | 'inline' | 'sidebar' | 'docked' | 'mobile', {
+        /** Full border shorthand (for example, `"1px solid var(--persona-border)"`). */
+        border?: string;
+        /** Box-shadow token reference or raw CSS shadow. */
+        shadow?: string;
+        /** Corner radius token reference or raw CSS radius. */
+        borderRadius?: TokenReference<'radius'>;
+    }>>;
 }
 /** Per-element text styling shared by themable text surfaces. */
 interface TextStyleTokens {
@@ -840,10 +852,16 @@ interface HeaderTokens extends ComponentTokenSet {
      */
     border?: TokenReference<'color'>;
     borderRadius: TokenReference<'radius'>;
+    /** Standard-header padding. @default "20px 24px" */
+    padding?: string;
+    /** Minimal-header padding. Explicitly wins over `padding`. @default "16px 24px" */
+    minimalPadding?: string;
     /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
     iconBackground: TokenReference<'color'>;
     /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
     iconForeground: TokenReference<'color'>;
+    /** Header identity glyph size as a fraction of its icon box. @default "0.6" */
+    iconScale?: string;
     /**
      * Legacy alias of `title.color`; `title.color` wins when both are set.
      * Unset, the title takes `foreground`, then the primary color.
@@ -882,6 +900,14 @@ interface HeaderTokens extends ComponentTokenSet {
      * sibling. @default "1.5"
      */
     controlStrokeWidth?: string;
+    /** Header control corner radius. Per-control radius overrides win. */
+    controlBorderRadius?: string;
+    /** Default control hover/focus fill. Explicit button backgrounds win. */
+    controlHoverBackground?: TokenReference<'color'>;
+    /** Default control hover/focus icon color. Explicit button colors win. */
+    controlHoverForeground?: TokenReference<'color'>;
+    /** Keyboard focus outline; unset preserves the browser default. */
+    controlFocusOutline?: string;
     /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
     shadow?: string;
     /** Override the header bottom border (e.g., `none`). */
@@ -1056,6 +1082,12 @@ interface MessageGeometryTokens {
     lineHeight?: string;
 }
 interface MessageTokens {
+    /** Height of the optional transcript top fade. Default 18px. */
+    topFadeHeight?: string;
+    /** Vertical gap between transcript turns. @default "12px" */
+    gap?: string;
+    /** Gap between turns in fullscreen mode; falls back to `gap`. */
+    fullscreenGap?: string;
     user: MessageGeometryTokens & {
         background: TokenReference<'color'>;
         text: TokenReference<'color'>;
@@ -1069,6 +1101,8 @@ interface MessageTokens {
         borderRadius: TokenReference<'radius'>;
         /** Assistant bubble border color (CSS color). */
         border?: TokenReference<'color'>;
+        /** Border width; set to 0px for a flat assistant response. @default "1px" */
+        borderWidth?: string;
         /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
         shadow?: string;
     };
@@ -1187,12 +1221,40 @@ interface AttachmentTokens {
     };
 }
 /** Tool-call row chrome (collapsible tool bubbles). */
-interface ToolBubbleTokens {
+interface ActivityTokens {
+    /** Minimum activity row height. */
+    rowHeight?: string;
+    /** Group child indentation; falls back to indent when unset. V5: 0px. */
+    groupIndent?: string;
+    /** Extra vertical gap between grouped rows. V5: 0px. */
+    groupGap?: string;
+    /** Padding around expanded group children. V5: 0px. */
+    groupPadding?: string;
+    /** Gap between consecutive activity entries. V5: 0px. */
+    transcriptGap?: string;
+    /** Gap from activity to an assistant response. V5: 12px. */
+    responseGap?: string;
+    /** Expanded body padding. V5: 4px 0. */
+    bodyPadding?: string;
+    /** Expanded reasoning text size. V5: 13px. */
+    bodySize?: string;
+    /** Expanded reasoning line height. V5: 1.5. */
+    bodyLineHeight?: string;
+    /** Expanded reasoning font weight. V5: 400. */
+    bodyFontWeight?: string;
+    /** Gap between expanded detail sections. V5: 8px. */
+    sectionGap?: string;
+    labelSize?: string;
+    iconSize?: string;
+    indent?: string;
+    bodySurface?: TokenReference<'color'>;
+}
+interface ToolBubbleTokens extends ActivityTokens {
     /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
     shadow: string;
 }
 /** Reasoning / “thinking” row chrome. */
-interface ReasoningBubbleTokens {
+interface ReasoningBubbleTokens extends ActivityTokens {
     shadow: string;
 }
 /** One event-stream badge chip: fill + text pair. The chip border derives
@@ -1326,6 +1388,10 @@ interface ComposerChromeTokens {
     shadow: string;
     /** Border color of the composer form. @default semantic.colors.border */
     borderColor?: TokenReference<'color'>;
+    /** Focused form border color; falls back to borderColor. V5: a stronger neutral border. */
+    focusBorderColor?: TokenReference<'color'>;
+    /** Outer focus ring (CSS outline shorthand). V4: none; V5: a thin neutral ring. */
+    focusRing?: string;
     /** Inner padding of the composer form (raw CSS shorthand). @default "0.75rem 1rem" */
     padding?: string;
     /** Gap between the textarea row and the actions row. @default "0.5rem" */
@@ -1344,12 +1410,18 @@ interface ComposerChromeTokens {
     controlSize?: string;
     /** Glyph box inside those controls. @default "24px" */
     controlIconSize?: string;
+    /** Send/stop glyph size. Explicit sendButton.iconSize wins. V5: 18px. */
+    sendIconSize?: string;
+    /** Icon-mode submit button radius. V4 inherits the primary button; V5: 9999px. */
+    sendButtonRadius?: string;
+    /** Footer top border (CSS shorthand). V4: 1px solid divider; V5: none. */
+    footerBorder?: string;
     /**
      * Background painted behind an overlaid composer footer
      * (`composer.placement: "overlay"`). Any CSS `background` value, gradients
      * included — same convention as the shadow tokens. Inert under
      * `placement: "block"`.
-     * @default "transparent"
+     * @default "transparent" (V4); a theme-aware 24px fade (V5)
      */
     overlayBand?: string;
     /** Segmented mode-group track. */
@@ -1525,6 +1597,8 @@ interface ScrollToBottomTokens extends ComponentTokenSet {
 }
 /** Visual tokens shared by one suggestion presentation variant. */
 interface SuggestionVariantTokens extends ComponentTokenSet {
+    /** Label weight. V4: 500; V5: 400. */
+    fontWeight?: string;
     /** Space inside one item, between its icon and its copy. */
     gap?: string;
     /** Space between suggestion items in the container. */
@@ -1573,6 +1647,7 @@ interface ComponentTokens {
     voice: VoiceTokens;
     approval: ApprovalTokens;
     attachment: AttachmentTokens;
+    activity?: ActivityTokens;
     toolBubble: ToolBubbleTokens;
     reasoningBubble: ReasoningBubbleTokens;
     /** Event-stream inspector badge chips. */
@@ -1702,6 +1777,7 @@ type RuntypeExecutionStreamEvent = ({
     turnIndex?: number;
     type: "turn_start";
 }) | ({
+    attributes?: Record<string, string | number | boolean>;
     completedAt?: string;
     content?: string;
     cost?: number;
@@ -1760,7 +1836,8 @@ type RuntypeExecutionStreamEvent = ({
     };
     turnId?: string;
     type: "model_call_start";
-} | {
+} | ({
+    attributes?: Record<string, string | number | boolean>;
     completedAt?: string;
     cost?: number;
     durationMs?: number;
@@ -1784,10 +1861,11 @@ type RuntypeExecutionStreamEvent = ({
         cacheWrite?: number;
         input: number;
         output: number;
+        reasoning?: number;
     };
     turnId?: string;
     type: "model_call_complete";
-} | {
+}) | {
     executionId: string;
     id: string;
     index?: number;
@@ -2954,10 +3032,32 @@ type AgentWidgetContextMentionTokenRenderContext = {
     ref: AgentWidgetContextMentionRef;
     readonly: boolean;
 };
+/** One earlier client-tool call replayed to the model, in `/v1/dispatch` shape. */
+type AgentWidgetReplayedToolCall = {
+    toolCallId: string;
+    /** Model-facing (sanitized) name, e.g. `webmcp_search`. */
+    toolName: string;
+    args: Record<string, unknown>;
+};
+/** The browser's answer to an {@link AgentWidgetReplayedToolCall}. */
+type AgentWidgetReplayedToolResult = {
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+};
+/**
+ * A message in the proxy/agent request payload. Earlier client-tool calls the
+ * browser answered replay as an assistant message carrying `toolCalls`,
+ * followed by a `tool` message carrying the matching `toolResults`; both have
+ * empty `content`. Client-token mode never sends them: the server replays
+ * from its own stored transcript there.
+ */
 type AgentWidgetRequestPayloadMessage = {
-    role: AgentWidgetMessageRole;
+    role: AgentWidgetMessageRole | "tool";
     content: MessageContent;
     createdAt: string;
+    toolCalls?: AgentWidgetReplayedToolCall[];
+    toolResults?: AgentWidgetReplayedToolResult[];
 };
 type AgentWidgetRequestPayload = {
     messages: AgentWidgetRequestPayloadMessage[];
@@ -3353,6 +3453,24 @@ type AgentMessageMetadata = {
      * never re-resume the call.
      */
     suggestRepliesResolved?: boolean;
+    /**
+     * The client-tool answer the server accepted through `/resume`, kept so
+     * later proxy/agent turns can replay the call and its result to the model.
+     * `toolName` is the widget's internal name (`webmcp:<name>` or a bare
+     * built-in). Set only after the resume succeeds; preserved across
+     * re-emissions of the tool message.
+     */
+    clientToolAnswer?: {
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+        result: unknown;
+        /**
+         * Shared by the answers posted in one `/resume`, i.e. one assistant
+         * turn's parallel calls; a chained call gets a new batch.
+         */
+        batch?: string;
+    };
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -4350,6 +4468,14 @@ type AgentWidgetToolCallCollapsedMode = "tool-call" | "tool-name" | "tool-previe
  */
 type AgentWidgetToolCallLoadingAnimation = "none" | "pulse" | "shimmer" | "shimmer-color" | "rainbow";
 type AgentWidgetToolCallDisplayFeature = {
+    /** Activity chrome. Defaults to card in V4 and row with future.v5Defaults. */
+    variant?: "card" | "row";
+    /** Row status icons: always, active/attention-needed only, or never. V5 defaults to active; V4 to always. */
+    iconVisibility?: "always" | "active" | "never";
+    /** Row variant: open when the first content chunk arrives. Default false in V5; true in V4. */
+    autoExpand?: boolean;
+    /** Row variant: collapse once after completion, in ms; false disables. Default 1000. */
+    autoCollapseDelay?: number | false;
     /**
      * Controls what collapsed tool call rows show in their header/summary area.
      * @default "tool-call"
@@ -4380,9 +4506,10 @@ type AgentWidgetToolCallDisplayFeature = {
      * Controls how a grouped tool sequence is rendered.
      * - `"stack"`: show the group summary and each child tool row.
      * - `"summary"`: show one consolidated summary row only.
+     * - `"collapsible"`: expandable activity group (V5 default).
      * @default "stack"
      */
-    groupedMode?: "stack" | "summary";
+    groupedMode?: "stack" | "summary" | "collapsible";
     /**
      * What happens to a tool call row once it completes.
      *
@@ -4413,6 +4540,14 @@ type AgentWidgetToolCallDisplayFeature = {
 /** See `features.toolCallDisplay.completedVisibility`. */
 type AgentWidgetToolCallCompletedVisibility = "kept" | "removed";
 type AgentWidgetReasoningDisplayFeature = {
+    /** Activity chrome. Defaults to card in V4 and row with future.v5Defaults. */
+    variant?: "card" | "row";
+    /** Row status icons: always, active/attention-needed only, or never. V5 defaults to active; V4 to always. */
+    iconVisibility?: "always" | "active" | "never";
+    /** Row variant: open when the first content chunk arrives. Default false in V5; true in V4. */
+    autoExpand?: boolean;
+    /** Row variant: collapse once after completion, in ms; false disables. Default 1000. */
+    autoCollapseDelay?: number | false;
     /**
      * When true, active collapsed reasoning rows can render a lightweight preview block.
      * @default false
@@ -5108,8 +5243,8 @@ interface AgentWidgetHistoryFeature {
      * otherwise `"browser"`) and narrows it to what the provider advertises, so a
      * browser-only provider is never asked for a scope it cannot serve. An
      * explicit `features.history.scope` is a hard request and still fails closed
-     * with `unsupported_scope`. `getIdentityProof` is never called for a supplied
-     * provider, and `HistoryOperationContext` carries only the resolved scope;
+     * with `unsupported_scope`. History operations on a supplied provider never
+     * call `getIdentityProof`, and `HistoryOperationContext` carries only the resolved scope;
      * report your own identity through `getIdentityStatus()` /
      * `subscribeIdentityStatus()`, which is what the scope banner and its retry
      * affordance read.
@@ -5493,7 +5628,7 @@ type EventStreamConfig = {
     /**
      * Fields to extract from event payloads for description text.
      * The first matching field value is displayed after the badge.
-     * @default ["flowName", "stepName", "name", "tool", "toolName"]
+     * @default ["flowName", "stepName", "reasoningText", "text", "name", "tool", "toolName"]
      */
     descriptionFields?: string[];
     /**
@@ -5704,6 +5839,8 @@ type AgentWidgetComposerBarPeekConfig = {
     streamAnimation?: AgentWidgetStreamAnimationFeature;
 };
 type AgentWidgetLauncherConfig = {
+    /** Collapsed launcher shape. V4 defaults to pill; V5 defaults to circle. */
+    variant?: "pill" | "circle";
     enabled?: boolean;
     title?: string;
     subtitle?: string;
@@ -6459,9 +6596,9 @@ type AgentWidgetComposerConfig = {
     /**
      * Where the composer footer sits relative to the transcript.
      *
-     * - `"block"` (default): the footer is a flex sibling below the scroll body.
+     * - `"block"` (V4 default): the footer is a flex sibling below the scroll body.
      *   Nothing scrolls behind it.
-     * - `"overlay"`: the footer is absolutely overlaid on the scroll body, so the
+     * - `"overlay"` (V5 default): the footer is absolutely overlaid on the scroll body, so the
      *   transcript scrolls behind it (the chatgpt.com / claude.ai model, where the
      *   composer is sticky inside the scroller). The widget reserves the footer's
      *   live height as bottom padding on the scroll body and on a plugin welcome
@@ -6473,7 +6610,7 @@ type AgentWidgetComposerConfig = {
      * included) and `theme.components.input.backdropFilter`.
      *
      * Ignored in composer-bar mount mode, which owns its own geometry.
-     * @default "block"
+     * @default "block" (V4), "overlay" (V5)
      */
     placement?: ComposerPlacement;
     /**
@@ -6487,8 +6624,9 @@ type AgentWidgetComposerConfig = {
      *
      * `"single-row"` describes the IDLE composer only. It composes with the
      * compact state, so a wrapped draft, chips, attachment previews, a quote, a
-     * pending card, or live dictation all fall back to the stacked card, exactly
-     * as `data-persona-composer-compact` does today.
+     * pending card all fall back to the stacked card, exactly
+     * as `data-persona-composer-compact` does today. Recording alone does not
+     * expand the composer; dictated text expands it when it wraps.
      *
      * Ignored in composer-bar mount mode, whose pill is already one row.
      * @default "stacked"
@@ -6530,7 +6668,14 @@ type AgentWidgetClearChatConfig = {
     showTooltip?: boolean;
 };
 type AgentWidgetStatusIndicatorConfig = {
+    /** Show the indicator. Explicit false also hides transient connection states. */
     visible?: boolean;
+    /**
+     * "always" shows status beneath the composer; "transient" shows connecting,
+     * reconnecting, and error status above it, hiding normal idle/streaming status.
+     * Available in both defaults states. Default: "always" in v4, "transient" in v5.
+     */
+    mode?: "always" | "transient";
     /** Text alignment. Default: 'right'. */
     align?: 'left' | 'center' | 'right';
     idleText?: string;
@@ -7350,7 +7495,8 @@ type AgentWidgetResolvedSuggestion = {
 };
 /** Presentation keys shared by every suggestion surface. */
 type AgentWidgetSuggestionSurfaceConfig = {
-    /** Item density. Defaults to `card` for starters and `chip` for follow-ups. */
+    /** Item density. V4 starters: card. V5 starters: chip, or card in fullscreen.
+     * Follow-ups default to chip. */
     variant?: AgentWidgetSuggestionVariant;
     /** Default click behavior, overridable per item. Defaults to `send`. */
     behavior?: AgentWidgetSuggestionBehavior;
@@ -7361,7 +7507,7 @@ type AgentWidgetSuggestionSurfaceConfig = {
      * own stacking.
      */
     overflow?: "scroll" | "wrap";
-    /** Maximum visible items. Defaults to 4. */
+    /** Maximum visible items. Defaults to 4, or 3 for V5 non-fullscreen starters. */
     maxItems?: number;
 };
 type AgentWidgetStarterSuggestionsConfig = AgentWidgetSuggestionSurfaceConfig & {
@@ -7415,8 +7561,8 @@ type AgentWidgetSuggestionsConfig = {
 type AgentWidgetWelcomeVariant = "card" | "hero" | "none";
 /**
  * When the welcome surface goes away. `"never"` is the default for `"card"`;
- * `"on-first-message"` is the default for `"hero"` and cannot be overridden
- * there.
+ * `"on-first-message"` is forced for legacy V4 `"hero"`. V5 defaults every
+ * variant to `"on-first-message"`. Explicit layout opts into overridable dismissal.
  */
 type AgentWidgetWelcomeDismiss = "never" | "on-first-message";
 /**
@@ -7470,7 +7616,10 @@ type AgentWidgetWelcomeAlign = "start" | "center";
  * host-set value from a filled-in default.
  */
 interface AgentWidgetWelcomeConfig {
-    /** Card or hero title. Defaults to "Hello 👋". */
+    /** Vertical placement: V4 defaults to top; V5 to centered. Fullscreen centered
+     * welcomes also raise the empty composer unless `anchor` is explicitly set. */
+    layout?: "top" | "centered";
+    /** Card or hero title. V4: "Hello 👋". V5: "What can I help with?". */
     title?: string;
     /**
      * Small muted line above the title, e.g. a section name. Omitted when unset
@@ -7483,19 +7632,22 @@ interface AgentWidgetWelcomeConfig {
     icon?: AgentWidgetWelcomeIcon;
     /**
      * Horizontal alignment of the kicker, title, subtitle, and starter
-     * suggestions. Unset follows the variant: `card` starts, `hero` centers.
+     * suggestions. Centered layouts default to center. Otherwise unset follows
+     * the variant: `card` starts, `hero` centers.
      */
     align?: AgentWidgetWelcomeAlign;
     /** @default "card" */
     variant?: AgentWidgetWelcomeVariant;
-    /** @default "never" for `card`, always `"on-first-message"` for `hero`. */
+    /** V4: never for card, forced on-first-message for hero. V5: on-first-message
+     * for all variants; explicit values win. Explicit layout also allows overriding
+     * the legacy hero dismissal in V4. */
     dismiss?: AgentWidgetWelcomeDismiss;
     /**
      * Vertical anchoring of the greeting-plus-composer pair in the EMPTY
      * conversation only. On the first message the pair drops to the bottom
      * (animated; see `data-persona-conversation-state`).
      *
-     * - `"bottom"` (default): the composer stays pinned at the bottom.
+     * - `"bottom"`: the composer stays pinned at the bottom.
      * - `"center"`: greeting and composer float together so the composer's top
      *   edge lands at `anchorComposerTop` of the panel column, and the welcome
      *   surface is end-anchored `composerGap` above it.
@@ -7503,7 +7655,8 @@ interface AgentWidgetWelcomeConfig {
      * Composes with either `composer.placement`. Ignored in composer-bar mount
      * mode. `renderWelcome` plugin content inherits the anchor: the widget
      * positions the overlay host and reserves the composer zone.
-     * @default "bottom"
+     * Defaults to bottom, except centered fullscreen layouts, which center the
+     * measured greeting/composer group when no anchor override is supplied.
      */
     anchor?: AgentWidgetWelcomeAnchor;
     /**
@@ -8093,6 +8246,9 @@ type AgentWidgetLayoutConfig = {
      * `launcher.composerBar.contentMaxWidth`)
      */
     contentMaxWidth?: string;
+    /** Fade the transcript's top edge when content is scrolled above it.
+     * Defaults to false in V4 and true with future.v5Defaults. */
+    topFade?: boolean;
 };
 /**
  * Token types for marked renderer methods
@@ -8706,7 +8862,30 @@ type AgentWidgetLoadingIndicatorConfig = {
      */
     renderIdle?: (context: IdleIndicatorRenderContext) => HTMLElement | null;
 };
+/** Built-in `sessionInit` triggers. See {@link AgentWidgetConfig.sessionInit}. */
+type AgentWidgetSessionInitTrigger = 'input' | 'focus' | 'mount' | 'send';
+/**
+ * Custom `sessionInit` trigger. Runs when the widget mounts in client token mode,
+ * and again if `update()` swaps in a different function. Call `warm()` whenever
+ * the visitor shows intent (it is safe to call repeatedly). Return a cleanup to
+ * run when the widget is destroyed or the hook is replaced.
+ */
+type AgentWidgetSessionInitHook = (context: {
+    /** Fire-and-forget early session init; latched and error-swallowing. */
+    warm: () => void;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetConfig = {
+    /** Opt in to upcoming major-version defaults without changing explicit settings. */
+    future?: {
+        /**
+         * Use the v5 default styling as it rolls out in 4.x. Every affected setting
+         * remains independently configurable. Explicit options and theme tokens win.
+         * @default false
+         */
+        v5Defaults?: boolean;
+    };
     apiUrl?: string;
     flowId?: string;
     /**
@@ -8861,6 +9040,46 @@ type AgentWidgetConfig = {
      * ```
      */
     onSessionExpired?: () => void;
+    /**
+     * When the widget calls `/v1/client/init` in client token mode, ahead of the
+     * first send. Ignored outside client token mode.
+     *
+     * - `'input'` (default): on the composer's first user keystroke that leaves
+     *   non-empty text. Programmatic value changes (restored drafts,
+     *   `setMessage()`, history recall) do not count.
+     * - `'focus'`: when the visitor focuses the composer by pointer or Tab (and
+     *   on first input, as a fallback). Programmatic focus, such as
+     *   `autoFocusInput` on open or mount, does not count.
+     * - `'mount'`: as soon as the widget mounts (the behavior before this option
+     *   existed). Use it when a server-configured welcome message, which arrives
+     *   with the init response, must show before the visitor types.
+     * - `'send'`: no early init; the first send initializes the session.
+     * - A function: custom trigger. Called on mount (and when `update()` swaps
+     *   in a different function) with a `warm` callback to call whenever you
+     *   decide (e.g. on hover); may return a cleanup that runs on destroy or
+     *   replacement. Replaces the built-in triggers.
+     *
+     * The early init is fire-and-forget: it runs at most once per session
+     * lifetime (re-armed after expiry or a new conversation), sends exactly the
+     * same request the send would, and swallows errors. A failure resurfaces
+     * when the send retries init. A send during an in-flight early init reuses
+     * it, so only one `/v1/client/init` is issued. When visitor history is
+     * enabled the widget still initializes on mount to restore the conversation.
+     * Hosts can also trigger it imperatively with `controller.warmSession()`.
+     *
+     * @default 'input'
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   clientToken: 'ct_live_...',
+     *   sessionInit: ({ warm, mount }) => {
+     *     mount.addEventListener('pointerenter', warm, { once: true });
+     *   }
+     * }
+     * ```
+     */
+    sessionInit?: AgentWidgetSessionInitTrigger | AgentWidgetSessionInitHook;
     /**
      * Get stored session ID for session resumption (client token mode only).
      * Called when initializing a new session to check if there's a previous session_id
@@ -8893,13 +9112,20 @@ type AgentWidgetConfig = {
      */
     setStoredSessionId?: (sessionId: string) => void;
     /**
-     * Called immediately before any cross-device history request and before a
+     * With identityProvider, called before every client-token chat POST, including retries, independently of history.
+     * Also called immediately before any cross-device history request and before a
      * conversationId resume of a conversation discovered on another device.
-     * Return a fresh end-user access token (rt_eu_… / JWT). Null uses exact-browser
-     * scope only for a never-bound visitor; a previously bound visitor fails closed
-     * until resetHistoryIdentity() runs. Never cached by the widget.
+     * Return a fresh end-user access token (rt_eu_… / JWT). Null stops identity-enabled chat.
+     * For history only, null uses exact-browser scope for a never-bound visitor;
+     * a bound visitor fails closed until resetHistoryIdentity(). Never cached.
      */
     getIdentityProof?: () => string | null | Promise<string | null>;
+    /**
+     * Provider name registered with Runtype, for example "clerk". Enables per-request
+     * chat identity through getIdentityProof without enabling history. A missing or
+     * failed proof stops the turn; omitting this preserves history-only callbacks.
+     */
+    identityProvider?: string;
     /**
      * Read the persisted active conversation id (client token mode only).
      * Called only after the internal stored-state bootstrap gate resolves.
@@ -9573,6 +9799,8 @@ type AgentWidgetReasoning = {
     durationMs?: number;
 };
 type AgentWidgetToolCall = {
+    /** Optional approval state for activity-row status chrome. */
+    approvalStatus?: "pending" | "approved" | "denied" | "timeout";
     id: string;
     name?: string;
     status: "pending" | "running" | "complete";
@@ -10042,6 +10270,14 @@ declare class AgentWidgetClient {
     private currentClientTurnId;
     private clientSession;
     private sessionInitPromise;
+    /**
+     * Early-init latch for `warmSession()`. `false` = armed. Otherwise it holds
+     * the session value (`null` or an expired session) the one early attempt was
+     * made against, so a failed attempt is not retried on every keystroke. It is
+     * re-armed when a session is installed or cleared, so each session lifetime
+     * gets one early init.
+     */
+    private sessionWarmLatch;
     private lastSentClientToolsFingerprint;
     private clientToolsFingerprintSessionId;
     private sentNonEmptyClientToolsSessionId;
@@ -10150,9 +10386,27 @@ declare class AgentWidgetClient {
         after: string;
         signal: AbortSignal;
     }): Promise<Response>;
+    /**
+     * Fire-and-forget early `initSession()` for client-token mode, driven by the
+     * widget's `sessionInit` trigger (or a host calling it directly, e.g. on
+     * hover). It fires at most once per session lifetime and is a no-op while a
+     * session is live or an init is already in flight. Errors are swallowed, with
+     * no `onSessionExpired` and no UI: a send calls `initSession()` again and
+     * reuses the in-flight promise, so any failure resurfaces there exactly as it
+     * would without the early init. Sends nothing new on the wire. Outside
+     * client-token mode this does nothing.
+     *
+     * Resolves with the session this call initialized, or `null` when it was
+     * skipped or failed. It never rejects.
+     */
+    warmSession(): Promise<ClientSession | null>;
     /**
      * Initialize session for client token mode.
-     * Called automatically on first message if not already initialized.
+     * Called by the send if no live session exists. The widget normally calls
+     * it earlier, when the visitor shows intent to send (see the `sessionInit`
+     * config option and `warmSession()`), and concurrent calls share one
+     * in-flight request, so a send racing an early init issues a single
+     * `/v1/client/init`.
      */
     initSession(): Promise<ClientSession>;
     /** Visitor history rides on client-token init only, and latches off after a 403 degrade. */
@@ -10297,6 +10551,7 @@ declare class AgentWidgetClient {
     private historyUrl;
     /** Explicit per-operation scope wins; otherwise config, then evidence. */
     private resolveHistoryScope;
+    private resolveChatIdentityProof;
     /**
      * Resolve the proof for one logical request. `null` is an intentional
      * browser-scope fallback only while the visitor has never been bound.
@@ -10752,10 +11007,16 @@ declare class AgentWidgetSession {
      * explicitly to pre-initialize the session and get config from server.
      */
     initClientSession(): Promise<ClientSession | null>;
+    /**
+     * Early, fire-and-forget client-token init (`sessionInit` trigger or
+     * `controller.initSession()`). Failures stay silent here: no `onError`, no
+     * UI. The send re-runs `initSession()` and reports them as it always has.
+     */
+    warmClientSession(): void;
     /**
      * Set the client session after initialization
      */
-    setClientSession(session: ClientSession): void;
+    setClientSession(session: ClientSession, pristine?: boolean): void;
     /**
      * Welcome injection is skipped while `suppressWelcomeInjection` is latched:
      * reopening a stored conversation is not a new thread, and the hydrated