@runtypelabs/persona 1.41.0 → 1.43.0

package/dist/index.d.ts

@@ -100,6 +100,26 @@ interface AgentWidgetPlugin {
      * ```
      */
     renderIdleIndicator?: (context: IdleIndicatorRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for the entire event stream view.
+     * Return null to use default renderer.
+     */
+    renderEventStreamView?: (context: EventStreamViewRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for individual event stream rows.
+     * Return null to use default renderer.
+     */
+    renderEventStreamRow?: (context: EventStreamRowRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for the event stream toolbar/header bar.
+     * Return null to use default renderer.
+     */
+    renderEventStreamToolbar?: (context: EventStreamToolbarRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for the expanded event payload display.
+     * Return null to use default renderer.
+     */
+    renderEventStreamPayload?: (context: EventStreamPayloadRenderContext) => HTMLElement | null;
     /**
      * Called when plugin is registered
      */
@@ -161,6 +181,81 @@ type AgentWidgetRequestPayload = {
     context?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
 };
+/**
+ * Configuration for agent loop behavior.
+ */
+type AgentLoopConfig = {
+    /** Maximum number of reasoning iterations */
+    maxIterations: number;
+    /** Stop condition: 'auto' for automatic detection, or a custom JS expression */
+    stopCondition?: 'auto' | string;
+    /** Enable periodic reflection during execution */
+    enableReflection?: boolean;
+    /** Number of iterations between reflections */
+    reflectionInterval?: number;
+};
+/**
+ * Agent configuration for agent execution mode.
+ * When provided in the widget config, enables agent loop execution instead of flow dispatch.
+ */
+type AgentConfig = {
+    /** Agent display name */
+    name: string;
+    /** Model identifier (e.g., 'openai:gpt-4o-mini') */
+    model: string;
+    /** System prompt for the agent */
+    systemPrompt: string;
+    /** Temperature for model responses */
+    temperature?: number;
+    /** Loop configuration for multi-iteration execution */
+    loopConfig?: AgentLoopConfig;
+};
+/**
+ * Options for agent execution requests.
+ */
+type AgentRequestOptions = {
+    /** Whether to stream the response (should be true for widget usage) */
+    streamResponse?: boolean;
+    /** Record mode: 'virtual' for no persistence, 'existing'/'create' for database records */
+    recordMode?: 'virtual' | 'existing' | 'create';
+    /** Whether to store results server-side */
+    storeResults?: boolean;
+    /** Enable debug mode for additional event data */
+    debugMode?: boolean;
+};
+/**
+ * Request payload for agent execution mode.
+ */
+type AgentWidgetAgentRequestPayload = {
+    agent: AgentConfig;
+    messages: AgentWidgetRequestPayloadMessage[];
+    options: AgentRequestOptions;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Agent execution state tracking.
+ */
+type AgentExecutionState = {
+    executionId: string;
+    agentId: string;
+    agentName: string;
+    status: 'running' | 'complete' | 'error';
+    currentIteration: number;
+    maxIterations: number;
+    startedAt?: number;
+    completedAt?: number;
+    stopReason?: 'max_iterations' | 'complete' | 'error' | 'manual';
+};
+/**
+ * Metadata attached to messages created during agent execution.
+ */
+type AgentMessageMetadata = {
+    executionId?: string;
+    iteration?: number;
+    turnId?: string;
+    agentName?: string;
+};
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
     config: AgentWidgetConfig;
@@ -330,10 +425,130 @@ type AgentWidgetControllerEventMap = {
     "widget:state": AgentWidgetStateSnapshot;
     "message:feedback": AgentWidgetMessageFeedback;
     "message:copy": AgentWidgetMessage;
+    "eventStream:opened": {
+        timestamp: number;
+    };
+    "eventStream:closed": {
+        timestamp: number;
+    };
 };
 type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
     showToolCalls?: boolean;
+    showEventStreamToggle?: boolean;
+    /** Configuration for the Event Stream inspector view */
+    eventStream?: EventStreamConfig;
+};
+type SSEEventRecord = {
+    id: string;
+    type: string;
+    timestamp: number;
+    payload: string;
+};
+/**
+ * Badge color configuration for event stream event types.
+ */
+type EventStreamBadgeColor = {
+    /** Background color (CSS value) */
+    bg: string;
+    /** Text color (CSS value) */
+    text: string;
+};
+/**
+ * Configuration for the Event Stream inspector view.
+ */
+type EventStreamConfig = {
+    /**
+     * Custom badge color mappings by event type prefix or exact type.
+     * Keys are matched as exact match first, then prefix match (keys ending with "_").
+     * @example { "flow_": { bg: "#dcfce7", text: "#166534" }, "error": { bg: "#fecaca", text: "#991b1b" } }
+     */
+    badgeColors?: Record<string, EventStreamBadgeColor>;
+    /**
+     * Timestamp display format.
+     * - "relative": Shows time offset from first event (+0.000s, +0.361s)
+     * - "absolute": Shows wall-clock time (HH:MM:SS.mmm)
+     * @default "relative"
+     */
+    timestampFormat?: "absolute" | "relative";
+    /**
+     * Whether to show sequential event numbers (1, 2, 3...).
+     * @default true
+     */
+    showSequenceNumbers?: boolean;
+    /**
+     * Maximum events to keep in the ring buffer.
+     * @default 500
+     */
+    maxEvents?: number;
+    /**
+     * 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"]
+     */
+    descriptionFields?: string[];
+    /**
+     * Custom CSS class names to append to event stream UI elements.
+     * Each value is a space-separated class string appended to the element's default classes.
+     */
+    classNames?: {
+        /** The toggle button in the widget header (activity icon). */
+        toggleButton?: string;
+        /** Additional classes applied to the toggle button when the event stream is open. */
+        toggleButtonActive?: string;
+        /** The outer event stream panel/container. */
+        panel?: string;
+        /** The toolbar header bar (title, filter, copy all). */
+        headerBar?: string;
+        /** The search bar wrapper. */
+        searchBar?: string;
+        /** The search text input. */
+        searchInput?: string;
+        /** Each event row wrapper. */
+        eventRow?: string;
+        /** The "new events" scroll indicator pill. */
+        scrollIndicator?: string;
+    };
+};
+/**
+ * Context for the renderEventStreamView plugin hook.
+ */
+type EventStreamViewRenderContext = {
+    config: AgentWidgetConfig;
+    events: SSEEventRecord[];
+    defaultRenderer: () => HTMLElement;
+    onClose?: () => void;
+};
+/**
+ * Context for the renderEventStreamRow plugin hook.
+ */
+type EventStreamRowRenderContext = {
+    event: SSEEventRecord;
+    index: number;
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    isExpanded: boolean;
+    onToggleExpand: () => void;
+};
+/**
+ * Context for the renderEventStreamToolbar plugin hook.
+ */
+type EventStreamToolbarRenderContext = {
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    eventCount: number;
+    filteredCount: number;
+    onFilterChange: (type: string) => void;
+    onSearchChange: (term: string) => void;
+};
+/**
+ * Context for the renderEventStreamPayload plugin hook.
+ */
+type EventStreamPayloadRenderContext = {
+    event: SSEEventRecord;
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    parsedPayload: unknown;
 };
 type AgentWidgetTheme = {
     primary?: string;
@@ -1386,6 +1601,41 @@ type AgentWidgetLoadingIndicatorConfig = {
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
+    /**
+     * Agent configuration for agent execution mode.
+     * When provided, the widget uses agent loop execution instead of flow dispatch.
+     * Mutually exclusive with `flowId`.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   agent: {
+     *     name: 'Assistant',
+     *     model: 'openai:gpt-4o-mini',
+     *     systemPrompt: 'You are a helpful assistant.',
+     *     loopConfig: { maxIterations: 3, stopCondition: 'auto' }
+     *   }
+     * }
+     * ```
+     */
+    agent?: AgentConfig;
+    /**
+     * Options for agent execution requests.
+     * Only used when `agent` is configured.
+     *
+     * @default { streamResponse: true, recordMode: 'virtual' }
+     */
+    agentOptions?: AgentRequestOptions;
+    /**
+     * Controls how multiple agent iterations are displayed in the chat UI.
+     * Only used when `agent` is configured.
+     *
+     * - `'separate'`: Each iteration creates a new assistant message bubble
+     * - `'merged'`: All iterations stream into a single assistant message
+     *
+     * @default 'separate'
+     */
+    iterationDisplay?: 'separate' | 'merged';
     /**
      * Client token for direct browser-to-API communication.
      * When set, the widget uses /v1/client/* endpoints instead of /v1/dispatch.
@@ -1921,6 +2171,11 @@ type AgentWidgetMessage = {
      * }
      */
     llmContent?: string;
+    /**
+     * Metadata for messages created during agent loop execution.
+     * Contains execution context like iteration number and turn ID.
+     */
+    agentMetadata?: AgentMessageMetadata;
 };
 /**
  * Options for injecting a message into the conversation.
@@ -2026,6 +2281,7 @@ type DispatchOptions = {
     assistantMessageId?: string;
 };
 type SSEHandler = (event: AgentWidgetEvent) => void;
+type SSEEventCallback = (eventType: string, payload: unknown) => void;
 declare class AgentWidgetClient {
     private config;
     private readonly apiUrl;
@@ -2037,13 +2293,22 @@ declare class AgentWidgetClient {
     private readonly customFetch?;
     private readonly parseSSEEvent?;
     private readonly getHeaders?;
+    private onSSEEvent?;
     private clientSession;
     private sessionInitPromise;
     constructor(config?: AgentWidgetConfig);
+    /**
+     * Set callback for capturing raw SSE events
+     */
+    setSSEEventCallback(callback: SSEEventCallback): void;
     /**
      * Check if running in client token mode
      */
     isClientTokenMode(): boolean;
+    /**
+     * Check if operating in agent execution mode
+     */
+    isAgentMode(): boolean;
     /**
      * Get the appropriate API URL based on mode
      */
@@ -2136,6 +2401,11 @@ declare class AgentWidgetClient {
      * Proxy mode dispatch (original implementation)
      */
     private dispatchProxy;
+    /**
+     * Agent mode dispatch
+     */
+    private dispatchAgent;
+    private buildAgentPayload;
     private buildPayload;
     /**
      * Handle custom SSE event parsing via parseSSEEvent callback
@@ -2162,11 +2432,28 @@ declare class AgentWidgetSession {
     private abortController;
     private sequenceCounter;
     private clientSession;
+    private agentExecution;
     constructor(config: AgentWidgetConfig | undefined, callbacks: SessionCallbacks);
+    /**
+     * Set callback for capturing raw SSE events (forwards to client)
+     */
+    setSSEEventCallback(callback: SSEEventCallback): void;
     /**
      * Check if running in client token mode
      */
     isClientTokenMode(): boolean;
+    /**
+     * Check if running in agent execution mode
+     */
+    isAgentMode(): boolean;
+    /**
+     * Get current agent execution state (if in agent mode)
+     */
+    getAgentExecution(): AgentExecutionState | null;
+    /**
+     * Check if an agent execution is currently running
+     */
+    isAgentExecuting(): boolean;
     /**
      * Initialize the client session (for client token mode).
      * This is called automatically on first message, but can be called
@@ -2291,6 +2578,10 @@ declare class AgentWidgetSession {
      * });
      */
     injectSystemMessage(options: InjectSystemMessageOptions): AgentWidgetMessage;
+    /**
+     * Inject multiple messages in a single batch with one sort and one render pass.
+     */
+    injectMessageBatch(optionsList: InjectMessageOptions[]): AgentWidgetMessage[];
     sendMessage(rawInput: string, options?: {
         viaVoice?: boolean;
         /** Multi-modal content parts (e.g., images) to include with the message */
@@ -2406,6 +2697,10 @@ type Controller = {
      * Convenience method for injecting system messages.
      */
     injectSystemMessage: (options: InjectSystemMessageOptions) => AgentWidgetMessage;
+    /**
+     * Inject multiple messages in a single batch with one sort and one render pass.
+     */
+    injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
     /**
      * @deprecated Use injectMessage() instead.
      */
@@ -2423,6 +2718,17 @@ type Controller = {
     showNPSFeedback: (options?: Partial<NPSFeedbackOptions>) => void;
     submitCSATFeedback: (rating: number, comment?: string) => Promise<void>;
     submitNPSFeedback: (rating: number, comment?: string) => Promise<void>;
+    /** Push a raw event into the event stream buffer (for testing/debugging) */
+    __pushEventStreamEvent: (event: {
+        type: string;
+        payload: unknown;
+    }) => void;
+    /** Opens the event stream panel */
+    showEventStream: () => void;
+    /** Closes the event stream panel */
+    hideEventStream: () => void;
+    /** Returns current visibility state of the event stream panel */
+    isEventStreamVisible: () => boolean;
 };
 declare const createAgentExperience: (mount: HTMLElement, initialConfig?: AgentWidgetConfig, runtimeOptions?: {
     debugTools?: boolean;
@@ -3179,4 +3485,4 @@ declare const getHeaderLayout: (layoutName: string) => HeaderLayoutRenderer;
  */
 declare const buildHeaderWithLayout: (config: AgentWidgetConfig, layoutConfig?: AgentWidgetHeaderLayoutConfig, context?: Partial<HeaderLayoutContext>) => HeaderElements;
 
-export { type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, 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 AgentWidgetTheme, type AgentWidgetTimestampConfig, AttachmentManager, type AttachmentManagerConfig, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateStandardBubbleOptions, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_WIDGET_CONFIG, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, type PendingAttachment, type SlotRenderContext, type SlotRenderer, type TextContentPart, VERSION, type WidgetLayoutSlot, attachHeaderToContainer, buildComposer, buildDefaultHeader, buildExpandedHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, componentRegistry, createActionManager, createAgentExperience, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDirectivePostprocessor, createFlexibleJsonStreamParser, createImagePart, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createRegexJsonParser, createStandardBubble, createTextPart, createTypingIndicator, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateUserMessageId, getDisplayText, getHeaderLayout, getImageParts, hasComponentDirective, hasImages, headerLayouts, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, normalizeContent, pluginRegistry, renderComponentDirective, renderLoadingIndicatorWithFallback, validateImageFile };
+export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentWidgetAgentRequestPayload, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, 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 AgentWidgetTheme, type AgentWidgetTimestampConfig, AttachmentManager, type AttachmentManagerConfig, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateStandardBubbleOptions, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_WIDGET_CONFIG, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, type PendingAttachment, type SSEEventCallback, type SSEEventRecord, type SlotRenderContext, type SlotRenderer, type TextContentPart, VERSION, type WidgetLayoutSlot, attachHeaderToContainer, buildComposer, buildDefaultHeader, buildExpandedHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, componentRegistry, createActionManager, createAgentExperience, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDirectivePostprocessor, createFlexibleJsonStreamParser, createImagePart, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createRegexJsonParser, createStandardBubble, createTextPart, createTypingIndicator, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateUserMessageId, getDisplayText, getHeaderLayout, getImageParts, hasComponentDirective, hasImages, headerLayouts, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, normalizeContent, pluginRegistry, renderComponentDirective, renderLoadingIndicatorWithFallback, validateImageFile };