@runtypelabs/persona 4.4.2 → 4.6.0

package/dist/theme-editor-preview.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.
  */
@@ -1975,6 +2002,22 @@ type AgentWidgetControllerEventMap = {
         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;
+    };
 };
 /**
  * Layout for the artifact split / drawer (CSS lengths unless noted).
@@ -2133,25 +2176,74 @@ type AgentWidgetArtifactsFeature = {
 /**
  * How the transcript scrolls while an assistant response streams in.
  *
- * - `"follow"` (default): keep the newest content pinned to the bottom of the
- *   viewport, pausing when the user scrolls up and resuming when they return
- *   to the bottom.
- * - `"anchor-top"`: on send, scroll the user's message near the top of the
- *   viewport and hold it there while the response streams in beneath it
- *   (ChatGPT-style). The transcript never auto-scrolls during streaming.
+ * - `"anchor-top"` (default): on send, scroll the user's message near the top
+ *   of the viewport and hold it there while the response streams in beneath it
+ *   (ChatGPT-style). When a turn has no user send to anchor to (a proactive
+ *   greeting, an injected assistant message, a resubmit, or first-load
+ *   streaming), it falls back to `"follow"` for that turn so content never
+ *   streams in off-screen.
+ * - `"follow"`: keep the newest content pinned to the bottom of the viewport,
+ *   pausing when the user scrolls up and resuming when they return to the
+ *   bottom. This was the default before 4.x.
  * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
  *   way back to the latest content.
  */
 type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
+/**
+ * Where the transcript lands when a *saved* conversation is reopened (restored
+ * from the storage adapter / `initialMessages`), as opposed to a fresh send.
+ *
+ * - `"bottom"` (default): jump to the absolute end of the transcript, matching
+ *   the historical behavior.
+ * - `"last-user-turn"`: pin the last user message near the top of the viewport
+ *   (the last point the reader was actively driving the conversation) so a long
+ *   restored thread opens at a readable place rather than at the very bottom.
+ */
+type AgentWidgetScrollRestorePosition = "bottom" | "last-user-turn";
 type AgentWidgetScrollBehaviorFeature = {
-    /** Scroll behavior during streamed responses. @default "follow" */
+    /** Scroll behavior during streamed responses. @default "anchor-top" */
     mode?: AgentWidgetScrollMode;
     /**
      * Gap (px) kept between the anchored user message and the top of the
-     * viewport in `"anchor-top"` mode.
+     * viewport in `"anchor-top"` mode. Also used as the gap for
+     * `restorePosition: "last-user-turn"`.
      * @default 16
      */
     anchorTopOffset?: number;
+    /**
+     * Where to land when a saved conversation reopens. Additive and opt-in: the
+     * default preserves the historical "jump to the bottom" behavior.
+     * @default "bottom"
+     */
+    restorePosition?: AgentWidgetScrollRestorePosition;
+    /**
+     * When true, interactions beyond text selection — keyboard navigation
+     * (PageUp/PageDown/Home/End/arrows) inside the transcript and focusing a
+     * link or other interactive element within it — also pause auto-follow in
+     * `"follow"` mode. Treats "the reader is doing something here" as intent to
+     * stay put, not just "the reader dragged a selection". Opt-in; default keeps
+     * only the existing wheel/scroll/selection triggers.
+     * @default false
+     */
+    pauseOnInteraction?: boolean;
+    /**
+     * When true, the scroll-to-bottom affordance also surfaces new-content and
+     * still-streaming activity while the reader is pinned away from the latest
+     * content in `"anchor-top"` mode. Lets the reader know a response is arriving
+     * offscreen below. Defaults on alongside the `"anchor-top"` default; set
+     * `false` to keep the count + streaming hint silent while pinned.
+     * @default true
+     */
+    showActivityWhilePinned?: boolean;
+    /**
+     * When true, Persona maintains a visually-hidden `aria-live="polite"` region
+     * that announces important transcript events — a response starting, a
+     * response finishing, and "N new messages below" while the reader is scrolled
+     * away — at a comfortable cadence (never token-by-token). Opt-in so existing
+     * embeds don't suddenly gain screen-reader announcements.
+     * @default false
+     */
+    announce?: boolean;
 };
 type AgentWidgetScrollToBottomFeature = {
     /**
@@ -3034,6 +3126,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;
@@ -5124,6 +5220,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.
      *
@@ -5666,9 +5821,27 @@ type AgentWidgetEvent = {
 } | {
     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;
@@ -5689,7 +5862,7 @@ type AgentWidgetEvent = {
     id: string;
 };
 
-type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error";
+type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error" | "paused" | "resuming";
 
 /**
  * Feedback UI components for CSAT and NPS collection
@@ -5746,6 +5919,11 @@ type Controller = {
     clearChat: () => void;
     setMessage: (message: string) => boolean;
     submitMessage: (message?: string) => boolean;
+    /**
+     * Manually retry a dropped durable stream (e.g. from a "Reconnect" button).
+     * No-op unless a resumable durable turn dropped and `reconnectStream` is set.
+     */
+    reconnect: () => void;
     startVoiceRecognition: () => boolean;
     stopVoiceRecognition: () => boolean;
     /**

package/dist/theme-editor-preview.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.
  */
@@ -1975,6 +2002,22 @@ type AgentWidgetControllerEventMap = {
         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;
+    };
 };
 /**
  * Layout for the artifact split / drawer (CSS lengths unless noted).
@@ -2133,25 +2176,74 @@ type AgentWidgetArtifactsFeature = {
 /**
  * How the transcript scrolls while an assistant response streams in.
  *
- * - `"follow"` (default): keep the newest content pinned to the bottom of the
- *   viewport, pausing when the user scrolls up and resuming when they return
- *   to the bottom.
- * - `"anchor-top"`: on send, scroll the user's message near the top of the
- *   viewport and hold it there while the response streams in beneath it
- *   (ChatGPT-style). The transcript never auto-scrolls during streaming.
+ * - `"anchor-top"` (default): on send, scroll the user's message near the top
+ *   of the viewport and hold it there while the response streams in beneath it
+ *   (ChatGPT-style). When a turn has no user send to anchor to (a proactive
+ *   greeting, an injected assistant message, a resubmit, or first-load
+ *   streaming), it falls back to `"follow"` for that turn so content never
+ *   streams in off-screen.
+ * - `"follow"`: keep the newest content pinned to the bottom of the viewport,
+ *   pausing when the user scrolls up and resuming when they return to the
+ *   bottom. This was the default before 4.x.
  * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
  *   way back to the latest content.
  */
 type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
+/**
+ * Where the transcript lands when a *saved* conversation is reopened (restored
+ * from the storage adapter / `initialMessages`), as opposed to a fresh send.
+ *
+ * - `"bottom"` (default): jump to the absolute end of the transcript, matching
+ *   the historical behavior.
+ * - `"last-user-turn"`: pin the last user message near the top of the viewport
+ *   (the last point the reader was actively driving the conversation) so a long
+ *   restored thread opens at a readable place rather than at the very bottom.
+ */
+type AgentWidgetScrollRestorePosition = "bottom" | "last-user-turn";
 type AgentWidgetScrollBehaviorFeature = {
-    /** Scroll behavior during streamed responses. @default "follow" */
+    /** Scroll behavior during streamed responses. @default "anchor-top" */
     mode?: AgentWidgetScrollMode;
     /**
      * Gap (px) kept between the anchored user message and the top of the
-     * viewport in `"anchor-top"` mode.
+     * viewport in `"anchor-top"` mode. Also used as the gap for
+     * `restorePosition: "last-user-turn"`.
      * @default 16
      */
     anchorTopOffset?: number;
+    /**
+     * Where to land when a saved conversation reopens. Additive and opt-in: the
+     * default preserves the historical "jump to the bottom" behavior.
+     * @default "bottom"
+     */
+    restorePosition?: AgentWidgetScrollRestorePosition;
+    /**
+     * When true, interactions beyond text selection — keyboard navigation
+     * (PageUp/PageDown/Home/End/arrows) inside the transcript and focusing a
+     * link or other interactive element within it — also pause auto-follow in
+     * `"follow"` mode. Treats "the reader is doing something here" as intent to
+     * stay put, not just "the reader dragged a selection". Opt-in; default keeps
+     * only the existing wheel/scroll/selection triggers.
+     * @default false
+     */
+    pauseOnInteraction?: boolean;
+    /**
+     * When true, the scroll-to-bottom affordance also surfaces new-content and
+     * still-streaming activity while the reader is pinned away from the latest
+     * content in `"anchor-top"` mode. Lets the reader know a response is arriving
+     * offscreen below. Defaults on alongside the `"anchor-top"` default; set
+     * `false` to keep the count + streaming hint silent while pinned.
+     * @default true
+     */
+    showActivityWhilePinned?: boolean;
+    /**
+     * When true, Persona maintains a visually-hidden `aria-live="polite"` region
+     * that announces important transcript events — a response starting, a
+     * response finishing, and "N new messages below" while the reader is scrolled
+     * away — at a comfortable cadence (never token-by-token). Opt-in so existing
+     * embeds don't suddenly gain screen-reader announcements.
+     * @default false
+     */
+    announce?: boolean;
 };
 type AgentWidgetScrollToBottomFeature = {
     /**
@@ -3034,6 +3126,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;
@@ -5124,6 +5220,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.
      *
@@ -5666,9 +5821,27 @@ type AgentWidgetEvent = {
 } | {
     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;
@@ -5689,7 +5862,7 @@ type AgentWidgetEvent = {
     id: string;
 };
 
-type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error";
+type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error" | "paused" | "resuming";
 
 /**
  * Feedback UI components for CSAT and NPS collection
@@ -5746,6 +5919,11 @@ type Controller = {
     clearChat: () => void;
     setMessage: (message: string) => boolean;
     submitMessage: (message?: string) => boolean;
+    /**
+     * Manually retry a dropped durable stream (e.g. from a "Reconnect" button).
+     * No-op unless a resumable durable turn dropped and `reconnectStream` is set.
+     */
+    reconnect: () => void;
     startVoiceRecognition: () => boolean;
     stopVoiceRecognition: () => boolean;
     /**