@runtypelabs/persona 4.5.0 → 4.6.1

package/dist/index.d.cts

@@ -812,6 +812,7 @@ type RuntypeExecutionStreamEvent = ({
     };
     type: "execution_complete";
 }) | ({
+    blockReason?: string;
     code?: string;
     completedAt?: string;
     error: string | {
@@ -1066,6 +1067,7 @@ type RuntypeExecutionStreamEvent = ({
     startedAt?: string;
     subagent?: {
         agentName?: string;
+        parentToolCallId?: string;
         toolName: string;
     };
     timeout?: number;
@@ -1082,12 +1084,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;
@@ -1156,6 +1161,7 @@ type RuntypeFlowSSEEvent = {
     totalTokensUsed?: number;
     type: "flow_complete";
 } | ({
+    blockReason?: string;
     code?: string;
     error: string | {
         code: string;
@@ -1176,13 +1182,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;
@@ -1425,7 +1436,7 @@ type RuntypeClientInitResponse = {
         welcomeMessage?: string | null;
     };
     expiresAt: string;
-    flow: {
+    flow?: {
         description?: string | null;
         id: string;
         name?: string | null;
@@ -1446,6 +1457,10 @@ type RuntypeClientChatRequest = {
         untrustedContentHint?: boolean;
     }>;
     clientToolsFingerprint?: string;
+    identityProof?: {
+        provider: string;
+        token: string;
+    };
     inputs?: Record<string, unknown>;
     messages: Array<{
         content: string | (Array<{
@@ -1888,6 +1903,27 @@ type AgentExecutionState = {
     completedAt?: number;
     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).
+ */
+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.
  */
@@ -2170,6 +2206,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).
@@ -3278,6 +3330,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;
@@ -5469,6 +5525,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.
      *
@@ -6011,9 +6126,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;
@@ -6243,7 +6376,7 @@ declare class AgentWidgetClient {
      * This allows piping responses from endpoints like agent approval
      * through the same message/tool/reasoning handling as dispatch().
      */
-    processStream(body: ReadableStream<Uint8Array>, onEvent: SSEHandler, assistantMessageId?: string): Promise<void>;
+    processStream(body: ReadableStream<Uint8Array>, onEvent: SSEHandler, assistantMessageId?: string, seedContent?: string): Promise<void>;
     /**
      * Send an approval decision to the API and return the response
      * for streaming continuation.
@@ -6358,7 +6491,7 @@ declare class ReadAloudController {
     private set;
 }
 
-type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error";
+type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error" | "paused" | "resuming";
 type SessionCallbacks = {
     onMessagesChanged: (messages: AgentWidgetMessage[]) => void;
     onStatusChanged: (status: AgentWidgetSessionStatus) => void;
@@ -6369,6 +6502,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;
 };
 declare class AgentWidgetSession {
     private config;
@@ -6381,6 +6525,12 @@ declare class AgentWidgetSession {
     private sequenceCounter;
     private clientSession;
     private agentExecution;
+    private resumable;
+    private activeAssistantMessageId;
+    private reconnecting;
+    private reconnectController;
+    private reconnectControllerPromise;
+    private executionStateTimer;
     private artifacts;
     private selectedArtifactId;
     private webMcpInflightKeys;
@@ -6652,6 +6802,19 @@ declare class AgentWidgetSession {
     connectStream(stream: ReadableStream<Uint8Array>, 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>;
     /**
      * Install the native approval-bubble confirm handler on the WebMCP bridge
@@ -6835,6 +6998,73 @@ declare class AgentWidgetSession {
     hydrateMessages(messages: AgentWidgetMessage[]): void;
     hydrateArtifacts(artifacts: PersonaArtifactRecord[], selectedId?: string | null): void;
     private handleEvent;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** The narrow surface the lazily-loaded reconnect loop drives. */
+    private buildReconnectHost;
+    /** Public manual retry (e.g. a "Reconnect" button). */
+    reconnectNow(): void;
+    /**
+     * 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`.
+     */
+    resumeFromHandle(resume: {
+        executionId: string;
+        after: string;
+    }): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Drop the resume handle and notify the host (`onExecutionState(null)`). */
+    private clearResumable;
+    /**
+     * 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;
+    /** The current durable resume handle, if any (read-only). */
+    getResumableHandle(): ResumableHandle | null;
     private setStatus;
     private setStreaming;
     /**
@@ -7013,6 +7243,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;
     /**