@runtypelabs/persona 4.5.0 → 4.6.0

package/src/session.ts

@@ -12,6 +12,7 @@ import {
   AgentWidgetApprovalDecisionOptions,
   WebMcpConfirmInfo,
   AgentExecutionState,
+  ResumableHandle,
   ClientSession,
   ContentPart,
   InjectMessageOptions,
@@ -44,12 +45,25 @@ import {
 } from "./voice";
 import { resolveSpeakableText } from "./utils/speech-text";
 import { loadRuntypeTts } from "./voice/runtype-tts-loader";
+// Type-only (erased at build): the runtime reconnect machinery is reached via a
+// dynamic import in `beginReconnect`, so it never lands in bundles that don't
+// opt into durable reconnect (see ./session-reconnect.ts).
+import type {
+  ReconnectController,
+  ReconnectHost,
+} from "./session-reconnect";
 
 export type AgentWidgetSessionStatus =
   | "idle"
   | "connecting"
   | "connected"
-  | "error";
+  | "error"
+  // Durable-session reconnect states. `paused`: a durable stream dropped and a
+  // reconnect is pending. `resuming`: a reconnect attempt is in flight. While
+  // in either, the in-progress assistant bubble stays open (not finalized) and
+  // `streaming` stays true so the typing indicator persists.
+  | "paused"
+  | "resuming";
 
 /**
  * Config fields the `AgentWidgetClient` reads to shape the connection and each
@@ -107,6 +121,17 @@ type SessionCallbacks = {
     artifacts: PersonaArtifactRecord[];
     selectedId: string | null;
   }) => void;
+  /**
+   * Durable-session reconnect lifecycle, surfaced so the UI can map it to the
+   * public `stream:paused` / `stream:resuming` / `stream:resumed` controller
+   * events. `paused` fires once on the drop, `resuming` once per attempt,
+   * `resumed` when a reconnect reaches its terminal.
+   */
+  onReconnect?: (event: {
+    phase: "paused" | "resuming" | "resumed";
+    handle: ResumableHandle;
+    attempt?: number;
+  }) => void;
 };
 
 /**
@@ -171,6 +196,29 @@ export class AgentWidgetSession {
   // Agent execution state
   private agentExecution: AgentExecutionState | null = null;
 
+  // ── Durable-session reconnect ──────────────────────────────────
+  // The in-flight resume handle for the durable lane (any resumable agent
+  // execution the backend persists and can replay, e.g. Claude Managed agents
+  // or async/background runs). Created when a stream that carries SSE `id:`
+  // lines first yields a cursor (and an executionId is known); advanced as the
+  // cursor climbs; cleared on a graceful terminal, a terminal error, or any
+  // teardown. Drives both in-session reconnect and host persistence
+  // (`onExecutionState`).
+  private resumable: ResumableHandle | null = null;
+  // The assistant message id of the current turn, so a reconnect keeps filling
+  // the SAME bubble instead of opening a new one.
+  private activeAssistantMessageId: string | null = null;
+  // True while a reconnect run is active (guards against re-entry from a second
+  // drop and tells the dispatch/connectStream catches to stay quiet).
+  private reconnecting = false;
+  // The reconnect orchestration (backoff loop, wake listeners, give-up
+  // finalizer) lives in a lazily-imported module so it stays out of bundles
+  // that never opt into durable reconnect. Created on the first reconnect.
+  private reconnectController: ReconnectController | null = null;
+  private reconnectControllerPromise: Promise<ReconnectController> | null = null;
+  // Trailing-edge throttle for `onExecutionState` so it isn't fired per delta.
+  private executionStateTimer: ReturnType<typeof setTimeout> | null = null;
+
   private artifacts = new Map<string, PersonaArtifactRecord>();
   private selectedArtifactId: string | null = null;
 
@@ -1096,10 +1144,17 @@ export class AgentWidgetSession {
     // one) so a lingering resolve can't race the new dispatch or post a stale
     // /resume against a superseded execution.
     this.abortWebMcpResolves();
+    // A new turn also supersedes any pending durable reconnect from the prior
+    // turn (cancels backoff/listeners, clears the old resume handle).
+    this.teardownReconnect();
 
     // Generate IDs for both user message and expected assistant response
     const userMessageId = generateUserMessageId();
     const assistantMessageId = generateAssistantMessageId();
+    // The active assistant bubble for a durable reconnect is captured from the
+    // real streamed message events (see handleEvent), not pre-assigned here:
+    // the proxy path auto-generates a different id than `assistantMessageId`.
+    this.activeAssistantMessageId = null;
 
     const userMessage: AgentWidgetMessage = {
       id: userMessageId,
@@ -1132,6 +1187,11 @@ export class AgentWidgetSession {
         this.handleEvent
       );
     } catch (error) {
+      // A durable drop fired the dispatch wrapper's `finally` (plain `idle`)
+      // first, which already flipped us into `resuming` and armed reconnect.
+      // The subsequent dispatch rejection must NOT paint a dispatch-error
+      // bubble: the turn is being resumed, not failed.
+      if (this.status === "resuming" || this.reconnecting) return;
       // Check if this is an abort error (user canceled, navigated away, etc.)
       // In these cases, don't show fallback - the request was intentionally interrupted
       const isAbortError =
@@ -1191,8 +1251,10 @@ export class AgentWidgetSession {
     if (this.streaming) return;
 
     this.abortController?.abort();
+    this.teardownReconnect();
 
     const assistantMessageId = generateAssistantMessageId();
+    this.activeAssistantMessageId = null;
 
     this.setStreaming(true);
 
@@ -1211,6 +1273,7 @@ export class AgentWidgetSession {
         this.handleEvent
       );
     } catch (error) {
+      if (this.status === "resuming" || this.reconnecting) return;
       // Check if this is an abort error (a prior in-flight stream was canceled,
       // the user navigated away, etc.). In these cases, don't show fallback or
       // fire onError - the request was intentionally interrupted.
@@ -1258,18 +1321,44 @@ export class AgentWidgetSession {
    */
   public async connectStream(
     stream: ReadableStream<Uint8Array>,
-    options?: { assistantMessageId?: string; allowReentry?: boolean }
+    options?: {
+      assistantMessageId?: string;
+      allowReentry?: boolean;
+      /**
+       * Durable reconnect: keep the assistant message identified by
+       * `assistantMessageId` OPEN so the replayed deltas keep filling it. The
+       * default stale-finalize pass would otherwise seal the very bubble we're
+       * resuming into.
+       */
+      preserveAssistantId?: boolean;
+      /**
+       * Durable reconnect: text already shown in the resumed bubble, so the
+       * fresh stream's accumulator continues from it (the replay carries only
+       * post-cursor deltas, not the full text).
+       */
+      seedContent?: string;
+    }
   ): Promise<void> {
     if (this.streaming && !options?.allowReentry) return;
     if (!options?.allowReentry) {
       this.abortController?.abort();
     }
 
+    // Durable reconnect keeps filling the same bubble: track its id so the
+    // cursor handler attaches to it.
+    if (options?.preserveAssistantId && options.assistantMessageId) {
+      this.activeAssistantMessageId = options.assistantMessageId;
+    }
+
     // Finalize any stale streaming messages from the previous stream
-    // (e.g., tool messages interrupted by approval pause)
+    // (e.g., tool messages interrupted by approval pause), except the bubble
+    // an active reconnect is resuming into.
+    const preserveId = options?.preserveAssistantId
+      ? options.assistantMessageId
+      : undefined;
     let hasStale = false;
     for (const msg of this.messages) {
-      if (msg.streaming) {
+      if (msg.streaming && msg.id !== preserveId) {
         msg.streaming = false;
         hasStale = true;
       }
@@ -1284,9 +1373,14 @@ export class AgentWidgetSession {
       await this.client.processStream(
         stream,
         this.handleEvent,
-        options?.assistantMessageId
+        options?.assistantMessageId,
+        options?.seedContent
       );
     } catch (error) {
+      // During a durable reconnect a thrown resume stream is just another drop:
+      // the reconnect loop owns the retry/backoff. Don't paint an error or tear
+      // down, stay in `resuming`.
+      if (this.status === "resuming" || this.reconnecting) return;
       this.setStatus("error");
       // Mirror the idle/error handlers: a failed resume stream must not tear
       // down streaming/abortController while another WebMCP resolve is still
@@ -2446,6 +2540,9 @@ export class AgentWidgetSession {
   public cancel() {
     this.abortController?.abort();
     this.abortController = null;
+    // A user stop also cancels any pending/in-flight durable reconnect and
+    // clears the resume handle (the abort above already killed its fetch).
+    this.teardownReconnect();
     // Tear down every in-flight WebMCP resolve (each owns its own controller,
     // independent of the shared one above). Clear the inflight set so retries
     // are possible if the user re-issues the same step_await context.
@@ -2464,6 +2561,7 @@ export class AgentWidgetSession {
     this.stopSpeaking();
     this.abortController?.abort();
     this.abortController = null;
+    this.teardownReconnect();
     // Tear down every in-flight WebMCP resolve too: their messages are about
     // to be wiped, and a microtask-deferred resolve must not survive the clear.
     this.abortWebMcpResolves();
@@ -2603,6 +2701,9 @@ export class AgentWidgetSession {
   public hydrateMessages(messages: AgentWidgetMessage[]) {
     this.abortController?.abort();
     this.abortController = null;
+    // Hydration replaces the conversation: also cancel any pending reconnect and
+    // clear the resume handle (a boot resume re-arms via resumeFromHandle after).
+    this.teardownReconnect();
     // Hydration replaces the conversation: abort and forget every in-flight
     // WebMCP resolve; their messages are about to be replaced.
     this.abortWebMcpResolves();
@@ -2638,6 +2739,18 @@ export class AgentWidgetSession {
     if (event.type === "message") {
       this.upsertMessage(event.message);
 
+      // Track the open assistant text bubble's REAL streamed id so a durable
+      // reconnect keeps filling the same message. The proxy path auto-generates
+      // this id (it isn't the session's pre-generated one), so we must read it
+      // off the actual message events, not assume it.
+      if (
+        event.message.role === "assistant" &&
+        !event.message.variant &&
+        event.message.streaming
+      ) {
+        this.activeAssistantMessageId = event.message.id;
+      }
+
       // Local-tool auto-resolve: when a step_await emits a tool-variant
       // message for a `webmcp:*` tool, or the built-in fire-and-forget
       // `suggest_replies`: resolve it and post the result to /resume.
@@ -2694,11 +2807,27 @@ export class AgentWidgetSession {
           this.agentExecution.currentIteration = event.message.agentMetadata.iteration;
         }
       }
+    } else if (event.type === "cursor") {
+      // Durable-reconnect cursor. Track the highest SSE `id:` seq as the resume
+      // cursor and (lazily) form the resume handle once the executionId is
+      // known. Only durable, resumable executions emit these, so this is the
+      // natural gate: no `id:` lines → no handle → reconnect never arms.
+      this.trackCursor(event.id);
     } else if (event.type === "status") {
+      // A plain `idle` (no `terminal`) on the durable lane, while the run is
+      // genuinely mid-turn, is a dropped connection, not a finish and not an
+      // intentional `step_await` pause. Reconnect instead of finalizing.
+      if (event.status === "idle" && !event.terminal && this.isDurableDrop()) {
+        this.beginReconnect();
+        return;
+      }
       this.setStatus(event.status);
       if (event.status === "connecting") {
         this.setStreaming(true);
       } else if (event.status === "idle" || event.status === "error") {
+        // Graceful terminal or terminal error: the durable turn is over, so
+        // drop the resume handle (no reconnect should arm after this).
+        this.clearResumable();
         // Keep the typing indicator up while a WebMCP resolve is still in
         // flight: in a chained turn the intermediate resume stream ends with an
         // idle status, but the successor tool is still executing. The resolve's
@@ -2733,6 +2862,8 @@ export class AgentWidgetSession {
       }
     } else if (event.type === "error") {
       this.setStatus("error");
+      // Terminal error: drop the resume handle so no reconnect arms.
+      this.clearResumable();
       // Mirror the idle/status handler: don't tear down streaming while a
       // WebMCP resolve is still confirming/executing on another stream: an
       // error on one chained resume stream must not hide the typing indicator
@@ -2756,6 +2887,278 @@ export class AgentWidgetSession {
     }
   };
 
+  // ── Durable-session reconnect ──────────────────────────────────
+
+  /**
+   * Record the latest SSE `id:` cursor and (lazily) form/advance the resume
+   * handle. Needs an executionId (lifted into `agentExecution` from the same
+   * frame's metadata, handled before this trailing cursor event) and the active
+   * assistant message id.
+   */
+  private trackCursor(id: string): void {
+    const executionId = this.agentExecution?.executionId;
+    if (!executionId || !this.activeAssistantMessageId) return;
+    // Only track while the run is live. A graceful terminal sets the execution
+    // to 'complete'/'error' and clears the handle BEFORE its own frame's
+    // trailing cursor fires; without this guard that cursor would re-arm the
+    // handle and the next plain `idle` would look like a spurious drop.
+    if (this.agentExecution?.status !== "running") return;
+    const isNew = this.resumable === null;
+    this.resumable = {
+      executionId,
+      lastEventId: id,
+      assistantMessageId: this.activeAssistantMessageId,
+      status: "running",
+    };
+    // Fire immediately when the handle first appears (so the host can persist
+    // the executionId promptly); throttle subsequent cursor advances.
+    this.notifyExecutionState(isNew);
+  }
+
+  /**
+   * The drop gate: is this stream-end a dropped connection we should reconnect,
+   * rather than a graceful finish or an intentional `step_await` pause? ALL must
+   * hold (see plan §Design overview keystone 3).
+   */
+  private isDurableDrop(): boolean {
+    return (
+      this.resumable !== null &&
+      typeof this.config.reconnectStream === "function" &&
+      this.abortController?.signal.aborted !== true &&
+      this.webMcpResolveControllers.size === 0 &&
+      this.webMcpAwaitBatches.size === 0 &&
+      !this.isAwaitPending()
+    );
+  }
+
+  /**
+   * True when the run is parked awaiting user input (an unanswered
+   * `ask_user_question` / local-tool await, or a pending approval). Those end
+   * the stream with `idle` and no terminal too, but are NOT drops.
+   */
+  private isAwaitPending(): boolean {
+    return this.messages.some((m) => {
+      if (
+        m.agentMetadata?.awaitingLocalTool === true &&
+        m.agentMetadata?.askUserQuestionAnswered !== true
+      ) {
+        return true;
+      }
+      if (m.variant === "approval" && m.approval?.status === "pending") {
+        return true;
+      }
+      return false;
+    });
+  }
+
+  /**
+   * Enter the reconnect flow. Keeps the assistant bubble open and `streaming`
+   * true, flips to `resuming`, and kicks the bounded backoff loop. Re-entrant
+   * calls (a second drop while reconnecting) are no-ops.
+   */
+  private beginReconnect(): void {
+    if (this.reconnecting) return;
+    if (!this.resumable || typeof this.config.reconnectStream !== "function") {
+      return;
+    }
+    // Flip the visible state synchronously — the bubble stays open and a
+    // `resuming` status is observable immediately (e.g. right after
+    // `resumeFromHandle`). The heavy backoff loop is loaded lazily below.
+    this.reconnecting = true;
+    this.callbacks.onReconnect?.({ phase: "paused", handle: this.resumable });
+    this.setStreaming(true);
+    this.setStatus("resuming");
+    void this.loadReconnectController().then((controller) => {
+      // The run may have been torn down (new turn / cancel / hydrate) while the
+      // module was loading; only start the loop if we're still reconnecting.
+      if (this.reconnecting && this.resumable) controller.begin();
+    });
+  }
+
+  /**
+   * Lazily import and instantiate the reconnect controller. Cached so repeated
+   * reconnects reuse one controller (and one module load). Deliberately kept off
+   * every hot path (`sendMessage` / `cancel` / `teardownReconnect`) so a widget
+   * that never reconnects never pulls the chunk.
+   */
+  private loadReconnectController(): Promise<ReconnectController> {
+    if (this.reconnectController) {
+      return Promise.resolve(this.reconnectController);
+    }
+    if (!this.reconnectControllerPromise) {
+      this.reconnectControllerPromise = import("./session-reconnect").then(
+        ({ createReconnectController }) => {
+          const controller = createReconnectController(
+            this.buildReconnectHost()
+          );
+          this.reconnectController = controller;
+          return controller;
+        }
+      );
+    }
+    return this.reconnectControllerPromise;
+  }
+
+  /** The narrow surface the lazily-loaded reconnect loop drives. */
+  private buildReconnectHost(): ReconnectHost {
+    const session = this;
+    return {
+      get config() {
+        return session.config;
+      },
+      getResumable: () => session.resumable,
+      clearResumable: () => session.clearResumable(),
+      getStatus: () => session.status,
+      setStatus: (status) => session.setStatus(status),
+      setStreaming: (streaming) => session.setStreaming(streaming),
+      setReconnecting: (value) => {
+        session.reconnecting = value;
+      },
+      setAbortController: (controller) => {
+        session.abortController = controller;
+      },
+      getMessages: () => session.messages,
+      notifyMessagesChanged: () =>
+        session.callbacks.onMessagesChanged([...session.messages]),
+      resumeConnect: (body, assistantMessageId, seedContent) =>
+        session.connectStream(body, {
+          assistantMessageId,
+          allowReentry: true,
+          preserveAssistantId: true,
+          seedContent,
+        }),
+      appendMessage: (message) => session.appendMessage(message),
+      nextSequence: () => session.nextSequence(),
+      emitReconnect: (event) => session.callbacks.onReconnect?.(event),
+      buildErrorContent: (message) =>
+        buildDispatchErrorContent(
+          new Error(message),
+          session.config.errorMessage
+        ),
+      onError: (error) => session.callbacks.onError?.(error),
+    };
+  }
+
+  /** Public manual retry (e.g. a "Reconnect" button). */
+  public reconnectNow(): void {
+    if (this.reconnecting) {
+      // Already trying, so just short-circuit the current backoff. (No-op if the
+      // controller is still loading; the first attempt hasn't slept yet.)
+      this.reconnectController?.wake();
+      return;
+    }
+    this.beginReconnect();
+  }
+
+  /**
+   * Resume a durable turn on boot (tab-reload path). Re-opens the trailing
+   * assistant bubble (or mints one), restores the execution/handle, and
+   * reconnects from the persisted cursor. No-op without `reconnectStream`.
+   */
+  public resumeFromHandle(resume: { executionId: string; after: string }): void {
+    if (typeof this.config.reconnectStream !== "function") return;
+    if (this.reconnecting) return;
+
+    let assistantId = this.reopenTrailingAssistant();
+    if (!assistantId) {
+      assistantId = generateAssistantMessageId();
+      this.appendMessage({
+        id: assistantId,
+        role: "assistant",
+        content: "",
+        createdAt: new Date().toISOString(),
+        streaming: true,
+        sequence: this.nextSequence(),
+      });
+    }
+    this.activeAssistantMessageId = assistantId;
+    if (!this.agentExecution) {
+      this.agentExecution = {
+        executionId: resume.executionId,
+        agentId: "",
+        agentName: "",
+        status: "running",
+        currentIteration: 0,
+        maxTurns: 0,
+      };
+    }
+    this.resumable = {
+      executionId: resume.executionId,
+      lastEventId: resume.after,
+      assistantMessageId: assistantId,
+      status: "running",
+    };
+    this.beginReconnect();
+  }
+
+  /**
+   * Reopen the trailing assistant bubble (the persisted partial) so replayed
+   * deltas append to it. Returns its id, or null if the last turn doesn't end
+   * in a plain assistant message.
+   */
+  private reopenTrailingAssistant(): string | null {
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const m = this.messages[i];
+      if (m.role === "assistant" && !m.variant) {
+        m.streaming = true;
+        this.callbacks.onMessagesChanged([...this.messages]);
+        return m.id;
+      }
+      if (m.role === "user") break;
+    }
+    return null;
+  }
+
+  /**
+   * Tear down any in-flight/pending reconnect and clear the resume handle. Runs
+   * on every new turn / cancel / hydrate, so it must NOT pull the reconnect
+   * chunk: it only delegates to the controller if one was already created.
+   */
+  private teardownReconnect(): void {
+    this.reconnecting = false;
+    this.reconnectController?.teardown();
+    this.clearResumable();
+  }
+
+  /** Drop the resume handle and notify the host (`onExecutionState(null)`). */
+  private clearResumable(): void {
+    if (this.executionStateTimer) {
+      clearTimeout(this.executionStateTimer);
+      this.executionStateTimer = null;
+    }
+    const had = this.resumable !== null;
+    this.resumable = null;
+    if (had) this.config.onExecutionState?.(null);
+  }
+
+  /**
+   * Surface the resume handle to the host for persistence. Immediate on
+   * create/clear; trailing-edge throttled on cursor advances so it isn't called
+   * per delta.
+   */
+  private notifyExecutionState(immediate: boolean): void {
+    const cb = this.config.onExecutionState;
+    if (!cb) return;
+    if (immediate) {
+      if (this.executionStateTimer) {
+        clearTimeout(this.executionStateTimer);
+        this.executionStateTimer = null;
+      }
+      cb(this.resumable);
+      return;
+    }
+    if (this.executionStateTimer) return; // a trailing call is already queued
+    this.executionStateTimer = setTimeout(() => {
+      this.executionStateTimer = null;
+      this.config.onExecutionState?.(this.resumable);
+    }, 500);
+  }
+
+  /** The current durable resume handle, if any (read-only). */
+  public getResumableHandle(): ResumableHandle | null {
+    return this.resumable;
+  }
+
   private setStatus(status: AgentWidgetSessionStatus) {
     if (this.status === status) return;
     this.status = status;

package/src/types.ts

@@ -386,6 +386,28 @@ export type AgentExecutionState = {
   stopReason?: 'complete' | 'end_turn' | 'max_turns' | 'max_cost' | 'timeout' | 'error';
 };
 
+/**
+ * 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).
+ */
+export 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.
  */
@@ -689,6 +711,12 @@ export type AgentWidgetControllerEventMap = {
   "eventStream:closed": { timestamp: number };
   "approval:requested": { approval: AgentWidgetApproval; message: AgentWidgetMessage };
   "approval:resolved": { approval: AgentWidgetApproval; decision: string };
+  /** A durable stream dropped; the widget is about to reconnect. */
+  "stream:paused": { executionId: string; after: string };
+  /** A reconnect attempt is in flight (`attempt` is 1-based). */
+  "stream:resuming": { executionId: string; after: string; attempt: number };
+  /** The durable turn resumed and reached its terminal after a reconnect. */
+  "stream:resumed": { executionId: string; after: string };
 };
 
 /**
@@ -1851,6 +1879,10 @@ export 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;
 };
 
 export type AgentWidgetVoiceRecognitionConfig = {
@@ -4160,6 +4192,62 @@ export 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.
    *
@@ -4736,8 +4824,26 @@ export type PersonaArtifactManualUpsert =
 
 export type AgentWidgetEvent =
   | { type: "message"; message: AgentWidgetMessage }
-  | { type: "status"; status: "connecting" | "connected" | "error" | "idle" }
+  | {
+      type: "status";
+      status: "connecting" | "connected" | "error" | "idle";
+      /**
+       * Set on the `idle` emitted from a graceful execution terminal
+       * (`execution_complete`). Distinguishes a real finish from the plain
+       * `idle` the dispatch wrappers emit in their `finally` on a dropped
+       * connection. The durable-reconnect drop detection keys off this.
+       */
+      terminal?: boolean;
+    }
   | { type: "error"; error: Error }
+  /**
+   * Durable-session reconnect cursor. Carries the SSE `id:` line (the durable
+   * row seq) of a fully-parsed frame so the session can track `lastEventId`
+   * and resume from `?after=<id>` after a drop. Only emitted on the durable
+   * lane (any resumable execution that stamps `id:` lines, e.g. Claude Managed
+   * agents or async/background runs).
+   */
+  | { type: "cursor"; id: string }
   | {
       type: "artifact_start";
       id: string;