@runtypelabs/persona 3.26.0 → 3.28.0

package/README.md

@@ -92,7 +92,8 @@ const docked = initAgentWidget({
 | `target` | `string \| HTMLElement` | CSS selector or element where widget mounts. |
 | `config` | `AgentWidgetConfig` | Widget configuration object (see [Configuration reference](#configuration-reference) below). |
 | `useShadowDom` | `boolean` | Use Shadow DOM for style isolation (default: `true`). |
-| `onReady` | `() => void` | Callback fired when widget is initialized. |
+| `onChatReady` | `() => void` | Callback fired when the widget is initialized and its API is callable. |
+| `onReady` | `() => void` | **Deprecated** alias of `onChatReady`; still works, removed in the next major. |
 | `windowKey` | `string` | If provided, stores the controller on `window[windowKey]` for global access. Automatically cleaned up on `destroy()`. |
 
 When `config.launcher.mountMode` is `'docked'`, `target` is treated as the page container that Persona should wrap. Use a concrete element such as `#workspace-main`; `body` and `html` are rejected.
@@ -354,7 +355,7 @@ window.chatController.submitMessage("Test message")
 window.chatController.startVoiceRecognition()
 ```
 
-When using the automatic installer script (`install.global.js`), see [Programmatic access with the installer](#programmatic-access-with-the-installer) for additional approaches including the `onReady` callback and `persona:ready` event.
+When using the automatic installer script (`install.global.js`), see [Programmatic access with the installer](#programmatic-access-with-the-installer) for additional approaches including the `onChatReady` callback and `persona:chat-ready` event.
 
 #### Message Types
 
@@ -619,19 +620,30 @@ window.dispatchEvent(new CustomEvent('persona:focusInput', {
 
 **Instance scoping:** Same as `persona:showEventStream` — use `detail.instanceId` to target a specific widget. Without `instanceId`, all instances receive the event.
 
-#### `persona:ready`
+#### `persona:chat-ready`
 
-Dispatched on `window` by the automatic installer script (`install.global.js`) after the widget is initialized. The `event.detail` contains the `AgentWidgetInitHandle` (the same object returned by `initAgentWidget()`).
+Dispatched on `window` by the automatic installer script (`install.global.js`) when the widget is initialized and its controller API is callable. The `event.detail` contains the `AgentWidgetInitHandle` (the same object returned by `initAgentWidget()`). In a deferred install (the default floating-launcher case) this fires after the user first opens the panel; in an eager install it fires on page load.
 
 ```ts
-window.addEventListener('persona:ready', (e) => {
+window.addEventListener('persona:chat-ready', (e) => {
   const handle = e.detail;
   handle.on('message:sent', (msg) => console.log(msg));
   handle.open();
 });
 ```
 
-> **Note:** This event is only dispatched by the automatic installer script. Direct calls to `initAgentWidget()` return the handle synchronously and do not fire this event.
+The installer also dispatches sibling lifecycle events for diagnostics and analytics:
+
+| Event | `detail` | Fires |
+| --- | --- | --- |
+| `persona:script-load` | `{ version }` | the installer script executed (before any loading) |
+| `persona:launcher-shown` | `{ deferred, element? }` | the floating launcher painted on the page (page-load time) |
+| `persona:chat-ready` | the widget handle | the widget is initialized and its API is callable |
+| `persona:error` | `{ phase, error }` | a load step (`css` / `bundle` / `init`) failed |
+
+> **Note:** These events are only dispatched by the automatic installer script. Direct calls to `initAgentWidget()` return the handle synchronously and do not fire them.
+>
+> `persona:ready` is still dispatched as a **deprecated** alias of `persona:chat-ready` and will be removed in the next major.
 
 ### Controller Events
 
@@ -1553,7 +1565,11 @@ The easiest way is to use the automatic installer script. It handles loading CSS
 - `previewQueryParam` - Query parameter key that gates widget loading; widget only loads when the parameter is present and truthy
 - `useShadowDom` - Use Shadow DOM for style isolation (default: `false`)
 - `windowKey` - If provided, stores the widget handle on `window[windowKey]` for programmatic access
-- `onReady` - Callback fired with the widget handle after initialization; signature: `(handle) => void`
+- `onScriptLoad` - Fired as soon as the installer script executes, before it loads or gates anything (diagnostics / timing); signature: `({ version }) => void`
+- `onLauncherShown` - Fired when the floating launcher is painted on the page (page-load time — for "widget appeared" analytics); signature: `({ deferred, element? }) => void`
+- `onChatReady` - Fired when the widget is initialized and its controller API is callable (after first open in a deferred install); signature: `(handle) => void`
+- `onError` - Fired when a load step fails (`css` / `bundle` / `init`), so ad-blocked / timed-out installs don't fail silently; signature: `({ phase, error }) => void`
+- `onReady` - **Deprecated** alias of `onChatReady`; still works, removed in the next major; signature: `(handle) => void`
 
 **Example with version pinning:**
 
@@ -1574,14 +1590,14 @@ The easiest way is to use the automatic installer script. It handles loading CSS
 
 The installer is fully asynchronous (it waits for framework hydration, then loads CSS and JS). To interact with the widget after it initializes, use one of these approaches:
 
-**`onReady` callback** — best when config and access logic live in the same script:
+**`onChatReady` callback** — best when config and access logic live in the same script:
 
 ```html
 <script>
   window.siteAgentConfig = {
     clientToken: 'YOUR_TOKEN',
     windowKey: 'myChat',
-    onReady(handle) {
+    onChatReady(handle) {
       handle.on('message:sent', (e) => console.log('sent:', e));
       handle.on('message:received', (e) => console.log('received:', e));
     }
@@ -1590,11 +1606,11 @@ The installer is fully asynchronous (it waits for framework hydration, then load
 <script src="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@latest/dist/install.global.js"></script>
 ```
 
-**`persona:ready` event** — best for decoupled integration (e.g. tag managers, separate scripts):
+**`persona:chat-ready` event** — best for decoupled integration (e.g. tag managers, separate scripts):
 
 ```html
 <script>
-  window.addEventListener('persona:ready', (e) => {
+  window.addEventListener('persona:chat-ready', (e) => {
     const handle = e.detail;
     handle.on('message:sent', (e) => console.log('sent:', e));
   });
@@ -1607,7 +1623,7 @@ The installer is fully asynchronous (it waits for framework hydration, then load
 <script src="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@latest/dist/install.global.js"></script>
 ```
 
-**`windowKey`** — stores the handle on `window[windowKey]` for persistent global access. Combine with `onReady` or `persona:ready` to know when it's available:
+**`windowKey`** — stores the handle on `window[windowKey]` for persistent global access. Combine with `onChatReady` or `persona:chat-ready` to know when it's available:
 
 ```html
 <script>
@@ -1619,7 +1635,7 @@ The installer is fully asynchronous (it waits for framework hydration, then load
 <script src="https://cdn.jsdelivr.net/npm/@runtypelabs/persona@latest/dist/install.global.js"></script>
 
 <script>
-  window.addEventListener('persona:ready', () => {
+  window.addEventListener('persona:chat-ready', () => {
     // window.myChat is now available and persists until destroy()
     window.myChat.open();
   });

package/dist/animations/glyph-cycle.d.cts

@@ -1,4 +1,4 @@
-import { S as StreamAnimationPlugin } from './types-BZVr1YOV.cjs';
+import { S as StreamAnimationPlugin } from './types-CxvHw0X6.cjs';
 
 declare const glyphCycle: StreamAnimationPlugin;
 

package/dist/animations/glyph-cycle.d.ts

@@ -1,4 +1,4 @@
-import { S as StreamAnimationPlugin } from './types-BZVr1YOV.js';
+import { S as StreamAnimationPlugin } from './types-CxvHw0X6.js';
 
 declare const glyphCycle: StreamAnimationPlugin;
 

package/dist/animations/{types-BZVr1YOV.d.cts → types-CxvHw0X6.d.cts}

@@ -1,3 +1,553 @@
+type RuntypeAgentSSEEvent = {
+    agentId: string;
+    agentName: string;
+    config?: {
+        enableReflection?: boolean;
+        model?: string;
+    };
+    executionId: string;
+    maxTurns: number;
+    seq: number;
+    startedAt: string;
+    type: "agent_start";
+} | {
+    executionId: string;
+    iteration: number;
+    maxTurns: number;
+    seq: number;
+    startedAt: string;
+    totalCost?: number;
+    type: "agent_iteration_start";
+} | ({
+    executionId: string;
+    iteration: number;
+    role: "user" | "assistant" | "system";
+    seq: number;
+    turnId: string;
+    turnIndex: number;
+    type: "agent_turn_start";
+}) | ({
+    contentType: "text" | "thinking" | "tool_input";
+    delta: string;
+    executionId: string;
+    iteration: number;
+    seq: number;
+    turnId: string;
+    type: "agent_turn_delta";
+}) | ({
+    completedAt: string;
+    content?: string;
+    cost?: number;
+    estimatedContextBreakdown?: {
+        categories: Record<string, {
+            chars: number;
+            estimatedTokens: number;
+        }>;
+        contextWindowSize?: number;
+        estimatedTotalTokens: number;
+        estimatedUtilizationPercent?: number;
+    };
+    executionId: string;
+    iteration: number;
+    role: "user" | "assistant" | "system";
+    seq: number;
+    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    turnId: string;
+    type: "agent_turn_complete";
+}) | ({
+    executionId: string;
+    iteration: number;
+    origin?: "webmcp" | "sdk";
+    pageOrigin?: string;
+    parameters?: Record<string, unknown>;
+    seq: number;
+    toolCallId: string;
+    toolName: string;
+    toolType: "flow" | "mcp" | "builtin" | "custom" | "external" | "advisor" | "subagent" | "local";
+    type: "agent_tool_start";
+}) | {
+    delta: string;
+    executionId: string;
+    iteration: number;
+    seq: number;
+    toolCallId: string;
+    type: "agent_tool_delta";
+} | {
+    delta: string;
+    executionId: string;
+    iteration: number;
+    seq: number;
+    toolCallId: string;
+    type: "agent_tool_input_delta";
+} | {
+    executionId: string;
+    hiddenParameterNames?: Array<string>;
+    iteration: number;
+    parameters: Record<string, unknown>;
+    seq: number;
+    toolCallId: string;
+    toolName: string;
+    type: "agent_tool_input_complete";
+} | {
+    executionId: string;
+    executionTime?: number;
+    iteration: number;
+    result?: unknown;
+    seq: number;
+    success: boolean;
+    toolCallId: string;
+    toolName: string;
+    type: "agent_tool_complete";
+} | ({
+    executionId?: string;
+    iteration: number;
+    media: Array<({
+        annotations?: {
+            audience?: Array<"user" | "assistant">;
+        };
+        data: string;
+        mediaType: string;
+        type: "media";
+    }) | ({
+        annotations?: {
+            audience?: Array<"user" | "assistant">;
+        };
+        mediaType?: string;
+        type: "image-url";
+        url: string;
+    }) | ({
+        annotations?: {
+            audience?: Array<"user" | "assistant">;
+        };
+        mediaType: string;
+        type: "file-url";
+        url: string;
+    })>;
+    seq?: number;
+    toolCallId: string;
+    toolName: string;
+    type: "agent_media";
+}) | {
+    approvalId: string;
+    description: string;
+    executionId: string;
+    externalAgent?: {
+        contextId?: string;
+        taskId?: string;
+    };
+    iteration?: number;
+    parameters?: Record<string, unknown>;
+    seq: number;
+    startedAt: string;
+    timeout: number;
+    toolCallId: string;
+    toolName: string;
+    toolType: string;
+    type: "agent_approval_start";
+} | ({
+    approvalId: string;
+    completedAt: string;
+    decision: "approved" | "denied" | "timeout";
+    executionId: string;
+    resolvedBy: "user" | "system";
+    seq: number;
+    type: "agent_approval_complete";
+}) | ({
+    awaitedAt: string;
+    executionId: string;
+    origin?: "webmcp" | "sdk";
+    pageOrigin?: string;
+    parameters?: Record<string, unknown>;
+    seq: number;
+    toolCallId?: string;
+    toolId: string;
+    toolName: string;
+    type: "agent_await";
+}) | {
+    completedAt: string;
+    cost?: number;
+    duration?: number;
+    estimatedContextBreakdown?: {
+        categories: Record<string, {
+            chars: number;
+            estimatedTokens: number;
+        }>;
+        contextWindowSize?: number;
+        estimatedTotalTokens: number;
+        estimatedUtilizationPercent?: number;
+    };
+    executionId: string;
+    iteration: number;
+    output?: string;
+    runningTotalCost?: number;
+    seq: number;
+    stopConditionMet: boolean;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    toolCallsMade: number;
+    type: "agent_iteration_complete";
+} | {
+    executionId: string;
+    iteration: number;
+    reflection?: string;
+    seq: number;
+    type: "agent_reflection";
+} | {
+    activatedCapabilities: Array<string>;
+    executionId: string;
+    iteration: number;
+    seq: number;
+    skill: string;
+    toolCallId: string;
+    type: "agent_skill_loaded";
+} | ({
+    executionId: string;
+    iteration: number;
+    outcome: "pending_approval" | "auto_published";
+    proposalId?: string;
+    seq: number;
+    skill: string;
+    toolCallId: string;
+    type: "agent_skill_proposed";
+}) | ({
+    agentId: string;
+    completedAt: string;
+    duration?: number;
+    error?: string;
+    executionId: string;
+    externalAgent?: {
+        contextId?: string;
+        taskId?: string;
+    };
+    finalOutput?: string;
+    iterations: number;
+    seq: number;
+    stopReason: "complete" | "end_turn" | "max_turns" | "max_cost" | "timeout" | "error";
+    success: boolean;
+    totalCost?: number;
+    totalTokens?: {
+        input: number;
+        output: number;
+    };
+    type: "agent_complete";
+}) | {
+    error: {
+        code: string;
+        details?: Record<string, unknown>;
+        message: string;
+    };
+    executionId: string;
+    iteration?: number;
+    recoverable: boolean;
+    seq: number;
+    type: "agent_error";
+} | {
+    executionId: string;
+    seq: number;
+    timestamp: string;
+    type: "agent_ping";
+};
+type RuntypeFlowSSEEvent = {
+    executionContext?: Record<string, unknown>;
+    executionId?: string;
+    flowId: string;
+    flowName?: string;
+    input?: unknown;
+    seq?: number;
+    source?: string;
+    startedAt: string;
+    toolContext?: {
+        executionId: string;
+        stepId: string;
+        toolId: string;
+    };
+    totalSteps?: number;
+    type: "flow_start";
+} | {
+    completedAt?: string;
+    completedSteps?: number;
+    duration?: number;
+    executionContext?: Record<string, unknown>;
+    executionId?: string;
+    executionTime?: number;
+    failedSteps?: number;
+    finalOutput?: string;
+    flowId?: string;
+    output?: unknown;
+    seq?: number;
+    source?: string;
+    success?: boolean;
+    successfulSteps?: number;
+    toolContext?: {
+        executionId: string;
+        stepId: string;
+        toolId: string;
+    };
+    totalSteps?: number;
+    totalTokensUsed?: number;
+    type: "flow_complete";
+} | ({
+    code?: string;
+    error: string | {
+        code: string;
+        message: string;
+        stepId?: string;
+        stepType?: string;
+    };
+    executionId?: string;
+    executionTime?: number;
+    flowId?: string;
+    seq?: number;
+    timestamp?: string;
+    toolContext?: {
+        executionId: string;
+        stepId: string;
+        toolId: string;
+    };
+    type: "flow_error";
+    upgradeUrl?: string;
+}) | ({
+    awaitedAt: string;
+    executionId?: string;
+    flowId: string;
+    origin?: "webmcp" | "sdk";
+    pageOrigin?: string;
+    parameters?: Record<string, unknown>;
+    seq?: number;
+    toolCallId?: string;
+    toolId?: string;
+    toolName?: string;
+    type: "flow_await";
+}) | {
+    estimatedTokens?: number;
+    executionId?: string;
+    id?: string;
+    index?: number;
+    name?: string;
+    seq?: number;
+    startedAt: string;
+    stepId?: string;
+    stepName?: string;
+    stepType?: string;
+    toolContext?: {
+        executionId: string;
+        stepId: string;
+        toolId: string;
+    };
+    totalSteps?: number;
+    type: "step_start";
+} | {
+    delta?: string;
+    executionId?: string;
+    id?: string;
+    messageId?: string;
+    partId?: string;
+    seq?: number;
+    text?: string;
+    toolContext?: {
+        executionId: string;
+        stepId: string;
+        toolId: string;
+    };
+    toolId?: string;
+    type: "step_delta";
+} | ({
+    completedAt?: string;
+    duration?: number;
+    durationMs?: number;
+    error?: string;
+    executionId?: string;
+    executionTime?: number;
+    id?: string;
+    index?: number;
+    name?: string;
+    output?: unknown;
+    result?: unknown;
+    seq?: number;
+    stepId?: string;
+    stepName?: string;
+    stepType?: string;
+    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
+    success?: boolean;
+    tokensUsed?: number;
+    toolContext?: {
+        executionId: string;
+        stepId: string;
+        toolId: string;
+    };
+    type: "step_complete";
+}) | {
+    error: string;
+    executionId?: string;
+    executionTime?: number;
+    id?: string;
+    index?: number;
+    name?: string;
+    seq?: number;
+    stepType?: string;
+    type: "step_error";
+} | {
+    error?: string;
+    executionId?: string;
+    id: string;
+    index?: number;
+    name?: string;
+    seq?: number;
+    skippedAt: string;
+    stepType: string;
+    totalSteps: number;
+    type: "step_skip";
+    when: string;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "step_await";
+    [key: string]: unknown;
+} | ({
+    agentContext?: {
+        executionId: string;
+        iteration: number;
+        seq: number;
+    };
+    executionId?: string;
+    hiddenParameterNames?: Array<string>;
+    name?: string;
+    parameters?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+    seq?: number;
+    startedAt?: string;
+    stepId?: string;
+    toolCallId?: string;
+    toolId?: string;
+    toolName?: string;
+    toolType: "flow" | "mcp" | "builtin" | "custom" | "external" | "advisor" | "subagent" | "local";
+    type: "tool_start";
+    [key: string]: unknown;
+}) | {
+    delta?: string;
+    executionId?: string;
+    seq?: number;
+    toolId?: string;
+    type: "tool_delta";
+    [key: string]: unknown;
+} | {
+    delta: string;
+    executionId?: string;
+    seq?: number;
+    stepId?: string;
+    toolCallId?: string;
+    toolId?: string;
+    type: "tool_input_delta";
+} | {
+    executionId?: string;
+    hiddenParameterNames?: Array<string>;
+    parameters: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+    seq?: number;
+    stepId?: string;
+    toolCallId?: string;
+    toolId?: string;
+    toolName?: string;
+    type: "tool_input_complete";
+} | {
+    agentContext?: {
+        executionId: string;
+        iteration: number;
+        seq: number;
+    };
+    completedAt?: string;
+    error?: string;
+    executionId?: string;
+    executionTime?: number;
+    name?: string;
+    result?: unknown;
+    seq?: number;
+    stepId?: string;
+    success: boolean;
+    toolCallId?: string;
+    toolCost?: number;
+    toolId?: string;
+    toolName?: string;
+    type: "tool_complete";
+} | {
+    agentContext?: {
+        executionId: string;
+        iteration: number;
+        seq: number;
+    };
+    error: string;
+    executionId?: string;
+    executionTime?: number;
+    failedAt?: string;
+    name: string;
+    seq?: number;
+    toolId: string;
+    type: "tool_error";
+} | {
+    executionId?: string;
+    id: string;
+    seq?: number;
+    text: string;
+    type: "chunk";
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "text_start";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "text_end";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "reason_start";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "reason_delta";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "reason_complete";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "source";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "fallback_start";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "fallback_complete";
+    [key: string]: unknown;
+} | {
+    executionId?: string;
+    seq?: number;
+    type: "fallback_exhausted";
+    [key: string]: unknown;
+};
+type RuntypeStreamEventOf<U, T extends string> = Extract<U, {
+    type: T;
+}>;
+type RuntypeAgentTurnCompleteEvent = RuntypeStreamEventOf<RuntypeAgentSSEEvent, "agent_turn_complete">;
+type RuntypeStepCompleteEvent = RuntypeStreamEventOf<RuntypeFlowSSEEvent, "step_complete">;
+type RuntypeStopReasonKind = NonNullable<RuntypeAgentTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]>;
+
 /**
  * Text content part for multi-modal messages
  */
@@ -232,7 +782,7 @@ type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval"
  *
  * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
  */
-type StopReasonKind = 'end_turn' | 'max_tool_calls' | 'length' | 'content_filter' | 'error' | 'unknown';
+type StopReasonKind = RuntypeStopReasonKind;
 /**
  * Represents a message in the chat conversation.
  *