@runtypelabs/persona 4.5.0 → 4.6.0

package/dist/theme-editor.d.cts

@@ -1053,12 +1053,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;
@@ -1147,13 +1150,16 @@ type RuntypeFlowSSEEvent = {
     type: "flow_error";
     upgradeUrl?: string;
 }) | ({
+    awaitReason?: string;
     awaitedAt: string;
+    crawlId?: string;
     executionId?: string;
     flowId: string;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
     parameters?: Record<string, unknown>;
     seq?: number;
+    stepId?: string;
     toolCallId?: string;
     toolId?: string;
     toolName?: string;
@@ -1693,6 +1699,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 +3036,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 +5121,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

@@ -1053,12 +1053,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;
@@ -1147,13 +1150,16 @@ type RuntypeFlowSSEEvent = {
     type: "flow_error";
     upgradeUrl?: string;
 }) | ({
+    awaitReason?: string;
     awaitedAt: string;
+    crawlId?: string;
     executionId?: string;
     flowId: string;
     origin?: "webmcp" | "sdk";
     pageOrigin?: string;
     parameters?: Record<string, unknown>;
     seq?: number;
+    stepId?: string;
     toolCallId?: string;
     toolId?: string;
     toolName?: string;
@@ -1693,6 +1699,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 +3036,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 +5121,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.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",
@@ -124,7 +124,7 @@
     "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()
@@ -2877,7 +2887,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).
@@ -3163,20 +3177,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 +3246,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 +3257,7 @@ export class AgentWidgetClient {
         // drains straight through.
         seqReadyQueue.push({ payloadType, payload });
         drainReadyQueue();
+        advanceCursor();
       }
     }
 

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

@@ -311,12 +311,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;
@@ -406,13 +409,16 @@ export type RuntypeFlowSSEEvent = {
   type: "flow_error";
   upgradeUrl?: string;
 }) | ({
+  awaitReason?: string;
   awaitedAt: string;
+  crawlId?: string;
   executionId?: string;
   flowId: string;
   origin?: "webmcp" | "sdk";
   pageOrigin?: string;
   parameters?: Record<string, unknown>;
   seq?: number;
+  stepId?: string;
   toolCallId?: string;
   toolId?: string;
   toolName?: string;

package/src/reconnect-wake.test.ts

@@ -0,0 +1,162 @@
+// @vitest-environment jsdom
+//
+// Wake-listener behavior for durable reconnect (`session-reconnect.ts`). These
+// need a DOM so the `visibilitychange` / `online` listeners actually attach, so
+// this file runs in jsdom (the sibling `reconnect.test.ts` is node-env, where
+// the `typeof document/window` guards skip the listeners entirely).
+//
+// The crux: `online` must short-circuit the backoff sleep even when the tab is
+// backgrounded, while `visibilitychange` must only wake on the show transition.
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
+import { AgentWidgetMessage } from "./types";
+
+const enc = new TextEncoder();
+
+function sseStream(frames: string[]): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      for (const f of frames) controller.enqueue(enc.encode(f));
+      controller.close();
+    },
+  });
+}
+
+function frame(
+  id: number | null,
+  type: string,
+  data: Record<string, unknown> = {}
+): string {
+  const head = id !== null ? `id: ${id}\n` : "";
+  return `${head}event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`;
+}
+
+async function waitFor(pred: () => boolean, timeoutMs = 1500): Promise<void> {
+  const start = Date.now();
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    if (pred()) return;
+    if (Date.now() - start > timeoutMs) throw new Error("waitFor: timed out");
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+function setVisibility(state: "visible" | "hidden"): void {
+  Object.defineProperty(document, "visibilityState", {
+    configurable: true,
+    get: () => state,
+  });
+}
+
+describe("AgentWidgetSession - reconnect wake listeners", () => {
+  let messages: AgentWidgetMessage[];
+  let status: AgentWidgetSessionStatus;
+  let reconnectPhases: string[];
+
+  const baseCallbacks = () => ({
+    onMessagesChanged: (m: AgentWidgetMessage[]) => {
+      messages = m;
+    },
+    onStatusChanged: (s: AgentWidgetSessionStatus) => {
+      status = s;
+    },
+    onStreamingChanged: () => {},
+    onError: () => {},
+    onReconnect: (ev: { phase: string }) => {
+      reconnectPhases.push(ev.phase);
+    },
+  });
+
+  const assistantText = () =>
+    messages.find((m) => m.role === "assistant" && !m.variant)?.content ?? "";
+
+  // A session that drops mid-stream, fails its first reconnect attempt (forcing
+  // a deliberately long backoff sleep), then succeeds on the second. A prompt
+  // 2nd attempt can therefore only mean a wake fired — never the 10s timer.
+  function dropThenResumeSession() {
+    const initial = sseStream([
+      frame(1, "text_delta", {
+        id: "text_0",
+        delta: "Hello",
+        executionId: "exec_1",
+      }),
+    ]);
+    const resume = sseStream([
+      frame(2, "text_delta", {
+        id: "text_0",
+        delta: " world",
+        executionId: "exec_1",
+      }),
+      frame(3, "execution_complete", { success: true, kind: "agent" }),
+    ]);
+    let calls = 0;
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: "http://x",
+        customFetch: async () => ({ ok: true, body: initial }) as any,
+        reconnectStream: async () => {
+          calls += 1;
+          if (calls === 1) return { ok: false } as any;
+          return { ok: true, body: resume } as any;
+        },
+        reconnect: { backoffMs: [10000], maxAttempts: 5 },
+      },
+      baseCallbacks()
+    );
+    return {
+      session,
+      getCalls: () => calls,
+    };
+  }
+
+  beforeEach(() => {
+    messages = [];
+    status = "idle";
+    reconnectPhases = [];
+    setVisibility("visible");
+  });
+
+  afterEach(() => {
+    setVisibility("visible");
+    vi.restoreAllMocks();
+  });
+
+  it("online wakes the backoff immediately even when the tab is backgrounded", async () => {
+    const { session, getCalls } = dropThenResumeSession();
+
+    await session.sendMessage("hi");
+    // Wait until the first reconnect attempt has failed and we're sleeping in
+    // the (10s) backoff before the second attempt.
+    await waitFor(() => status === "paused");
+    expect(getCalls()).toBe(1);
+
+    // Background the tab, then regain connectivity. The visibility guard must
+    // NOT suppress the `online` wake.
+    setVisibility("hidden");
+    window.dispatchEvent(new Event("online"));
+
+    // Without the fix this times out (the loop would wait the full 10s).
+    await waitFor(() => reconnectPhases.includes("resumed"));
+    expect(getCalls()).toBe(2);
+    expect(assistantText()).toBe("Hello world");
+    expect(status).toBe("idle");
+  });
+
+  it("visibilitychange wakes the backoff when the tab becomes visible", async () => {
+    const { session, getCalls } = dropThenResumeSession();
+
+    await session.sendMessage("hi");
+    await waitFor(() => status === "paused");
+    expect(getCalls()).toBe(1);
+
+    // Tab brought back to the foreground: the show transition should wake.
+    setVisibility("visible");
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    await waitFor(() => reconnectPhases.includes("resumed"));
+    expect(getCalls()).toBe(2);
+    expect(assistantText()).toBe("Hello world");
+    expect(status).toBe("idle");
+  });
+});