@runtypelabs/persona 4.20.0 → 4.21.1

package/src/session.ts

@@ -1553,6 +1553,7 @@ export class AgentWidgetSession {
 
   /** Conversation-scoped caches that must not leak across records. */
   private resetConversationScopedState(): void {
+    this.historyInternals.setStoredResumableHandle?.(null);
     this.agentExecution = null;
     this.clearArtifactState();
     this.webMcpInflightKeys.clear();
@@ -3341,9 +3342,16 @@ export class AgentWidgetSession {
     }
 
     try {
-      const response = await this.client.resumeFlow(executionId, {
-        [toolName]: answer,
-      });
+      const response = await this.client.resumeFlow(
+        executionId,
+        { [toolName]: answer },
+        {
+          after:
+            this.resumable?.executionId === executionId
+              ? this.resumable.lastEventId
+              : undefined,
+        },
+      );
 
       if (!response.ok) {
         const errorData = await response.json().catch(() => null);
@@ -3566,10 +3574,12 @@ export class AgentWidgetSession {
   /**
    * Resolve one or more parallel local-tool awaits sharing one paused
    * executionId with a SINGLE `/resume` (core#3878); `resolveWebMcpToolCall`
-   * delegates size-1 resolves here after its guards. Each call is executed
-   * against the page registry concurrently: every gated call renders its own
-   * native approval bubble, and a sibling's confirm Promise never blocks
-   * another's execution. Outputs are keyed by per-call `webMcpToolCallId`
+   * delegates size-1 resolves here after its guards. By default each call is
+   * executed against the page registry concurrently: every gated call renders
+   * its own native approval bubble, and a sibling's confirm Promise never
+   * blocks another's execution. With `webmcp.execution: "sequential"` the
+   * calls run one at a time in emission order instead (see the config docs
+   * for when that matters). Outputs are keyed by per-call `webMcpToolCallId`
    * (server prefers it over tool name; name-keying remains the fallback for
    * legacy single/distinct-tool turns), so two calls to the SAME tool no longer
    * collide. The server is tolerant: any call we omit (declined-after-abort,
@@ -3599,111 +3609,125 @@ export class AgentWidgetSession {
     this.webMcpResolveControllers.add(batchController);
     this.setStreaming(true);
 
-    // Phase 1: execute every pending call concurrently. A null result means
-    // the call was deduped, aborted, or threw; it's omitted from the resume and
-    // (per the tolerant server) re-pauses for retry.
-    const executed = await Promise.all(
-      snapshots.map(async (toolMessage) => {
-        const wireToolName = toolMessage.toolCall?.name;
-        const callId = toolMessage.toolCall?.id;
-        if (!wireToolName || !callId) return null;
-
-        const dedupeKey = `${executionId}:${callId}`;
-        if (
-          this.webMcpInflightKeys.has(dedupeKey) ||
-          this.webMcpResolvedKeys.has(dedupeKey) ||
-          this.isSuggestRepliesAlreadyResolved(toolMessage)
-        ) {
-          return null;
-        }
-        this.webMcpInflightKeys.add(dedupeKey);
-        claimedKeys.push(dedupeKey);
-
-        // Clear the awaiting flag and keep the tool bubble running while the
-        // browser-side WebMCP promise is in flight. The initial `step_await`
-        // only means the server paused for a local tool; it is not completion.
-        const startedAt = this.markWebMcpToolRunning(toolMessage);
-
-        // Per-call id wins for resume keying; fall back to the wire tool name
-        // for legacy servers that don't emit `webMcpToolCallId`.
-        const resumeKey =
-          toolMessage.agentMetadata?.webMcpToolCallId ?? wireToolName;
-
-        // Built-in fire-and-forget tool: no bridge, no confirm gate, no
-        // browser-side execution: the chips render from the message list and
-        // the canned output joins the batch's single /resume.
-        if (wireToolName === SUGGEST_REPLIES_TOOL_NAME) {
-          return {
-            dedupeKey,
-            resumeKey,
-            output: suggestRepliesToolResult(),
-            toolMessage,
-            startedAt,
-            completedAt: Date.now(),
-          };
-        }
+    // Phase 1: execute every pending call. A null result means the call was
+    // deduped, aborted, or threw; it's omitted from the resume and (per the
+    // tolerant server) re-pauses for retry.
+    const executeOne = async (
+      toolMessage: AgentWidgetMessage,
+    ): Promise<ExecutedWebMcpTool | null> => {
+      const wireToolName = toolMessage.toolCall?.name;
+      const callId = toolMessage.toolCall?.id;
+      if (!wireToolName || !callId) return null;
+
+      const dedupeKey = `${executionId}:${callId}`;
+      if (
+        this.webMcpInflightKeys.has(dedupeKey) ||
+        this.webMcpResolvedKeys.has(dedupeKey) ||
+        this.isSuggestRepliesAlreadyResolved(toolMessage)
+      ) {
+        return null;
+      }
+      this.webMcpInflightKeys.add(dedupeKey);
+      claimedKeys.push(dedupeKey);
+
+      // Clear the awaiting flag and keep the tool bubble running while the
+      // browser-side WebMCP promise is in flight. The initial `step_await`
+      // only means the server paused for a local tool; it is not completion.
+      const startedAt = this.markWebMcpToolRunning(toolMessage);
+
+      // Per-call id wins for resume keying; fall back to the wire tool name
+      // for legacy servers that don't emit `webMcpToolCallId`.
+      const resumeKey =
+        toolMessage.agentMetadata?.webMcpToolCallId ?? wireToolName;
+
+      // Built-in fire-and-forget tool: no bridge, no confirm gate, no
+      // browser-side execution: the chips render from the message list and
+      // the canned output joins the batch's single /resume.
+      if (wireToolName === SUGGEST_REPLIES_TOOL_NAME) {
+        return {
+          dedupeKey,
+          resumeKey,
+          output: suggestRepliesToolResult(),
+          toolMessage,
+          startedAt,
+          completedAt: Date.now(),
+        };
+      }
 
-        const execPromise = this.client.executeWebMcpToolCall(
-          wireToolName,
-          toolMessage.toolCall?.args,
-          batchController.signal,
-        );
+      const execPromise = this.client.executeWebMcpToolCall(
+        wireToolName,
+        toolMessage.toolCall?.args,
+        batchController.signal,
+      );
 
-        let output: unknown;
-        if (!execPromise) {
-          output = {
-            isError: true,
-            content: [
-              { type: "text", text: "WebMCP not enabled on this widget." },
-            ],
-          };
-        } else {
-          try {
-            output = await execPromise;
-          } catch (error) {
-            const isAbortError =
-              error instanceof Error &&
-              (error.name === "AbortError" ||
-                error.message.includes("aborted") ||
-                error.message.includes("abort"));
-            if (!isAbortError) {
-              this.callbacks.onError?.(
-                error instanceof Error ? error : new Error(String(error)),
-              );
-            }
-            this.markWebMcpToolComplete(
-              toolMessage,
-              buildWebMcpErrorResult(
-                isAbortError
-                  ? "Aborted by cancel()"
-                  : getWebMcpErrorMessage(error),
-              ),
-              startedAt,
+      let output: unknown;
+      if (!execPromise) {
+        output = {
+          isError: true,
+          content: [
+            { type: "text", text: "WebMCP not enabled on this widget." },
+          ],
+        };
+      } else {
+        try {
+          output = await execPromise;
+        } catch (error) {
+          const isAbortError =
+            error instanceof Error &&
+            (error.name === "AbortError" ||
+              error.message.includes("aborted") ||
+              error.message.includes("abort"));
+          if (!isAbortError) {
+            this.callbacks.onError?.(
+              error instanceof Error ? error : new Error(String(error)),
             );
-            // Release the dedupe claim so a re-emit can retry this call.
-            this.webMcpInflightKeys.delete(dedupeKey);
-            return null;
           }
-        }
-        if (batchController.signal.aborted) {
           this.markWebMcpToolComplete(
             toolMessage,
-            buildWebMcpErrorResult("Aborted by cancel()"),
+            buildWebMcpErrorResult(
+              isAbortError
+                ? "Aborted by cancel()"
+                : getWebMcpErrorMessage(error),
+            ),
             startedAt,
           );
+          // Release the dedupe claim so a re-emit can retry this call.
           this.webMcpInflightKeys.delete(dedupeKey);
           return null;
         }
-        return {
-          dedupeKey,
-          resumeKey,
-          output,
+      }
+      if (batchController.signal.aborted) {
+        this.markWebMcpToolComplete(
           toolMessage,
+          buildWebMcpErrorResult("Aborted by cancel()"),
           startedAt,
-          completedAt: Date.now(),
-        };
-      }),
-    );
+        );
+        this.webMcpInflightKeys.delete(dedupeKey);
+        return null;
+      }
+      return {
+        dedupeKey,
+        resumeKey,
+        output,
+        toolMessage,
+        startedAt,
+        completedAt: Date.now(),
+      };
+    };
+
+    // Parallel (default): a gated sibling's approval never blocks another's
+    // execution. Sequential: one at a time in emission order, so tools that
+    // share page state (a canvas, a form) don't interleave; the next call
+    // starts only once the previous one has settled, approval included.
+    let executed: Array<ExecutedWebMcpTool | null>;
+    if (this.config.webmcp?.execution === "sequential") {
+      executed = [];
+      for (const toolMessage of snapshots) {
+        executed.push(await executeOne(toolMessage));
+      }
+    } else {
+      executed = await Promise.all(snapshots.map(executeOne));
+    }
 
     let ready: ExecutedWebMcpTool[] = [];
     try {
@@ -3720,6 +3744,10 @@ export class AgentWidgetSession {
 
       const response = await this.client.resumeFlow(executionId, toolOutputs, {
         signal: batchController.signal,
+        after:
+          this.resumable?.executionId === executionId
+            ? this.resumable.lastEventId
+            : undefined,
       });
       if (!response.ok) {
         const errorData = await response.json().catch(() => null);
@@ -3895,7 +3923,13 @@ export class AgentWidgetSession {
     const response = await this.client.resumeFlow(
       executionId,
       { [resumeKey]: output },
-      { signal: options?.signal },
+      {
+        signal: options?.signal,
+        after:
+          this.resumable?.executionId === executionId
+            ? this.resumable.lastEventId
+            : undefined,
+      },
     );
     if (!response.ok) {
       const errorData = await response.json().catch(() => null);
@@ -4323,9 +4357,11 @@ export class AgentWidgetSession {
       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();
+        // A client-tool pause is an intentional stream end but NOT a terminal:
+        // retain its cursor so `/client/resume` can attach after the await
+        // frame instead of replaying the whole turn. Real terminals and
+        // ordinary non-durable idles still clear the handle.
+        if (!this.isAwaitPending()) 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

package/src/session.webmcp.test.ts

@@ -13,9 +13,10 @@ const makeSession = (overrides?: {
   resumeOk?: boolean;
   isOperational?: boolean;
   executeImpl?: () => Promise<WebMcpToolResult>;
+  webmcp?: Record<string, unknown>;
 }) => {
   const session = new AgentWidgetSession(
-    { apiUrl: "http://test", webmcp: { enabled: true } },
+    { apiUrl: "http://test", webmcp: { enabled: true, ...overrides?.webmcp } },
     {
       onMessagesChanged: () => undefined,
       onStatusChanged: () => undefined,
@@ -949,6 +950,52 @@ describe("AgentWidgetSession: WebMCP parallel batched resume (core#3878)", () =>
     expect(Object.keys(toolOutputs).sort()).toEqual(["toolu_A", "toolu_B"]);
   });
 
+  it("webmcp.execution: 'sequential' runs siblings one at a time, in emission order", async () => {
+    // Paint-style tools share page state (select tool + color, then draw), so
+    // a multi-call turn must not interleave. The second execute must not even
+    // START until the first has resolved; the batch still posts ONE /resume.
+    let releaseA: (r: WebMcpToolResult) => void = () => undefined;
+    let releaseB: (r: WebMcpToolResult) => void = () => undefined;
+    const pA = new Promise<WebMcpToolResult>((r) => (releaseA = r));
+    const pB = new Promise<WebMcpToolResult>((r) => (releaseB = r));
+    const started: string[] = [];
+
+    const { session, resumeSpy } = makeSession({
+      webmcp: { execution: "sequential" },
+    });
+    const client = (session as unknown as { client: Record<string, unknown> })
+      .client;
+    (client.executeWebMcpToolCall as ReturnType<typeof vi.fn>).mockImplementation(
+      (_name: string, args: { sku: string }) => {
+        started.push(args.sku);
+        return args.sku === "SHOE-001" ? pA : pB;
+      },
+    );
+
+    feed(session, parallelAwait("toolu_A", "SHOE-001"));
+    feed(session, parallelAwait("toolu_B", "SHOE-007"));
+    endStream(session);
+    await flushMicrotasks();
+
+    // Only the first call is in flight; the second waits on it.
+    expect(started).toEqual(["SHOE-001"]);
+    expect(resumeSpy).not.toHaveBeenCalled();
+
+    releaseA({ content: [{ type: "text", text: "a" }] });
+    await flushMicrotasks();
+    expect(started).toEqual(["SHOE-001", "SHOE-007"]);
+    expect(resumeSpy).not.toHaveBeenCalled();
+
+    releaseB({ content: [{ type: "text", text: "b" }] });
+    await flushMicrotasks();
+    expect(resumeSpy).toHaveBeenCalledTimes(1);
+    const toolOutputs = (resumeSpy.mock.calls[0]! as unknown[])[1] as Record<
+      string,
+      unknown
+    >;
+    expect(Object.keys(toolOutputs).sort()).toEqual(["toolu_A", "toolu_B"]);
+  });
+
   it("records elapsed time for each resolved tool in a batched WebMCP resume", async () => {
     vi.useFakeTimers();
     vi.setSystemTime(1_000);

package/src/types.ts

@@ -908,6 +908,22 @@ export type AgentWidgetWebMcpConfig = {
    * `window.confirm` fallback only applies when no widget UI is attached.
    */
   onConfirm?: WebMcpConfirmHandler;
+  /**
+   * How the widget runs the `webmcp:*` calls of ONE turn when the model emits
+   * several at once.
+   *
+   * - `'parallel'` (default): every call executes concurrently and a gated
+   *   sibling's approval never blocks another's execution. Right for
+   *   independent, order-insensitive tools (catalog lookups, add-to-cart).
+   * - `'sequential'`: calls execute one at a time, in the order the model
+   *   emitted them; the next starts only after the previous one settles
+   *   (including its approval bubble). Use this when the page tools share
+   *   mutable state that concurrent execution would interleave, e.g. a
+   *   canvas where every stroke selects a color/tool before drawing.
+   *
+   * Either way, all outputs still return to the server in a single `/resume`.
+   */
+  execution?: 'parallel' | 'sequential';
 };
 
 /**
@@ -5674,6 +5690,8 @@ export type ClientSession = {
   targetId?: string;
   /** Opaque change token; differs whenever the conversation transcript mutated. */
   conversationRevision?: string;
+  /** Server-negotiated durable reconnect support for this client-token session. */
+  durableRecovery?: { enabled: boolean };
   /** Visitor grant backing history. `token` appears only at mint. */
   visitor?: ClientVisitorGrant;
   /** Configuration from the server */
@@ -5714,6 +5732,8 @@ export type ClientInitResponse = {
   conversationId?: string;
   targetId?: string;
   conversationRevision?: string;
+  /** Present on servers that understand the durable-recovery negotiation. */
+  durableRecovery?: { enabled: boolean };
   visitor?: ClientVisitorGrant;
   config: {
     welcomeMessage: string | null;
@@ -5805,6 +5825,16 @@ export interface WidgetHistoryInternals {
   /** Persist the revision beside the active conversation id (internal only). */
   setStoredConversationRevision?: (revision: string | null) => void;
   getStoredConversationRevision?: () => string | null;
+  /** Internal client-token durable resume handle, persisted with widget state. */
+  setStoredResumableHandle?: (
+    handle: { executionId: string; after: string } | null
+  ) => void;
+  getStoredResumableHandle?: () => {
+    executionId: string;
+    after: string;
+  } | null;
+  /** True only while Persona owns a persisted client-token recovery attempt. */
+  shouldResumeDurableConversation?: () => boolean;
   /** "Show earlier messages" cursor for the persisted transcript. */
   setStoredMessageCursor?: (cursor: string | null) => void;
   getStoredMessageCursor?: () => string | null;

package/src/ui.history-lifecycle.test.ts

@@ -212,7 +212,7 @@ describe("history controller lifecycle", () => {
       expect(window.localStorage.getItem(keysA.storageKey)).toBe("cvt_alpha");
     });
 
-    it("drops the store entirely when history is disabled", async () => {
+    it("keeps the recovery credential store when history UI is disabled", async () => {
       await seed();
       const { controller } = mount({
         clientToken: TOKEN_A,
@@ -224,7 +224,7 @@ describe("history controller lifecycle", () => {
       await flush(20);
 
       expect(recorder.instances.length).toBe(1);
-      expect(recorder.instances[0]!.destroy).toHaveBeenCalledTimes(1);
+      expect(recorder.instances[0]!.destroy).not.toHaveBeenCalled();
       expect(recorder.instances[0]!.clear).not.toHaveBeenCalled();
     });
   });

package/src/ui.ts

@@ -1054,6 +1054,8 @@ export const createAgentExperience = (
     messagePersistenceDisabled
       ? null
       : (config.storageAdapter ?? createLocalStorageAdapter());
+  const personaOwnsClientTokenRecovery =
+    Boolean(config.clientToken) && typeof config.reconnectStream !== "function";
   let persistentMetadata: Record<string, unknown> = {};
   let pendingStoredState: Promise<AgentWidgetStoredState | null> | null = null;
   // Resolves once stored state has been applied (or its load failed). Every
@@ -5313,6 +5315,17 @@ export const createAgentExperience = (
         ? getMessagesForPersistence()
         : [];
 
+    const durableHandle =
+      personaOwnsClientTokenRecovery && session?.getResumableHandle();
+    if (durableHandle) {
+      persistentMetadata = {
+        ...persistentMetadata,
+        durableResume: {
+          executionId: durableHandle.executionId,
+          after: durableHandle.lastEventId,
+        },
+      };
+    }
     const payload: AgentWidgetStoredState = {
       messages,
       metadata: persistentMetadata,
@@ -8370,6 +8383,20 @@ export const createAgentExperience = (
     const stored = persistentMetadata[key];
     return typeof stored === 'string' ? stored : null;
   };
+  const readStoredResumableHandle = (): {
+    executionId: string;
+    after: string;
+  } | null => {
+    const stored = persistentMetadata.durableResume;
+    if (!stored || typeof stored !== 'object') return null;
+    const candidate = stored as Record<string, unknown>;
+    return typeof candidate.executionId === 'string' &&
+      candidate.executionId.length > 0 &&
+      typeof candidate.after === 'string' &&
+      candidate.after.length > 0
+      ? { executionId: candidate.executionId, after: candidate.after }
+      : null;
+  };
   if (config.clientToken) {
     config = {
       ...config,
@@ -8394,11 +8421,11 @@ export const createAgentExperience = (
     };
   }
 
-  // Visitor-history credential store, keyed on (clientToken, keyPrefix,
-  // persistence-disabled). Owned here and injected into every client the
-  // session builds; `update()` rebuilds it when that tuple changes.
+  // Exact-browser visitor credential store, keyed on (clientToken, keyPrefix,
+  // persistence-disabled). Durable reconnect and optional visitor history use
+  // the same credential but negotiate independent server capabilities.
   const historyStoreToken = (): string | null =>
-    config.features?.history?.enabled === true ? (config.clientToken ?? null) : null;
+    config.clientToken ?? null;
   const buildVisitorStore = (token: string) =>
     createVisitorStore(token, currentKeyPrefix(), config.persistState === false);
   const initialStoreToken = historyStoreToken();
@@ -8446,6 +8473,16 @@ export const createAgentExperience = (
         pendingDisplayProjections: pending,
       }));
     },
+    getStoredResumableHandle: readStoredResumableHandle,
+    setStoredResumableHandle: (handle) => {
+      if (!handle) {
+        dropMetadataKey('durableResume');
+        return;
+      }
+      updateSessionMetadata((prev) => ({ ...prev, durableResume: handle }));
+    },
+    shouldResumeDurableConversation: () =>
+      personaOwnsClientTokenRecovery && readStoredResumableHandle() !== null,
     ...(hostOwnsConversationId
       ? {}
       : {
@@ -8463,6 +8500,40 @@ export const createAgentExperience = (
           },
         }),
   };
+
+  // Runtype client-token widgets already possess the session, conversation,
+  // and exact-browser visitor credential needed by the public reconnect route.
+  // Install Persona's existing reconnect hooks by default so this mode follows
+  // the same path as host-configured durable dashboard chats.
+  if (personaOwnsClientTokenRecovery) {
+    const hostExecutionState = config.onExecutionState;
+    const recoveryWindow = mount.ownerDocument.defaultView;
+    let pageExitInProgress = false;
+    const markPageExit = () => (pageExitInProgress = true);
+    const markPageActive = () => (pageExitInProgress = false);
+    recoveryWindow?.addEventListener("pagehide", markPageExit);
+    recoveryWindow?.addEventListener("pageshow", markPageActive);
+    destroyCallbacks.push(() => {
+      recoveryWindow?.removeEventListener("pagehide", markPageExit);
+      recoveryWindow?.removeEventListener("pageshow", markPageActive);
+    });
+    config = {
+      ...config,
+      reconnectStream:
+        config.reconnectStream ??
+        ((ctx) => session.getClient().reconnectClientTokenStream(ctx)),
+      onExecutionState: (handle) => {
+        if (handle || !pageExitInProgress) {
+          historyInternals.setStoredResumableHandle?.(
+            handle
+              ? { executionId: handle.executionId, after: handle.lastEventId }
+              : null
+          );
+        }
+        hostExecutionState?.(handle);
+      },
+    };
+  }
   const syncVisitorStore = () => {
     const token = historyStoreToken();
     if (
@@ -8572,6 +8643,18 @@ export const createAgentExperience = (
   let activeStreamingTextCandidate: { index: number; id: string } | null = null;
   let pendingStreamingTextMessages: AgentWidgetMessage[] | null = null;
   let streamingTextRAF: number | null = null;
+  let pendingDurablePersistenceMessages: AgentWidgetMessage[] | null = null;
+
+  const persistMessages = (messages: AgentWidgetMessage[]) => {
+    if (!personaOwnsClientTokenRecovery) return persistState(messages);
+    pendingDurablePersistenceMessages = messages;
+    queueMicrotask(() => {
+      if (pendingDurablePersistenceMessages === messages) {
+        pendingDurablePersistenceMessages = null;
+        persistState(messages);
+      }
+    });
+  };
 
   const applyMessagesChanged = (messages: AgentWidgetMessage[]) => {
     lastAppliedMessages = messages;
@@ -8632,7 +8715,7 @@ export const createAgentExperience = (
     }
 
     voiceState.lastUserMessageWasVoice = Boolean(lastUserMessage?.viaVoice);
-    persistState(messages);
+    persistMessages(messages);
     syncComposerBarPeek();
   };
 
@@ -11297,8 +11380,13 @@ export const createAgentExperience = (
   // the restored conversation. Fires AFTER hydration so the trailing partial
   // assistant bubble exists for the replay to append to.
   const maybeBootResume = () => {
-    if (config.resume && typeof config.reconnectStream === "function") {
-      session.resumeFromHandle(config.resume);
+    const resume =
+      config.resume ??
+      (personaOwnsClientTokenRecovery
+        ? historyInternals.getStoredResumableHandle?.()
+        : null);
+    if (resume && typeof config.reconnectStream === "function") {
+      session.resumeFromHandle(resume);
     }
   };