@runtypelabs/persona 4.5.0 → 4.6.1

package/dist/theme-editor.d.cts

@@ -783,6 +783,7 @@ type RuntypeExecutionStreamEvent = ({
     };
     type: "execution_complete";
 }) | ({
+    blockReason?: string;
     code?: string;
     completedAt?: string;
     error: string | {
@@ -1037,6 +1038,7 @@ type RuntypeExecutionStreamEvent = ({
     startedAt?: string;
     subagent?: {
         agentName?: string;
+        parentToolCallId?: string;
         toolName: string;
     };
     timeout?: number;
@@ -1053,12 +1055,15 @@ type RuntypeExecutionStreamEvent = ({
     seq: number;
     type: "approval_complete";
 }) | ({
+    awaitReason?: string;
     awaitedAt?: string;
+    crawlId?: string;
     executionId: string;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
     parameters?: Record<string, unknown>;
     seq: number;
+    stepId?: string;
     toolCallId?: string;
     toolId?: string;
     toolName?: string;
@@ -1127,6 +1132,7 @@ type RuntypeFlowSSEEvent = {
     totalTokensUsed?: number;
     type: "flow_complete";
 } | ({
+    blockReason?: string;
     code?: string;
     error: string | {
         code: string;
@@ -1147,13 +1153,18 @@ type RuntypeFlowSSEEvent = {
     type: "flow_error";
     upgradeUrl?: string;
 }) | ({
+    approvalId?: string;
+    awaitReason?: string;
     awaitedAt: string;
+    crawlId?: string;
     executionId?: string;
     flowId: string;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
     parameters?: Record<string, unknown>;
     seq?: number;
+    stepId?: string;
+    timeout?: number;
     toolCallId?: string;
     toolId?: string;
     toolName?: string;
@@ -1693,6 +1704,27 @@ type AgentWidgetWebMcpConfig = {
      */
     onConfirm?: WebMcpConfirmHandler;
 };
+/**
+ * The coordinates needed to resume a durable agent turn after the SSE
+ * connection drops (any resumable, server-persisted execution, e.g. Claude
+ * Managed agents or async/background runs). Held on the session while a
+ * resumable stream is in flight
+ * and surfaced to the host via {@link AgentWidgetConfig.onExecutionState} so it
+ * can persist `{ executionId, lastEventId }` next to its own `conversationId`
+ * for the tab-reload path.
+ *
+ * `conversationId` is intentionally absent: it is host-owned (it lives in the
+ * host's `reconnectStream`/`customFetch` closure; the widget never sees it).
+ */
+type ResumableHandle = {
+    /** The durable turn to reconnect to (from `agentMetadata.executionId`). */
+    executionId: string;
+    /** Highest SSE `id:` seq applied: the `?after=` reconnect cursor. */
+    lastEventId: string;
+    /** The open assistant message being streamed into, kept open on resume. */
+    assistantMessageId: string;
+    status: 'running';
+};
 /**
  * Metadata attached to messages created during agent execution.
  */
@@ -3009,6 +3041,10 @@ type AgentWidgetStatusIndicatorConfig = {
     connectingText?: string;
     connectedText?: string;
     errorText?: string;
+    /** Status text while a dropped durable stream is awaiting reconnect. */
+    pausedText?: string;
+    /** Status text while a reconnect attempt is in flight. */
+    resumingText?: string;
 };
 type AgentWidgetVoiceRecognitionConfig = {
     enabled?: boolean;
@@ -5090,6 +5126,65 @@ type AgentWidgetConfig = {
      * ```
      */
     customFetch?: AgentWidgetCustomFetch;
+    /**
+     * Durable-session reconnect transport (host-owned, symmetric to
+     * {@link customFetch}). When a durable agent stream drops mid-turn (any
+     * resumable, server-persisted execution, e.g. Claude Managed agents or
+     * async/background runs), the widget calls this to fetch the read-only
+     * reconnect stream and pipes its body through the normal event pipeline to
+     * resume from where it left off.
+     *
+     * The host closure owns `agentId` / `conversationId` / base URL / auth and
+     * builds the events request, e.g.:
+     *
+     * ```typescript
+     * reconnectStream: ({ executionId, after, signal }) =>
+     *   fetch(
+     *     `${baseUrl}/v1/agents/${agentId}/executions/${executionId}` +
+     *       `/events?conversationId=${conversationId}&after=${after}`,
+     *     { headers: { Authorization: `Bearer ${token}`, "X-Persona-Version": ver }, signal }
+     *   )
+     * ```
+     *
+     * Resolve with a `text/event-stream` `Response`. Throw or resolve non-ok to
+     * signal "this attempt failed" (the widget backs off and retries, then gives
+     * up after the bounded attempts). Reconnect only ever arms on the durable
+     * lane (streams carrying SSE `id:` lines); without this hook a drop finalizes
+     * exactly as before.
+     */
+    reconnectStream?: (ctx: {
+        executionId: string;
+        after: string;
+        signal: AbortSignal;
+    }) => Promise<Response>;
+    /**
+     * Tuning for the auto-reconnect backoff. Defaults to ~5 attempts over ~30s
+     * (`backoffMs: [1000, 2000, 4000, 8000, 8000]`).
+     */
+    reconnect?: {
+        /** Max reconnect attempts before giving up and finalizing. @default backoffMs.length */
+        maxAttempts?: number;
+        /** Per-attempt delay (ms) before each retry. @default [1000, 2000, 4000, 8000, 8000] */
+        backoffMs?: number[];
+    };
+    /**
+     * Called whenever the durable resume handle changes: created when a durable
+     * turn starts streaming, updated as the cursor advances (throttled), and
+     * `null` when the turn finishes, errors, or is torn down. Persist
+     * `{ executionId, lastEventId }` next to your `conversationId` and pass it
+     * back via {@link resume} on the next mount to survive a tab reload.
+     */
+    onExecutionState?: (handle: ResumableHandle | null) => void;
+    /**
+     * Resume a durable turn on boot (tab-reload path). When present alongside
+     * {@link reconnectStream}, the widget enters `resuming` immediately on mount
+     * and reconnects from `after`, replaying everything past the cursor into the
+     * restored conversation.
+     */
+    resume?: {
+        executionId: string;
+        after: string;
+    };
     /**
      * Custom SSE event parser for non-standard streaming response formats.
      *

package/dist/theme-editor.d.ts

@@ -783,6 +783,7 @@ type RuntypeExecutionStreamEvent = ({
     };
     type: "execution_complete";
 }) | ({
+    blockReason?: string;
     code?: string;
     completedAt?: string;
     error: string | {
@@ -1037,6 +1038,7 @@ type RuntypeExecutionStreamEvent = ({
     startedAt?: string;
     subagent?: {
         agentName?: string;
+        parentToolCallId?: string;
         toolName: string;
     };
     timeout?: number;
@@ -1053,12 +1055,15 @@ type RuntypeExecutionStreamEvent = ({
     seq: number;
     type: "approval_complete";
 }) | ({
+    awaitReason?: string;
     awaitedAt?: string;
+    crawlId?: string;
     executionId: string;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
     parameters?: Record<string, unknown>;
     seq: number;
+    stepId?: string;
     toolCallId?: string;
     toolId?: string;
     toolName?: string;
@@ -1127,6 +1132,7 @@ type RuntypeFlowSSEEvent = {
     totalTokensUsed?: number;
     type: "flow_complete";
 } | ({
+    blockReason?: string;
     code?: string;
     error: string | {
         code: string;
@@ -1147,13 +1153,18 @@ type RuntypeFlowSSEEvent = {
     type: "flow_error";
     upgradeUrl?: string;
 }) | ({
+    approvalId?: string;
+    awaitReason?: string;
     awaitedAt: string;
+    crawlId?: string;
     executionId?: string;
     flowId: string;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
     parameters?: Record<string, unknown>;
     seq?: number;
+    stepId?: string;
+    timeout?: number;
     toolCallId?: string;
     toolId?: string;
     toolName?: string;
@@ -1693,6 +1704,27 @@ type AgentWidgetWebMcpConfig = {
      */
     onConfirm?: WebMcpConfirmHandler;
 };
+/**
+ * The coordinates needed to resume a durable agent turn after the SSE
+ * connection drops (any resumable, server-persisted execution, e.g. Claude
+ * Managed agents or async/background runs). Held on the session while a
+ * resumable stream is in flight
+ * and surfaced to the host via {@link AgentWidgetConfig.onExecutionState} so it
+ * can persist `{ executionId, lastEventId }` next to its own `conversationId`
+ * for the tab-reload path.
+ *
+ * `conversationId` is intentionally absent: it is host-owned (it lives in the
+ * host's `reconnectStream`/`customFetch` closure; the widget never sees it).
+ */
+type ResumableHandle = {
+    /** The durable turn to reconnect to (from `agentMetadata.executionId`). */
+    executionId: string;
+    /** Highest SSE `id:` seq applied: the `?after=` reconnect cursor. */
+    lastEventId: string;
+    /** The open assistant message being streamed into, kept open on resume. */
+    assistantMessageId: string;
+    status: 'running';
+};
 /**
  * Metadata attached to messages created during agent execution.
  */
@@ -3009,6 +3041,10 @@ type AgentWidgetStatusIndicatorConfig = {
     connectingText?: string;
     connectedText?: string;
     errorText?: string;
+    /** Status text while a dropped durable stream is awaiting reconnect. */
+    pausedText?: string;
+    /** Status text while a reconnect attempt is in flight. */
+    resumingText?: string;
 };
 type AgentWidgetVoiceRecognitionConfig = {
     enabled?: boolean;
@@ -5090,6 +5126,65 @@ type AgentWidgetConfig = {
      * ```
      */
     customFetch?: AgentWidgetCustomFetch;
+    /**
+     * Durable-session reconnect transport (host-owned, symmetric to
+     * {@link customFetch}). When a durable agent stream drops mid-turn (any
+     * resumable, server-persisted execution, e.g. Claude Managed agents or
+     * async/background runs), the widget calls this to fetch the read-only
+     * reconnect stream and pipes its body through the normal event pipeline to
+     * resume from where it left off.
+     *
+     * The host closure owns `agentId` / `conversationId` / base URL / auth and
+     * builds the events request, e.g.:
+     *
+     * ```typescript
+     * reconnectStream: ({ executionId, after, signal }) =>
+     *   fetch(
+     *     `${baseUrl}/v1/agents/${agentId}/executions/${executionId}` +
+     *       `/events?conversationId=${conversationId}&after=${after}`,
+     *     { headers: { Authorization: `Bearer ${token}`, "X-Persona-Version": ver }, signal }
+     *   )
+     * ```
+     *
+     * Resolve with a `text/event-stream` `Response`. Throw or resolve non-ok to
+     * signal "this attempt failed" (the widget backs off and retries, then gives
+     * up after the bounded attempts). Reconnect only ever arms on the durable
+     * lane (streams carrying SSE `id:` lines); without this hook a drop finalizes
+     * exactly as before.
+     */
+    reconnectStream?: (ctx: {
+        executionId: string;
+        after: string;
+        signal: AbortSignal;
+    }) => Promise<Response>;
+    /**
+     * Tuning for the auto-reconnect backoff. Defaults to ~5 attempts over ~30s
+     * (`backoffMs: [1000, 2000, 4000, 8000, 8000]`).
+     */
+    reconnect?: {
+        /** Max reconnect attempts before giving up and finalizing. @default backoffMs.length */
+        maxAttempts?: number;
+        /** Per-attempt delay (ms) before each retry. @default [1000, 2000, 4000, 8000, 8000] */
+        backoffMs?: number[];
+    };
+    /**
+     * Called whenever the durable resume handle changes: created when a durable
+     * turn starts streaming, updated as the cursor advances (throttled), and
+     * `null` when the turn finishes, errors, or is torn down. Persist
+     * `{ executionId, lastEventId }` next to your `conversationId` and pass it
+     * back via {@link resume} on the next mount to survive a tab reload.
+     */
+    onExecutionState?: (handle: ResumableHandle | null) => void;
+    /**
+     * Resume a durable turn on boot (tab-reload path). When present alongside
+     * {@link reconnectStream}, the widget enters `resuming` immediately on mount
+     * and reconnects from `after`, replaying everything past the cursor into the
+     * restored conversation.
+     */
+    resume?: {
+        executionId: string;
+        after: string;
+    };
     /**
      * Custom SSE event parser for non-standard streaming response formats.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.5.0",
+  "version": "4.6.1",
   "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",
@@ -79,6 +79,7 @@
   },
   "devDependencies": {
     "@size-limit/file": "^12.1.0",
+    "acorn": "^8.15.0",
     "@types/node": "^20.12.7",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
@@ -120,11 +121,12 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf dist && pnpm run build:styles && pnpm run build:markdown-parsers && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:runtype-tts && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:theme-editor-preview && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:voice-worklet-player && pnpm run build:plugin-kit && pnpm run build:animations",
+    "build": "rimraf dist && pnpm run build:styles && pnpm run build:markdown-parsers && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:webmcp-polyfill && pnpm run build:runtype-tts && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:theme-editor-preview && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:voice-worklet-player && pnpm run build:plugin-kit && pnpm run build:animations && pnpm run check:dist-vite8",
+    "check:dist-vite8": "node scripts/check-dist-no-in-for-init.mjs",
     "build:markdown-parsers": "tsup --config tsup.markdown-parsers.config.ts",
     "build:plugin-kit": "tsup src/plugin-kit.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
-    "build:theme-editor-preview": "tsup src/theme-editor-preview.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:theme-editor-preview": "tsup src/theme-editor-preview.ts --format esm,cjs --minify --dts --out-dir dist",
     "build:testing": "tsup src/testing.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:voice-worklet-player": "tsup src/voice-worklet-player.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",

package/src/client.ts

@@ -954,11 +954,12 @@ export class AgentWidgetClient {
   public async processStream(
     body: ReadableStream<Uint8Array>,
     onEvent: SSEHandler,
-    assistantMessageId?: string
+    assistantMessageId?: string,
+    seedContent?: string
   ): Promise<void> {
     onEvent({ type: "status", status: "connected" });
     try {
-      await this.streamResponse(body, onEvent, assistantMessageId);
+      await this.streamResponse(body, onEvent, assistantMessageId, seedContent);
     } finally {
       onEvent({ type: "status", status: "idle" });
     }
@@ -1353,7 +1354,12 @@ export class AgentWidgetClient {
   private async streamResponse(
     body: ReadableStream<Uint8Array>,
     onEvent: SSEHandler,
-    assistantMessageId?: string
+    assistantMessageId?: string,
+    // Durable reconnect: seed the assistant accumulator with the text already
+    // shown before the drop, so replayed post-cursor deltas APPEND to it
+    // instead of a fresh stream clobbering it (the replay carries only
+    // `seq > after`, i.e. the new deltas, not the full text).
+    seedContent?: string
   ) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -1490,10 +1496,14 @@ export class AgentWidgetClient {
     const ensureAssistantMessage = () => {
       if (assistantMessage) return assistantMessage;
       let id: string;
+      let initialContent = "";
       const segment = currentTextBlockId;
       if (!assistantIdConsumed && baseAssistantId) {
         id = baseAssistantId;
         assistantIdConsumed = true;
+        // First (and only) time we reuse the caller-supplied id: this is the
+        // bubble a durable reconnect resumes into, so continue its text.
+        initialContent = seedContent ?? "";
       } else if (baseAssistantId && segment) {
         id = `${baseAssistantId}_${segment}`;
       } else {
@@ -1502,7 +1512,7 @@ export class AgentWidgetClient {
       assistantMessage = {
         id,
         role: "assistant",
-        content: "",
+        content: initialContent,
         createdAt: new Date().toISOString(),
         streaming: true,
         sequence: nextSequence()
@@ -2552,7 +2562,11 @@ export class AgentWidgetClient {
             const message =
               typeof e === "string" && e !== ""
                 ? e
-                : e != null && typeof e === "object" && "message" in e
+                : // Reflect.has, not `in`: the `in` operator inside an arrow body can
+                  // be minified into a `for(init;;)` head, which Oxc mis-parses and
+                  // Rolldown (Vite 8) silently emits as an empty chunk. Same
+                  // [[HasProperty]] semantics. Enforced by scripts/check-dist-no-in-for-init.mjs.
+                  e != null && typeof e === "object" && Reflect.has(e, "message")
                   ? String((e as { message?: unknown }).message ?? "Step failed")
                   : "Step failed";
             onEvent({ type: "error", error: new Error(message) });
@@ -2877,7 +2891,11 @@ export class AgentWidgetClient {
           pendingFlowRaw = "";
           lastSealedFlowBubble = null;
 
-          onEvent({ type: "status", status: "idle" });
+          // `terminal: true` marks this as a graceful finish (not a drop). The
+          // session uses it to distinguish the real end-of-turn from the plain
+          // `idle` the dispatch wrappers emit in their `finally` when a durable
+          // connection drops mid-stream (durable-reconnect drop detection).
+          onEvent({ type: "status", status: "idle", terminal: true });
         } else if (payloadType === "execution_error") {
           // Terminal failure. The non-terminal `error` is handled
           // separately (recoverable → warn).
@@ -3131,7 +3149,8 @@ export class AgentWidgetClient {
             const e = payload.error;
             if (typeof e === "string" && e !== "") {
               resolvedError = new Error(e);
-            } else if (e != null && typeof e === "object" && "message" in e) {
+            } else if (e != null && typeof e === "object" && Reflect.has(e, "message")) {
+              // Reflect.has, not `in` — see the note on the equivalent guard above.
               resolvedError = new Error(String((e as { message?: unknown }).message ?? e));
             }
           }
@@ -3163,20 +3182,43 @@ export class AgentWidgetClient {
         const lines = event.split("\n");
         let eventType = "message";
         let data = "";
+        // Durable-reconnect cursor: the SSE `id:` line (the durable row seq).
+        // Only durable, resumable agent executions stamp these (e.g. Claude
+        // Managed agents, or any async/background run the backend persists and
+        // can replay); other streams carry no cursor. We emit a `cursor`
+        // event AFTER the frame is fully parsed and dispatched, so the session's
+        // `lastEventId` only advances past frames it has actually applied, so the
+        // happy path has no dupes against the server's `seq > after` replay.
+        let frameId: string | null = null;
 
         for (const line of lines) {
           if (line.startsWith("event:")) {
             eventType = line.replace("event:", "").trim();
           } else if (line.startsWith("data:")) {
             data += line.replace("data:", "").trim();
+          } else if (line.startsWith("id:")) {
+            frameId = line.slice(3).trim();
           }
         }
 
-        if (!data) continue;
+        const advanceCursor = () => {
+          if (frameId !== null && frameId !== "") {
+            onEvent({ type: "cursor", id: frameId });
+          }
+        };
+
+        // A frame with an `id:` but no `data:` (e.g. a bare keepalive line) is
+        // still a received durable row, so advance the cursor past it.
+        if (!data) {
+          advanceCursor();
+          continue;
+        }
         let payload: any;
         try {
           payload = JSON.parse(data);
         } catch (error) {
+          // Parse failure: the frame was NOT applied. Do NOT advance the cursor
+          // so a reconnect re-fetches this row.
           onEvent({
             type: "error",
             error:
@@ -3209,7 +3251,10 @@ export class AgentWidgetClient {
           if (assistantMessageRef.current && assistantMessageRef.current !== assistantMessage) {
             assistantMessage = assistantMessageRef.current;
           }
-          if (handled) continue; // Skip default handling if custom handler processed it
+          if (handled) {
+            advanceCursor();
+            continue; // Skip default handling if custom handler processed it
+          }
         }
 
         // The wire is the wire vocabulary; the handler consumes it
@@ -3217,6 +3262,7 @@ export class AgentWidgetClient {
         // drains straight through.
         seqReadyQueue.push({ payloadType, payload });
         drainReadyQueue();
+        advanceCursor();
       }
     }
 

package/src/generated/runtype-openapi-contract.ts

@@ -41,6 +41,7 @@ export type RuntypeExecutionStreamEvent = ({
 };
   type: "execution_complete";
 }) | ({
+  blockReason?: string;
   code?: string;
   completedAt?: string;
   error: string | {
@@ -295,6 +296,7 @@ export type RuntypeExecutionStreamEvent = ({
   startedAt?: string;
   subagent?: {
   agentName?: string;
+  parentToolCallId?: string;
   toolName: string;
 };
   timeout?: number;
@@ -311,12 +313,15 @@ export type RuntypeExecutionStreamEvent = ({
   seq: number;
   type: "approval_complete";
 }) | ({
+  awaitReason?: string;
   awaitedAt?: string;
+  crawlId?: string;
   executionId: string;
   origin?: "webmcp" | "sdk";
   pageOrigin?: string;
   parameters?: Record<string, unknown>;
   seq: number;
+  stepId?: string;
   toolCallId?: string;
   toolId?: string;
   toolName?: string;
@@ -386,6 +391,7 @@ export type RuntypeFlowSSEEvent = {
   totalTokensUsed?: number;
   type: "flow_complete";
 } | ({
+  blockReason?: string;
   code?: string;
   error: string | {
   code: string;
@@ -406,13 +412,18 @@ export type RuntypeFlowSSEEvent = {
   type: "flow_error";
   upgradeUrl?: string;
 }) | ({
+  approvalId?: string;
+  awaitReason?: string;
   awaitedAt: string;
+  crawlId?: string;
   executionId?: string;
   flowId: string;
   origin?: "webmcp" | "sdk";
   pageOrigin?: string;
   parameters?: Record<string, unknown>;
   seq?: number;
+  stepId?: string;
+  timeout?: number;
   toolCallId?: string;
   toolId?: string;
   toolName?: string;
@@ -667,7 +678,7 @@ export type RuntypeClientInitResponse = {
   welcomeMessage?: string | null;
 };
   expiresAt: string;
-  flow: {
+  flow?: {
   description?: string | null;
   id: string;
   name?: string | null;
@@ -689,6 +700,10 @@ export type RuntypeClientChatRequest = {
   untrustedContentHint?: boolean;
 }>;
   clientToolsFingerprint?: string;
+  identityProof?: {
+  provider: string;
+  token: string;
+};
   inputs?: Record<string, unknown>;
   messages: Array<{
   content: string | (Array<{