@runtypelabs/persona 3.37.0 → 4.1.0

package/README.md

@@ -96,7 +96,6 @@ const docked = initAgentWidget({
 | `config` | `AgentWidgetConfig` | Widget configuration object (see the [Configuration Reference](./docs/CONFIGURATION-REFERENCE.md)). |
 | `useShadowDom` | `boolean` | Use Shadow DOM for style isolation (default: `false`). |
 | `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.
@@ -125,9 +124,9 @@ The full reference lives in [`docs/`](./docs/) and the theming guide:
 - [Code Generator](./docs/CODE-GENERATOR.md): `@runtypelabs/persona/codegen` options for CLI/server-side snippet generation
 - [THEME-CONFIG.md](./THEME-CONFIG.md): the complete theme and design-token reference
 
-### Optional proxy server
+### Optional Runtype proxy server
 
-The proxy server handles flow configuration and forwards requests to Runtype. You can configure it in three ways:
+The `@runtypelabs/persona-proxy` package handles flow configuration and forwards requests to Runtype. You can configure it in three ways:
 
 **Option 1: Use default flow (recommended for getting started)**
 
@@ -201,9 +200,9 @@ Add `RUNTYPE_API_KEY` to your environment. The proxy constructs the Runtype payl
 
 ### Development notes
 
-- The widget streams results using SSE and mirrors Runtype flow/agent events, including `step_await` local-tool pauses and `/resume` continuations.
+- The widget streams results using SSE and mirrors Persona's unified flow/agent events (which Runtype implements natively), including `await` local-tool pauses and `/resume` continuations.
 - Tailwind classes are prefixed with `tvw-` and scoped to `[data-persona-root]`, so they won't collide with the host page.
-- Run `pnpm dev` from the repository root to boot the example proxy (`examples/vercel-edge`) and the vanilla demo (`examples/embedded-app`).
+- Run `pnpm dev` from the repository root to boot the example Runtype proxy (`examples/vercel-edge`) and the vanilla demo (`apps/web`).
 - The proxy prefers port `43111` but automatically selects the next free port if needed.
 - `features.askUserQuestion.expose` and `features.suggestReplies.expose` advertise built-in LOCAL client tools through `clientTools[]`; leave `expose` off if the flow already declares those tools server-side.
 - `webmcp: { enabled: true }` snapshots page-registered tools on `document.modelContext`, sends them as `clientTools[]`, executes returned `webmcp:*` calls in the browser, and resumes the paused execution.

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

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

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

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

package/dist/animations/{types-DgYsuwXL.d.cts → types-B_xbfvR0.d.cts}

@@ -1,54 +1,77 @@
-type RuntypeAgentSSEEvent = {
-    agentId: string;
-    agentName: string;
-    config?: {
-        enableReflection?: boolean;
-        model?: string;
-    };
+type RuntypeExecutionStreamEvent = ({
+    agentId?: string;
+    agentName?: string;
+    config?: Record<string, unknown>;
     executionId: string;
-    maxTurns: number;
+    flowId?: string;
+    flowName?: string;
+    kind: "agent" | "flow";
+    maxTurns?: number;
     seq: number;
+    source?: string;
     startedAt: string;
-    type: "agent_start";
-} | {
+    totalSteps?: number;
+    type: "execution_start";
+}) | ({
+    completedAt?: string;
+    durationMs?: number;
     executionId: string;
-    iteration: number;
-    maxTurns: number;
+    failedSteps?: number;
+    finalOutput?: string;
+    iterations?: number;
+    kind: "agent" | "flow";
     seq: number;
-    startedAt: string;
+    stopReason?: string;
+    success: boolean;
+    successfulSteps?: number;
     totalCost?: number;
-    type: "agent_iteration_start";
-} | ({
+    totalSteps?: number;
+    totalTokens?: {
+        input: number;
+        output: number;
+    };
+    type: "execution_complete";
+}) | ({
+    code?: string;
+    completedAt?: string;
+    error: string | {
+        code: string;
+        details?: Record<string, unknown>;
+        message: string;
+    };
     executionId: string;
-    iteration: number;
-    role: "user" | "assistant" | "system";
+    kind: "agent" | "flow";
     seq: number;
-    turnId: string;
-    turnIndex: number;
-    type: "agent_turn_start";
+    type: "execution_error";
+    upgradeUrl?: string;
 }) | ({
-    contentType: "text" | "thinking" | "tool_input";
-    delta: string;
     executionId: string;
-    iteration: number;
+    id: string;
+    iteration?: number;
+    role: "user" | "assistant" | "system";
     seq: number;
-    turnId: string;
-    type: "agent_turn_delta";
+    turnIndex?: number;
+    type: "turn_start";
 }) | ({
-    completedAt: string;
+    completedAt?: string;
     content?: string;
     cost?: number;
-    estimatedContextBreakdown?: {
-        categories: Record<string, {
-            chars: number;
-            estimatedTokens: number;
+    executionId: string;
+    fallback?: {
+        attempts: Array<{
+            attempt: number;
+            error?: string;
+            model?: string;
+            success: boolean;
+            type: "retry" | "model" | "message" | "flow";
         }>;
-        contextWindowSize?: number;
-        estimatedTotalTokens: number;
-        estimatedUtilizationPercent?: number;
+        exhausted: boolean;
+        model?: string;
+        reason?: string | null;
+        used: boolean;
     };
-    executionId: string;
-    iteration: number;
+    id: string;
+    iteration?: number;
     role: "user" | "assistant" | "system";
     seq: number;
     stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
@@ -56,207 +79,260 @@ type RuntypeAgentSSEEvent = {
         input: number;
         output: number;
     };
-    turnId: string;
-    type: "agent_turn_complete";
+    type: "turn_complete";
+}) | {
+    executionId: string;
+    id: string;
+    index?: number;
+    name?: string;
+    outputVariable?: string;
+    seq: number;
+    startedAt?: string;
+    stepType?: string;
+    totalSteps?: number;
+    type: "step_start";
+} | ({
+    completedAt?: string;
+    durationMs?: number;
+    error?: string;
+    executionId: string;
+    fallback?: {
+        attempts: Array<{
+            attempt: number;
+            error?: string;
+            model?: string;
+            success: boolean;
+            type: "retry" | "model" | "message" | "flow";
+        }>;
+        exhausted: boolean;
+        model?: string;
+        reason?: string | null;
+        used: boolean;
+    };
+    id: string;
+    name?: string;
+    result?: unknown;
+    seq: number;
+    stepType?: string;
+    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
+    success?: boolean;
+    tokensUsed?: number;
+    type: "step_complete";
+    unresolvedVariables?: Array<string>;
+}) | {
+    executionId: string;
+    id: string;
+    index?: number;
+    name?: string;
+    seq: number;
+    skippedAt?: string;
+    stepType?: string;
+    totalSteps?: number;
+    type: "step_skip";
+    when?: string;
+} | ({
+    executionId: string;
+    id: string;
+    parentToolCallId?: string;
+    role?: "user" | "assistant" | "system";
+    seq: number;
+    stepId?: string;
+    turnId?: string;
+    type: "text_start";
+}) | {
+    delta: string;
+    executionId: string;
+    id: string;
+    seq: number;
+    type: "text_delta";
+} | {
+    executionId: string;
+    id: string;
+    seq: number;
+    text?: string;
+    type: "text_complete";
+} | ({
+    executionId: string;
+    id: string;
+    parentToolCallId?: string;
+    scope?: "turn" | "loop";
+    seq: number;
+    type: "reasoning_start";
+}) | {
+    delta: string;
+    executionId: string;
+    id: string;
+    seq: number;
+    type: "reasoning_delta";
+} | ({
+    executionId: string;
+    id: string;
+    scope?: "turn" | "loop";
+    seq: number;
+    text?: string;
+    type: "reasoning_complete";
 }) | ({
     executionId: string;
-    iteration: number;
+    id: string;
+    mediaType: string;
+    role?: "user" | "assistant" | "system";
+    seq: number;
+    toolCallId?: string;
+    type: "media_start";
+}) | {
+    delta: string;
+    executionId: string;
+    id: string;
+    seq: number;
+    type: "media_delta";
+} | {
+    data?: string;
+    executionId: string;
+    id: string;
+    mediaType?: string;
+    seq: number;
+    toolCallId?: string;
+    type: "media_complete";
+    url?: string;
+} | ({
+    artifactType: "markdown" | "component";
+    component?: string;
+    executionId?: string;
+    id: string;
+    seq?: number;
+    title?: string;
+    type: "artifact_start";
+}) | {
+    delta: string;
+    executionId?: string;
+    id: string;
+    seq?: number;
+    type: "artifact_delta";
+} | {
+    component: string;
+    executionId?: string;
+    id: string;
+    props: Record<string, unknown>;
+    seq?: number;
+    type: "artifact_update";
+} | {
+    executionId?: string;
+    id: string;
+    seq?: number;
+    type: "artifact_complete";
+} | {
+    executionId: string;
+    id?: string;
+    seq: number;
+    sourceType?: string;
+    title?: string;
+    type: "source";
+    url?: string;
+    [key: string]: unknown;
+} | ({
+    executionId: string;
+    hiddenParameterNames?: Array<string>;
+    iteration?: number;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
     parameters?: Record<string, unknown>;
     seq: number;
+    startedAt?: string;
+    stepId?: string;
     toolCallId: string;
     toolName: string;
-    toolType: "flow" | "mcp" | "builtin" | "custom" | "external" | "advisor" | "subagent" | "local";
-    type: "agent_tool_start";
+    toolType: string;
+    type: "tool_start";
 }) | {
     delta: string;
     executionId: string;
-    iteration: number;
     seq: number;
     toolCallId: string;
-    type: "agent_tool_delta";
+    type: "tool_input_delta";
 } | {
-    delta: string;
     executionId: string;
-    iteration: number;
+    hiddenParameterNames?: Array<string>;
+    parameters: Record<string, unknown>;
     seq: number;
     toolCallId: string;
-    type: "agent_tool_input_delta";
+    toolName?: string;
+    type: "tool_input_complete";
 } | {
+    delta: string;
     executionId: string;
-    hiddenParameterNames?: Array<string>;
-    iteration: number;
-    parameters: Record<string, unknown>;
     seq: number;
     toolCallId: string;
-    toolName: string;
-    type: "agent_tool_input_complete";
+    type: "tool_output_delta";
 } | {
+    error?: string;
     executionId: string;
     executionTime?: number;
-    iteration: number;
+    iteration?: number;
     result?: unknown;
     seq: number;
+    stepId?: string;
     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";
-}) | {
+    toolName?: string;
+    type: "tool_complete";
+} | {
     approvalId: string;
-    description: string;
+    description?: string;
     executionId: string;
-    externalAgent?: {
-        contextId?: string;
-        taskId?: string;
-    };
     iteration?: number;
     parameters?: Record<string, unknown>;
     reason?: string;
     seq: number;
-    startedAt: string;
-    timeout: number;
-    toolCallId: string;
+    startedAt?: string;
+    subagent?: {
+        agentName?: string;
+        toolName: string;
+    };
+    timeout?: number;
+    toolCallId?: string;
     toolName: string;
-    toolType: string;
-    type: "agent_approval_start";
+    toolType?: string;
+    type: "approval_start";
 } | ({
     approvalId: string;
-    completedAt: string;
+    completedAt?: string;
     decision: "approved" | "denied" | "timeout";
     executionId: string;
-    resolvedBy: "user" | "system";
+    resolvedBy?: "user" | "system";
     seq: number;
-    type: "agent_approval_complete";
+    type: "approval_complete";
 }) | ({
-    awaitedAt: string;
+    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;
-    timestamp?: string;
-    type: "agent_reflection";
-} | {
-    activatedCapabilities: Array<string>;
-    executionId: string;
-    iteration: number;
-    seq: number;
-    skill: string;
-    timestamp?: string;
-    toolCallId: string;
-    type: "agent_skill_loaded";
-} | ({
-    executionId: string;
-    iteration: number;
-    outcome: "pending_approval" | "auto_published";
-    proposalId?: string;
-    seq: number;
-    skill: string;
-    timestamp?: string;
-    toolCallId: string;
-    type: "agent_skill_proposed";
+    toolId?: string;
+    toolName?: string;
+    type: "await";
 }) | ({
-    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: {
+    error: string | {
         code: string;
         details?: Record<string, unknown>;
         message: string;
     };
     executionId: string;
-    iteration?: number;
-    recoverable: boolean;
+    recoverable?: boolean;
     seq: number;
-    timestamp?: string;
-    type: "agent_error";
-} | {
+    type: "error";
+}) | {
     executionId: string;
     seq: number;
     timestamp: string;
-    type: "agent_ping";
+    type: "ping";
+} | {
+    executionId?: string;
+    name: string;
+    seq?: number;
+    type: "custom";
+    value?: unknown;
 };
 type RuntypeFlowSSEEvent = {
     executionContext?: Record<string, unknown>;
@@ -554,9 +630,9 @@ type RuntypeFlowSSEEvent = {
 type RuntypeStreamEventOf<U, T extends string> = Extract<U, {
     type: T;
 }>;
-type RuntypeAgentTurnCompleteEvent = RuntypeStreamEventOf<RuntypeAgentSSEEvent, "agent_turn_complete">;
+type RuntypeTurnCompleteEvent = RuntypeStreamEventOf<RuntypeExecutionStreamEvent, "turn_complete">;
 type RuntypeStepCompleteEvent = RuntypeStreamEventOf<RuntypeFlowSSEEvent, "step_complete">;
-type RuntypeStopReasonKind = NonNullable<RuntypeAgentTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]>;
+type RuntypeStopReasonKind = NonNullable<RuntypeTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]>;
 
 /**
  * Text content part for multi-modal messages
@@ -752,6 +828,12 @@ type AgentWidgetReasoning = {
     id: string;
     status: "pending" | "streaming" | "complete";
     chunks: string[];
+    /**
+     * Reasoning channel scope (unified spec). `"turn"` is ordinary per-turn
+     * thinking; `"loop"` is a cross-iteration agent reflection (the fold that
+     * replaced the legacy `agent_reflection` event). Absent for legacy streams.
+     */
+    scope?: "turn" | "loop";
     startedAt?: number;
     completedAt?: number;
     durationMs?: number;