@runtypelabs/persona 3.37.0 → 4.0.0

package/dist/theme-editor.d.ts

@@ -749,57 +749,80 @@ interface AgentWidgetPlugin {
     onUnregister?: () => void;
 }
 
-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";
@@ -807,207 +830,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>;
@@ -1305,9 +1381,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
@@ -4421,6 +4497,11 @@ type AgentWidgetConfig = {
      * When provided, the widget uses agent loop execution instead of flow dispatch.
      * Mutually exclusive with `flowId`.
      *
+     * Note: `@runtypelabs/persona-proxy` rejects a client-supplied `agent` (it was
+     * an open relay). This option is only for endpoints authorized to accept a
+     * client agent — your own backend, or token-scoped direct-to-Runtype dispatch.
+     * For the proxy, pin the agent server-side with `agentConfig`/`agentId`.
+     *
      * @example
      * ```typescript
      * config: {
@@ -4891,16 +4972,6 @@ type AgentWidgetConfig = {
      * ```
      */
     parseSSEEvent?: AgentWidgetSSEEventParser;
-    /**
-     * Wire vocabulary requested from the dispatch endpoint.
-     * - `'legacy'` (default): the current `agent_*` / `flow_*` SSE events.
-     * - `'unified'`: opt into the API's neutral unified event vocabulary by sending
-     *   `?events=unified`; incoming frames are transparently bridged back to the same
-     *   handlers, so rendering is unchanged. Requires an upstream that honors the
-     *   param — the widget detects the actual wire mode from the first stream frame
-     *   and falls back to legacy automatically if the param was ignored.
-     */
-    events?: "legacy" | "unified";
     /**
      * Called for every parsed SSE frame (after JSON parse), before native handling.
      * Use for lightweight side effects (e.g. telemetry). Does not replace native
@@ -5080,6 +5151,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.37.0",
+  "version": "4.0.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",