@runtypelabs/persona 3.23.0 → 3.25.0

package/dist/index.d.ts

@@ -2778,6 +2778,14 @@ type ClientChatRequest = {
     context?: Record<string, unknown>;
     /** WebMCP page-discovered tools — same shape as `dispatch.clientTools[]`. */
     clientTools?: ClientToolDefinition[];
+    /**
+     * Diff-only / send-once: order-independent fingerprint of the client tool set.
+     * When the set is unchanged from the previous turn the widget sends this
+     * WITHOUT `clientTools` and the server reuses its stored set. On a cache miss
+     * the server replies `409 { error: 'client_tools_resend_required' }` and the
+     * widget retries once with the full `clientTools[]`.
+     */
+    clientToolsFingerprint?: string;
 };
 /**
  * Feedback types supported by the API
@@ -4628,6 +4636,8 @@ declare class AgentWidgetClient {
     private onSSEEvent?;
     private clientSession;
     private sessionInitPromise;
+    private lastSentClientToolsFingerprint;
+    private clientToolsFingerprintSessionId;
     private readonly webMcpBridge;
     constructor(config?: AgentWidgetConfig);
     /**
@@ -4688,6 +4698,12 @@ declare class AgentWidgetClient {
      * Clear the current client session
      */
     clearClientSession(): void;
+    /**
+     * Forget the diff-only WebMCP tool fingerprint so the next client-token turn
+     * resends the full `clientTools[]`. Called when the session is cleared and
+     * when the conversation is reset (`WidgetSession.clearMessages`).
+     */
+    resetClientToolsFingerprint(): void;
     /**
      * Get the feedback API URL
      */
@@ -6085,148 +6101,6 @@ declare const isDockedMountMode: (config?: AgentWidgetConfig) => boolean;
  */
 declare const resolveDockConfig: (config?: AgentWidgetConfig) => Required<AgentWidgetDockConfig>;
 
-type CodeFormat = "esm" | "script-installer" | "script-manual" | "script-advanced" | "react-component" | "react-advanced";
-/**
- * Hook code templates for code generation.
- * Each hook can be provided as a string (code template) OR as an actual function.
- * Functions are automatically serialized via `.toString()`.
- *
- * IMPORTANT: When providing functions:
- * - Functions must be self-contained (no external variables/closures)
- * - External variables will be undefined when the generated code runs
- * - Use arrow functions or regular function expressions
- *
- * @example
- * ```typescript
- * // Both of these work:
- *
- * // As string:
- * { getHeaders: "async () => ({ 'Authorization': 'Bearer token' })" }
- *
- * // As function (recommended - better IDE support):
- * { getHeaders: async () => ({ 'Authorization': 'Bearer token' }) }
- * ```
- */
-type CodeGeneratorHooks = {
-    /**
-     * Custom getHeaders function.
-     * Should return an object with header key-value pairs.
-     *
-     * @example
-     * ```typescript
-     * async () => ({ 'Authorization': `Bearer ${await getAuthToken()}` })
-     * ```
-     */
-    getHeaders?: string | (() => Record<string, string> | Promise<Record<string, string>>);
-    /**
-     * Custom onFeedback callback for message actions.
-     * Receives a feedback object with type, messageId, and message.
-     *
-     * @example
-     * ```typescript
-     * (feedback) => { console.log('Feedback:', feedback.type); }
-     * ```
-     */
-    onFeedback?: string | ((feedback: {
-        type: string;
-        messageId: string;
-        message: unknown;
-    }) => void);
-    /**
-     * Custom onCopy callback for message actions.
-     * Receives the message that was copied.
-     *
-     * @example
-     * ```typescript
-     * (message) => { analytics.track('message_copied', { id: message.id }); }
-     * ```
-     */
-    onCopy?: string | ((message: unknown) => void);
-    /**
-     * Custom requestMiddleware function.
-     * Receives { payload, config } context.
-     *
-     * @example
-     * ```typescript
-     * ({ payload }) => ({ ...payload, metadata: { pageUrl: window.location.href } })
-     * ```
-     */
-    requestMiddleware?: string | ((context: {
-        payload: unknown;
-        config: unknown;
-    }) => unknown);
-    /**
-     * Custom action handlers array.
-     * Array of handler functions.
-     *
-     * @example
-     * ```typescript
-     * [
-     *   (action, context) => {
-     *     if (action.type === 'custom') {
-     *       return { handled: true };
-     *     }
-     *   }
-     * ]
-     * ```
-     */
-    actionHandlers?: string | Array<(action: unknown, context: unknown) => unknown>;
-    /**
-     * Custom action parsers array.
-     * Array of parser functions.
-     */
-    actionParsers?: string | Array<(context: unknown) => unknown>;
-    /**
-     * Custom postprocessMessage function.
-     * Receives { text, message, streaming, raw } context.
-     * Will override the default markdownPostprocessor.
-     *
-     * @example
-     * ```typescript
-     * ({ text }) => customMarkdownProcessor(text)
-     * ```
-     */
-    postprocessMessage?: string | ((context: {
-        text: string;
-        message?: unknown;
-        streaming?: boolean;
-        raw?: string;
-    }) => string);
-    /**
-     * Custom context providers array.
-     * Array of provider functions.
-     */
-    contextProviders?: string | Array<() => unknown>;
-    /**
-     * Custom stream parser factory.
-     * Should be a function that returns a StreamParser.
-     */
-    streamParser?: string | (() => unknown);
-};
-/**
- * Options for code generation beyond format selection.
- */
-type CodeGeneratorOptions = {
-    /**
-     * Custom hook code to inject into the generated snippet.
-     * Hooks are JavaScript/TypeScript code strings that will be
-     * inserted at appropriate locations in the output.
-     */
-    hooks?: CodeGeneratorHooks;
-    /**
-     * Whether to include comments explaining each hook.
-     * @default true
-     */
-    includeHookComments?: boolean;
-    /**
-     * If provided, emits `windowKey` in the generated `initAgentWidget()` call
-     * so the widget handle is stored on `window[windowKey]`.
-     * Only affects script formats (script-installer, script-manual, script-advanced).
-     */
-    windowKey?: string;
-};
-declare function generateCodeSnippet(config: any, format?: CodeFormat, options?: CodeGeneratorOptions): string;
-
 /**
  * The current version of the @runtypelabs/persona package.
  * This is automatically derived from package.json.
@@ -6633,54 +6507,6 @@ interface ComboButtonHandle {
  */
 declare function createComboButton(options: CreateComboButtonOptions): ComboButtonHandle;
 
-interface DemoCarouselItem {
-    /** URL to load in the iframe (relative or absolute). */
-    url: string;
-    /** Display title shown in the toolbar. */
-    title: string;
-    /** Optional subtitle/description. */
-    description?: string;
-}
-interface DemoCarouselOptions {
-    /** Demo pages to cycle through. */
-    items: DemoCarouselItem[];
-    /** Initial item index. Default: 0. */
-    initialIndex?: number;
-    /** Initial device viewport. Default: 'desktop'. */
-    initialDevice?: "desktop" | "mobile";
-    /** Initial color scheme for the iframe wrapper. Default: 'light'. */
-    initialColorScheme?: "light" | "dark";
-    /** Show zoom +/- controls. Default: true. */
-    showZoomControls?: boolean;
-    /** Show desktop/mobile toggle. Default: true. */
-    showDeviceToggle?: boolean;
-    /** Show light/dark scheme toggle. Default: true. */
-    showColorSchemeToggle?: boolean;
-    /** Called when the active demo changes. */
-    onChange?: (index: number, item: DemoCarouselItem) => void;
-}
-interface DemoCarouselHandle {
-    /** Root element (already appended to the container). */
-    element: HTMLElement;
-    /** Navigate to a demo by index. */
-    goTo(index: number): void;
-    /** Go to the next demo. */
-    next(): void;
-    /** Go to the previous demo. */
-    prev(): void;
-    /** Current demo index. */
-    getIndex(): number;
-    /** Change the device viewport. */
-    setDevice(device: "desktop" | "mobile"): void;
-    /** Change the wrapper color scheme. */
-    setColorScheme(scheme: "light" | "dark"): void;
-    /** Override zoom level (null = auto-fit). */
-    setZoom(zoom: number | null): void;
-    /** Tear down listeners, observer, and DOM. */
-    destroy(): void;
-}
-declare function createDemoCarousel(container: HTMLElement, options: DemoCarouselOptions): DemoCarouselHandle;
-
 declare const DEFAULT_PALETTE: {
     colors: {
         primary: {
@@ -7247,4 +7073,194 @@ declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
 declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
 declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
 
+type CodeFormat = "esm" | "script-installer" | "script-manual" | "script-advanced" | "react-component" | "react-advanced";
+/**
+ * Hook code templates for code generation.
+ * Each hook can be provided as a string (code template) OR as an actual function.
+ * Functions are automatically serialized via `.toString()`.
+ *
+ * IMPORTANT: When providing functions:
+ * - Functions must be self-contained (no external variables/closures)
+ * - External variables will be undefined when the generated code runs
+ * - Use arrow functions or regular function expressions
+ *
+ * @example
+ * ```typescript
+ * // Both of these work:
+ *
+ * // As string:
+ * { getHeaders: "async () => ({ 'Authorization': 'Bearer token' })" }
+ *
+ * // As function (recommended - better IDE support):
+ * { getHeaders: async () => ({ 'Authorization': 'Bearer token' }) }
+ * ```
+ */
+type CodeGeneratorHooks = {
+    /**
+     * Custom getHeaders function.
+     * Should return an object with header key-value pairs.
+     *
+     * @example
+     * ```typescript
+     * async () => ({ 'Authorization': `Bearer ${await getAuthToken()}` })
+     * ```
+     */
+    getHeaders?: string | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Custom onFeedback callback for message actions.
+     * Receives a feedback object with type, messageId, and message.
+     *
+     * @example
+     * ```typescript
+     * (feedback) => { console.log('Feedback:', feedback.type); }
+     * ```
+     */
+    onFeedback?: string | ((feedback: {
+        type: string;
+        messageId: string;
+        message: unknown;
+    }) => void);
+    /**
+     * Custom onCopy callback for message actions.
+     * Receives the message that was copied.
+     *
+     * @example
+     * ```typescript
+     * (message) => { analytics.track('message_copied', { id: message.id }); }
+     * ```
+     */
+    onCopy?: string | ((message: unknown) => void);
+    /**
+     * Custom requestMiddleware function.
+     * Receives { payload, config } context.
+     *
+     * @example
+     * ```typescript
+     * ({ payload }) => ({ ...payload, metadata: { pageUrl: window.location.href } })
+     * ```
+     */
+    requestMiddleware?: string | ((context: {
+        payload: unknown;
+        config: unknown;
+    }) => unknown);
+    /**
+     * Custom action handlers array.
+     * Array of handler functions.
+     *
+     * @example
+     * ```typescript
+     * [
+     *   (action, context) => {
+     *     if (action.type === 'custom') {
+     *       return { handled: true };
+     *     }
+     *   }
+     * ]
+     * ```
+     */
+    actionHandlers?: string | Array<(action: unknown, context: unknown) => unknown>;
+    /**
+     * Custom action parsers array.
+     * Array of parser functions.
+     */
+    actionParsers?: string | Array<(context: unknown) => unknown>;
+    /**
+     * Custom postprocessMessage function.
+     * Receives { text, message, streaming, raw } context.
+     * Will override the default markdownPostprocessor.
+     *
+     * @example
+     * ```typescript
+     * ({ text }) => customMarkdownProcessor(text)
+     * ```
+     */
+    postprocessMessage?: string | ((context: {
+        text: string;
+        message?: unknown;
+        streaming?: boolean;
+        raw?: string;
+    }) => string);
+    /**
+     * Custom context providers array.
+     * Array of provider functions.
+     */
+    contextProviders?: string | Array<() => unknown>;
+    /**
+     * Custom stream parser factory.
+     * Should be a function that returns a StreamParser.
+     */
+    streamParser?: string | (() => unknown);
+};
+/**
+ * Options for code generation beyond format selection.
+ */
+type CodeGeneratorOptions = {
+    /**
+     * Custom hook code to inject into the generated snippet.
+     * Hooks are JavaScript/TypeScript code strings that will be
+     * inserted at appropriate locations in the output.
+     */
+    hooks?: CodeGeneratorHooks;
+    /**
+     * Whether to include comments explaining each hook.
+     * @default true
+     */
+    includeHookComments?: boolean;
+    /**
+     * If provided, emits `windowKey` in the generated `initAgentWidget()` call
+     * so the widget handle is stored on `window[windowKey]`.
+     * Only affects script formats (script-installer, script-manual, script-advanced).
+     */
+    windowKey?: string;
+};
+declare function generateCodeSnippet(config: any, format?: CodeFormat, options?: CodeGeneratorOptions): string;
+
+interface DemoCarouselItem {
+    /** URL to load in the iframe (relative or absolute). */
+    url: string;
+    /** Display title shown in the toolbar. */
+    title: string;
+    /** Optional subtitle/description. */
+    description?: string;
+}
+interface DemoCarouselOptions {
+    /** Demo pages to cycle through. */
+    items: DemoCarouselItem[];
+    /** Initial item index. Default: 0. */
+    initialIndex?: number;
+    /** Initial device viewport. Default: 'desktop'. */
+    initialDevice?: "desktop" | "mobile";
+    /** Initial color scheme for the iframe wrapper. Default: 'light'. */
+    initialColorScheme?: "light" | "dark";
+    /** Show zoom +/- controls. Default: true. */
+    showZoomControls?: boolean;
+    /** Show desktop/mobile toggle. Default: true. */
+    showDeviceToggle?: boolean;
+    /** Show light/dark scheme toggle. Default: true. */
+    showColorSchemeToggle?: boolean;
+    /** Called when the active demo changes. */
+    onChange?: (index: number, item: DemoCarouselItem) => void;
+}
+interface DemoCarouselHandle {
+    /** Root element (already appended to the container). */
+    element: HTMLElement;
+    /** Navigate to a demo by index. */
+    goTo(index: number): void;
+    /** Go to the next demo. */
+    next(): void;
+    /** Go to the previous demo. */
+    prev(): void;
+    /** Current demo index. */
+    getIndex(): number;
+    /** Change the device viewport. */
+    setDevice(device: "desktop" | "mobile"): void;
+    /** Change the wrapper color scheme. */
+    setColorScheme(scheme: "light" | "dark"): void;
+    /** Override zoom level (null = auto-fit). */
+    setZoom(zoom: number | null): void;
+    /** Tear down listeners, observer, and DOM. */
+    destroy(): void;
+}
+declare function createDemoCarousel(container: HTMLElement, options: DemoCarouselOptions): DemoCarouselHandle;
+
 export { ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetActionContext, type AgentWidgetActionEventPayload, type AgentWidgetActionHandler, type AgentWidgetActionHandlerResult, type AgentWidgetActionParser, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetContextProvider, type AgentWidgetContextProviderContext, 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 AgentWidgetParsedAction, 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 AgentWidgetWebMcpConfig, 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 ClientToolDefinition, 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 IconName, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectComponentDirectiveOptions, 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, WEBMCP_TOOL_PREFIX, WebMcpBridge, type WebMcpConfirmHandler, type WebMcpConfirmInfo, type WebMcpToolResult, 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, isWebMcpToolName, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, renderLucideIcon, resolveDockConfig, resolveSanitizer, resolveTokens, stripWebMcpPrefix, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };