@runtypelabs/persona 3.21.2 → 3.22.0

package/src/session.ts

@@ -1,9 +1,11 @@
 import { AgentWidgetClient, type SSEEventCallback } from "./client";
+import { isWebMcpToolName } from "./webmcp-bridge";
 import {
   AgentWidgetConfig,
   AgentWidgetEvent,
   AgentWidgetMessage,
   AgentWidgetApproval,
+  WebMcpConfirmInfo,
   AgentExecutionState,
   ClientSession,
   ContentPart,
@@ -49,6 +51,31 @@ type SessionCallbacks = {
   }) => void;
 };
 
+/**
+ * Build the user-facing content shown when a dispatch fails before any
+ * assistant content streamed back. This fires on real network/server errors
+ * (connection refused, CORS, 4xx/5xx, malformed stream) — not just an
+ * un-wired proxy — so the copy stays honest about the failure and surfaces the
+ * underlying reason to help with debugging.
+ *
+ * Callers can override the copy via `config.errorMessage` (a static string or
+ * a function of the error). An override that returns an empty string yields ""
+ * here, which the caller treats as "suppress the fallback bubble".
+ */
+function buildDispatchErrorContent(
+  error: unknown,
+  override?: AgentWidgetConfig["errorMessage"]
+): string {
+  const err = error instanceof Error ? error : new Error(String(error));
+
+  if (typeof override === "string") return override;
+  if (typeof override === "function") return override(err);
+
+  const base =
+    "Sorry — I couldn't reach the assistant. The chat service didn't respond. Please check that your proxy or backend is running and reachable, then try again.";
+  return err.message ? `${base}\n\n_Details: ${err.message}_` : base;
+}
+
 export class AgentWidgetSession {
   private client: AgentWidgetClient;
   private messages: AgentWidgetMessage[];
@@ -66,6 +93,67 @@ export class AgentWidgetSession {
   private artifacts = new Map<string, PersonaArtifactRecord>();
   private selectedArtifactId: string | null = null;
 
+  // WebMCP dedupe — keys are `${executionId}:${toolCallId}` so they're
+  // naturally scoped to a single dispatch. A later dispatch (new executionId)
+  // that happens to recycle a `toolCall.id` never collides with prior entries,
+  // and a stale re-emit from an in-flight prior dispatch stays blocked because
+  // its executionId is still in the set.
+  //
+  //   webMcpInflightKeys  — currently executing; cleared on completion of
+  //                         EITHER /resume success OR /resume throw. Blocks
+  //                         concurrent re-fire during the resolve round-trip.
+  //   webMcpResolvedKeys  — /resume HTTP returned 2xx; not cleared on a new
+  //                         dispatch (executionId scoping makes that
+  //                         unnecessary). Blocks stale step_await re-emits
+  //                         for the same execution.
+  //
+  // If `/resume` throws (network error, server 5xx), we DO want a retry path:
+  // the dispatch is recoverable. Such a tool stays in neither set, so a
+  // subsequent re-emit will re-trigger.
+  private webMcpInflightKeys: Set<string> = new Set();
+  private webMcpResolvedKeys: Set<string> = new Set();
+  // Per-resolve AbortControllers, kept in a set so multiple `webmcp:*`
+  // step_await resolves in one turn never abort one another. The shared
+  // `this.abortController` is intentionally NOT used by resolveWebMcpToolCall:
+  // in a CHAINED turn (tool A → /resume → tool B, where the server emits B's
+  // step_await inside A's resume SSE stream) the shared controller is still
+  // piping A's resume stream — the very stream that just delivered B. Aborting
+  // it mid-chain (the prior shared-controller pre-abort) tore that stream down,
+  // so B never reached execute() and its /resume was never POSTed, pausing the
+  // dispatch forever. cancel(), clearMessages(), hydrateMessages(), and
+  // sendMessage() iterate this set to tear every in-flight resolve down on a
+  // real stop / new turn.
+  private webMcpResolveControllers: Set<AbortController> = new Set();
+  // Bumped on every teardown / new-turn boundary (cancel, clearMessages,
+  // hydrateMessages, sendMessage). A resolveWebMcpToolCall deferred via
+  // queueMicrotask captures the epoch at queue time and bails if it changed,
+  // so a resolve queued just before a teardown can't escape it by installing a
+  // fresh controller after the set was already cleared.
+  private webMcpEpoch = 0;
+  // WebMCP native approval-bubble gate. When no custom `webmcp.onConfirm` is
+  // supplied, the bridge's confirm handler routes here: we inject an
+  // approval-variant message and park the bridge on a Promise that resolves
+  // when the user clicks Approve/Deny (see requestWebMcpApproval /
+  // resolveWebMcpApproval). Resolvers are keyed by the approval message id.
+  private webMcpApprovalResolvers: Map<string, (approved: boolean) => void> =
+    new Map();
+  private webMcpApprovalSeq = 0;
+  // Parallel local-tool batching (core#3878). A single model turn can emit
+  // multiple `step_await(local_tool_required)` events for ONE paused
+  // executionId — including two PARALLEL calls to the SAME tool ("add SHOE-001
+  // and SHOE-007"). Those collapse to an identical `toolId`/`index` and differ
+  // only by the per-call `webMcpToolCallId`. We collect all awaits for an
+  // executionId that arrive in the same stream tick, then post ONE `/resume`
+  // keyed by `webMcpToolCallId` — NOT one `/resume` per tool keyed by name
+  // (which collides for same-tool calls, and whose concurrent posts on one
+  // execution raced → the second 404'd → the turn hung). Keyed by executionId;
+  // `seen` dedupes duplicate step_await re-emits within a batch. Cleared on
+  // every teardown via `abortWebMcpResolves`.
+  private webMcpAwaitBatches: Map<
+    string,
+    { snapshots: AgentWidgetMessage[]; seen: Set<string> }
+  > = new Map();
+
   // Voice support
   private voiceProvider: VoiceProvider | null = null;
   private voiceActive = false;
@@ -81,6 +169,7 @@ export class AgentWidgetSession {
     }));
     this.messages = this.sortMessages(this.messages);
     this.client = new AgentWidgetClient(config);
+    this.wireDefaultWebMcpConfirm();
 
     // Hydrate artifacts from config (mirrors `initialMessages`). Restored
     // records are forced to `status: "complete"` — a mid-stream artifact should
@@ -511,9 +600,20 @@ export class AgentWidgetSession {
   }
 
   public updateConfig(next: AgentWidgetConfig) {
+    // Replacing the client invalidates every in-flight WebMCP resolve, buffered
+    // parallel-await batch, and pending approval bubble tied to the OLD client/
+    // session. Tear them down BEFORE the swap (the new client has no session
+    // yet) so a deferred batch flush or a parked confirm can't fire against the
+    // fresh client — in client-token mode that would POST /resume without a
+    // valid sessionId and strand the paused turn. Mirrors clearMessages' WebMCP
+    // reset; the client swap already abandons any in-flight stream regardless.
+    this.abortWebMcpResolves();
+    this.webMcpInflightKeys.clear();
+    this.webMcpResolvedKeys.clear();
     const prevSSECallback = this.client.getSSEEventCallback();
     this.config = { ...this.config, ...next };
     this.client = new AgentWidgetClient(this.config);
+    this.wireDefaultWebMcpConfirm();
     if (prevSSECallback) {
       this.client.setSSEEventCallback(prevSSECallback);
     }
@@ -773,6 +873,11 @@ export class AgentWidgetSession {
 
     this.stopSpeaking();
     this.abortController?.abort();
+    // A new user turn supersedes any in-flight WebMCP resolve from the prior
+    // turn. Tear them down here (they own controllers separate from the shared
+    // one) so a lingering resolve can't race the new dispatch or post a stale
+    // /resume against a superseded execution.
+    this.abortWebMcpResolves();
 
     // Generate IDs for both user message and expected assistant response
     const userMessageId = generateUserMessageId();
@@ -818,16 +923,23 @@ export class AgentWidgetSession {
          error.message.includes('abort'));
 
       if (!isAbortError) {
-        const fallback: AgentWidgetMessage = {
-          id: assistantMessageId, // Use the pre-generated ID for fallback too
-          role: "assistant",
-          createdAt: new Date().toISOString(),
-          content:
-            "It looks like the proxy isn't returning a real response yet. Here's a sample message so you can continue testing locally.",
-          sequence: this.nextSequence()
-        };
+        const content = buildDispatchErrorContent(
+          error,
+          this.config.errorMessage
+        );
+        // An override that returns "" suppresses the fallback bubble entirely
+        // (onError still fires below).
+        if (content) {
+          const fallback: AgentWidgetMessage = {
+            id: assistantMessageId, // Use the pre-generated ID for fallback too
+            role: "assistant",
+            createdAt: new Date().toISOString(),
+            content,
+            sequence: this.nextSequence()
+          };
 
-        this.appendMessage(fallback);
+          this.appendMessage(fallback);
+        }
       }
 
       this.setStatus("idle");
@@ -881,23 +993,43 @@ export class AgentWidgetSession {
         this.handleEvent
       );
     } catch (error) {
-      const fallback: AgentWidgetMessage = {
-        id: assistantMessageId,
-        role: "assistant",
-        createdAt: new Date().toISOString(),
-        content:
-          "It looks like the proxy isn't returning a real response yet. Here's a sample message so you can continue testing locally.",
-        sequence: this.nextSequence()
-      };
+      // 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.
+      const isAbortError =
+        error instanceof Error &&
+        (error.name === 'AbortError' ||
+         error.message.includes('aborted') ||
+         error.message.includes('abort'));
 
-      this.appendMessage(fallback);
+      if (!isAbortError) {
+        const content = buildDispatchErrorContent(
+          error,
+          this.config.errorMessage
+        );
+        // An override that returns "" suppresses the fallback bubble entirely
+        // (onError still fires below).
+        if (content) {
+          const fallback: AgentWidgetMessage = {
+            id: assistantMessageId,
+            role: "assistant",
+            createdAt: new Date().toISOString(),
+            content,
+            sequence: this.nextSequence()
+          };
+
+          this.appendMessage(fallback);
+        }
+      }
       this.setStatus("idle");
       this.setStreaming(false);
       this.abortController = null;
-      if (error instanceof Error) {
-        this.callbacks.onError?.(error);
-      } else {
-        this.callbacks.onError?.(new Error(String(error)));
+      if (!isAbortError) {
+        if (error instanceof Error) {
+          this.callbacks.onError?.(error);
+        } else {
+          this.callbacks.onError?.(new Error(String(error)));
+        }
       }
     }
   }
@@ -938,14 +1070,111 @@ export class AgentWidgetSession {
       );
     } catch (error) {
       this.setStatus("error");
-      this.setStreaming(false);
-      this.abortController = null;
+      // Mirror the idle/error handlers: a failed resume stream must not tear
+      // down streaming/abortController while another WebMCP resolve is still
+      // confirming or executing. The in-flight resolve's `finally` owns the
+      // teardown once `webMcpResolveControllers` drains.
+      if (this.webMcpResolveControllers.size === 0) {
+        this.setStreaming(false);
+        this.abortController = null;
+      }
       this.callbacks.onError?.(
         error instanceof Error ? error : new Error(String(error))
       );
     }
   }
 
+  /**
+   * Install the native approval-bubble confirm handler on the WebMCP bridge
+   * when the integrator hasn't supplied a custom `webmcp.onConfirm`. Without
+   * this, the bridge falls back to a blunt `window.confirm`. Safe to call
+   * repeatedly (e.g. after the client is re-created in `updateConfig`).
+   */
+  private wireDefaultWebMcpConfirm(): void {
+    const webmcp = this.config.webmcp;
+    if (webmcp?.enabled === true && !webmcp.onConfirm) {
+      this.client.setWebMcpConfirmHandler((info) =>
+        this.requestWebMcpApproval(info)
+      );
+    }
+  }
+
+  /**
+   * Default WebMCP confirm gate: render Persona's native in-panel approval
+   * bubble and resolve when the user clicks Approve/Deny. Returns immediately
+   * with `true` when `webmcp.autoApprove(info)` opts the tool out of the gate
+   * (e.g. a read-only catalog search), so no bubble is shown. The bridge
+   * awaits this Promise before executing the page tool.
+   */
+  public requestWebMcpApproval(info: WebMcpConfirmInfo): Promise<boolean> {
+    // Per-tool policy hook — auto-allow opted-out tools without any UI. A
+    // throwing predicate must not block the call, so fall through to an
+    // explicit gate on error.
+    try {
+      if (this.config.webmcp?.autoApprove?.(info) === true) {
+        return Promise.resolve(true);
+      }
+    } catch {
+      // fall through to explicit approval
+    }
+
+    const approval: AgentWidgetApproval = {
+      id: `webmcp-${++this.webMcpApprovalSeq}`,
+      status: "pending",
+      agentId: "",
+      executionId: "",
+      toolName: info.toolName,
+      toolType: "webmcp",
+      description:
+        info.description ?? `Allow the assistant to run ${info.toolName}?`,
+      parameters: info.args,
+    };
+    const approvalMessageId = `approval-${approval.id}`;
+
+    this.upsertMessage({
+      id: approvalMessageId,
+      role: "assistant",
+      content: "",
+      createdAt: new Date().toISOString(),
+      streaming: false,
+      variant: "approval",
+      approval,
+    });
+
+    return new Promise<boolean>((resolve) => {
+      this.webMcpApprovalResolvers.set(approvalMessageId, resolve);
+    });
+  }
+
+  /**
+   * Resolve a pending WebMCP approval bubble (from the Approve/Deny click in
+   * `ui.ts`). Updates the bubble to its resolved state and unblocks the
+   * bridge Promise parked in `requestWebMcpApproval`. No-op if already
+   * resolved (double-click, re-render).
+   */
+  public resolveWebMcpApproval(
+    approvalMessageId: string,
+    decision: "approved" | "denied"
+  ): void {
+    const resolve = this.webMcpApprovalResolvers.get(approvalMessageId);
+    if (!resolve) return;
+    this.webMcpApprovalResolvers.delete(approvalMessageId);
+
+    const existing = this.messages.find((m) => m.id === approvalMessageId);
+    if (existing?.approval) {
+      this.upsertMessage({
+        ...existing,
+        approval: {
+          ...existing.approval,
+          status: decision,
+          resolvedAt: Date.now(),
+        },
+      });
+    }
+
+    resolve(decision === "approved");
+  }
+
   /**
    * Resolve a tool approval request (approve or deny).
    * Updates the approval message status, calls the API (or custom onDecision),
@@ -1280,9 +1509,532 @@ export class AgentWidgetSession {
     }
   }
 
+  /**
+   * Collect a `webmcp:*` LOCAL-tool `step_await` into a per-executionId batch
+   * and schedule a single deferred flush. Parallel calls (core#3878) emit
+   * several `step_await`s for ONE paused execution within the same stream tick;
+   * buffering them and flushing once lets us post ONE `/resume` keyed by the
+   * per-call `webMcpToolCallId` rather than racing N name-keyed resumes on the
+   * same execution (which 404'd on the second and hung the turn).
+   *
+   * Deferred via `queueMicrotask` (epoch-guarded) for the same reason the old
+   * direct resolve was: handleEvent must return first so the dispatch's
+   * `connectStream` sees end-of-stream and releases the shared abortController
+   * before a resolve grabs it.
+   *
+   * Awaits without an `executionId` or `toolCall.id` can't be batched (no key)
+   * — route them straight to the single-call path, which surfaces the malformed
+   * wire shape via `onError` / an `isError` resume.
+   */
+  private enqueueWebMcpAwait(toolMessage: AgentWidgetMessage): void {
+    const executionId = toolMessage.agentMetadata?.executionId;
+    const callId = toolMessage.toolCall?.id;
+    if (!executionId || !callId) {
+      const queuedEpoch = this.webMcpEpoch;
+      queueMicrotask(() => {
+        if (queuedEpoch !== this.webMcpEpoch) return;
+        void this.resolveWebMcpToolCall(toolMessage);
+      });
+      return;
+    }
+
+    let batch = this.webMcpAwaitBatches.get(executionId);
+    if (!batch) {
+      batch = { snapshots: [], seen: new Set() };
+      this.webMcpAwaitBatches.set(executionId, batch);
+    }
+    // Duplicate step_await re-emit for a call already in this batch — ignore.
+    if (batch.seen.has(callId)) return;
+    batch.seen.add(callId);
+    batch.snapshots.push(toolMessage);
+    // NB: no flush is scheduled here. Flushing happens once the stream that is
+    // delivering these awaits ENDS (handleEvent's `status: idle` →
+    // scheduleWebMcpBatchFlush). Flushing per-await on the next microtask would
+    // race SSE chunk boundaries: two PARALLEL step_awaits split across separate
+    // `read()` chunks would flush the first alone and post a partial resume.
+    // Waiting for stream end guarantees every parallel await is collected first.
+  }
+
+  /**
+   * Flush every buffered local-tool await batch, one `/resume` per executionId.
+   * Called once a stream ends (`status: idle` / `error`) — by then all parallel
+   * `step_await`s the stream carried have been collected, even if split across
+   * SSE chunks. Deferred via `queueMicrotask` (epoch-guarded) so the idle
+   * handler returns first and the stream's end-of-stream teardown (streaming /
+   * abortController) settles before a resolve grabs them — the same ordering the
+   * single-call resolve always relied on.
+   */
+  private scheduleWebMcpBatchFlush(): void {
+    if (this.webMcpAwaitBatches.size === 0) return;
+    const queuedEpoch = this.webMcpEpoch;
+    queueMicrotask(() => {
+      if (queuedEpoch !== this.webMcpEpoch) return;
+      for (const executionId of [...this.webMcpAwaitBatches.keys()]) {
+        this.flushWebMcpAwaitBatch(executionId);
+      }
+    });
+  }
+
+  /**
+   * Run a buffered batch of local-tool awaits for one executionId. Size 1
+   * (single call, or distinct-tool turns that happened to arrive alone) takes
+   * the original single-call path; size >1 (parallel calls) takes the batched
+   * path that posts ONE `/resume`. The batch is removed from the map up front
+   * so any later sibling re-emit (e.g. from a re-pause) forms a fresh batch
+   * rather than mutating one already in flight.
+   */
+  private flushWebMcpAwaitBatch(executionId: string): void {
+    const batch = this.webMcpAwaitBatches.get(executionId);
+    if (!batch) return;
+    this.webMcpAwaitBatches.delete(executionId);
+    const { snapshots } = batch;
+    if (snapshots.length === 1) {
+      void this.resolveWebMcpToolCall(snapshots[0]);
+    } else if (snapshots.length > 1) {
+      void this.resolveWebMcpToolCallBatch(executionId, snapshots);
+    }
+  }
+
+  /**
+   * Resolve TWO OR MORE parallel local-tool awaits sharing one paused
+   * executionId with a SINGLE `/resume` (core#3878). 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`
+   * (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,
+   * dedupe, exec failure) simply re-pauses and is retried on its re-emit.
+   *
+   * Mirrors `resolveWebMcpToolCall`'s dedupe / abort / streaming machinery, but
+   * shares one resume POST and marks every resolved key on that POST's HTTP OK.
+   */
+  private async resolveWebMcpToolCallBatch(
+    executionId: string,
+    snapshots: AgentWidgetMessage[],
+  ): Promise<void> {
+    const claimedKeys: string[] = [];
+    const controllers: AbortController[] = [];
+    // Dedicated controller for the shared resume fetch so cancel() can abort it
+    // alongside the per-call ones (all live in webMcpResolveControllers).
+    const resumeController = new AbortController();
+    this.webMcpResolveControllers.add(resumeController);
+    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)
+        ) {
+          return null;
+        }
+        this.webMcpInflightKeys.add(dedupeKey);
+        claimedKeys.push(dedupeKey);
+
+        // Clear the awaiting flag so the local-tool UI doesn't linger.
+        this.upsertMessage({
+          ...toolMessage,
+          agentMetadata: {
+            ...toolMessage.agentMetadata,
+            awaitingLocalTool: false,
+          },
+        });
+
+        const controller = new AbortController();
+        this.webMcpResolveControllers.add(controller);
+        controllers.push(controller);
+
+        // 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;
+
+        const execPromise = this.client.executeWebMcpToolCall(
+          wireToolName,
+          toolMessage.toolCall?.args,
+          controller.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)),
+              );
+            }
+            // Release the dedupe claim so a re-emit can retry this call.
+            this.webMcpInflightKeys.delete(dedupeKey);
+            return null;
+          }
+        }
+        if (controller.signal.aborted) {
+          this.webMcpInflightKeys.delete(dedupeKey);
+          return null;
+        }
+        return { dedupeKey, resumeKey, output };
+      }),
+    );
+
+    try {
+      const ready = executed.filter(
+        (r): r is { dedupeKey: string; resumeKey: string; output: unknown } =>
+          r !== null,
+      );
+      // Everything deduped/aborted/failed — nothing to post.
+      if (ready.length === 0) return;
+
+      const toolOutputs: Record<string, unknown> = {};
+      for (const r of ready) {
+        // Two omitted-on-collision safety: if two calls somehow resolve to the
+        // same key (only possible on a legacy name fallback), last write wins —
+        // the server re-pauses the unrepresented call for retry.
+        toolOutputs[r.resumeKey] = r.output;
+      }
+
+      const response = await this.client.resumeFlow(executionId, toolOutputs, {
+        signal: resumeController.signal,
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => null);
+        throw new Error(errorData?.error ?? `Resume failed: ${response.status}`);
+      }
+      // Server accepted the batch — mark every included call resolved so stale
+      // re-emits don't re-execute the page tool.
+      for (const r of ready) {
+        this.webMcpResolvedKeys.add(r.dedupeKey);
+      }
+      if (response.body) {
+        await this.connectStream(response.body, { allowReentry: true });
+      }
+    } 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)),
+        );
+      }
+    } finally {
+      for (const key of claimedKeys) {
+        this.webMcpInflightKeys.delete(key);
+      }
+      for (const controller of controllers) {
+        this.webMcpResolveControllers.delete(controller);
+      }
+      this.webMcpResolveControllers.delete(resumeController);
+      if (this.webMcpResolveControllers.size === 0 && !this.abortController) {
+        this.setStreaming(false);
+      }
+    }
+  }
+
+  /**
+   * Resolve a paused `webmcp:*` LOCAL tool call by executing it against the
+   * host page's tool registry and posting the result to `/resume`.
+   *
+   * Triggered automatically from `handleEvent` when a `step_await`-derived
+   * message arrives with a `webmcp:` prefix — the user does not click a
+   * pill; the bridge's confirm-bubble gate is the only interactive surface.
+   *
+   * Idempotent on the message's `toolCall.id`: re-emits of the same step_await
+   * (e.g. from message coalescing) won't double-fire `tool.execute`. Failure
+   * modes — declined, timed out, throw, unknown tool — all resolve into a
+   * `{ isError: true, content: [...] }` payload that resumes the dispatch
+   * cleanly so the agent can recover.
+   */
+  public async resolveWebMcpToolCall(
+    toolMessage: AgentWidgetMessage,
+  ): Promise<void> {
+    const executionId = toolMessage.agentMetadata?.executionId;
+    const wireToolName = toolMessage.toolCall?.name;
+    const toolCallId = toolMessage.toolCall?.id;
+
+    // Malformed step_await wire shapes shouldn't silently strand the
+    // server-side dispatch. Three failure modes:
+    //   - no executionId: no /resume target exists; surface to the host
+    //     via onError so an operator can react. This is a server-side
+    //     wire-shape bug — Persona can't recover it from the client.
+    //   - no wireToolName: defensive guard — handleEvent only calls us
+    //     when tc.name is a `webmcp:` prefix, so this path indicates a
+    //     direct caller misuse. Silent return.
+    //   - no toolCallId: dedupe key falls apart, but the server can still
+    //     advance if we post an isError for the wireToolName. Do that
+    //     and bail before the dedupe path.
+    if (!executionId) {
+      this.callbacks.onError?.(
+        new Error(
+          "WebMCP step_await missing executionId — dispatch left paused.",
+        ),
+      );
+      return;
+    }
+    if (!wireToolName) return;
+    if (!toolCallId) {
+      // No toolCall.id → no per-call dedupe key. Fall back to a synthetic
+      // `(executionId):(wireToolName)` so identical malformed re-emits don't
+      // re-POST /resume. Idempotent on duplicate bad payloads.
+      const malformedKey = `${executionId}:__no_tool_id__:${wireToolName}`;
+      if (
+        this.webMcpInflightKeys.has(malformedKey) ||
+        this.webMcpResolvedKeys.has(malformedKey)
+      ) {
+        return;
+      }
+      this.webMcpInflightKeys.add(malformedKey);
+      try {
+        await this.resumeWithToolOutput(executionId, wireToolName, {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: "WebMCP step_await missing toolCall.id — cannot execute the page tool.",
+            },
+          ],
+        });
+        this.webMcpResolvedKeys.add(malformedKey);
+      } catch (error) {
+        this.callbacks.onError?.(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      } finally {
+        this.webMcpInflightKeys.delete(malformedKey);
+      }
+      return;
+    }
+
+    // Dedupe key scoped by executionId — see `webMcpInflightKeys` doc comment
+    // for the failure-recovery + cross-dispatch rationale.
+    const dedupeKey = `${executionId}:${toolCallId}`;
+    if (
+      this.webMcpInflightKeys.has(dedupeKey) ||
+      this.webMcpResolvedKeys.has(dedupeKey)
+    ) {
+      return;
+    }
+    this.webMcpInflightKeys.add(dedupeKey);
+
+    // Mark resolved on the message so the UI's local-tool sheet (if any
+    // generic one ever lands) does not show — this is a fully-automatic
+    // tool from the user's perspective, modulo the confirm bubble.
+    this.upsertMessage({
+      ...toolMessage,
+      agentMetadata: {
+        ...toolMessage.agentMetadata,
+        awaitingLocalTool: false,
+      },
+    });
+
+    // Per-resolve AbortController, NOT the shared `this.abortController`.
+    // A single turn can produce multiple `webmcp:*` step_await messages —
+    // both PARALLEL (two awaits in one stream) and, more commonly, CHAINED
+    // (tool A → /resume → tool B, where B's step_await arrives inside A's
+    // resume SSE stream). The old code pre-aborted `this.abortController`
+    // here to mirror the sibling resolve paths; in the chained case that
+    // aborted the stream still delivering B, so B never executed and its
+    // /resume was never POSTed — the dispatch hung forever. Using a dedicated
+    // per-resolve controller leaves the in-flight resume stream untouched.
+    // cancel()/clearMessages()/hydrateMessages()/sendMessage() iterate
+    // `webMcpResolveControllers` to tear these down on a real stop / new turn.
+    const resolveController = new AbortController();
+    this.webMcpResolveControllers.add(resolveController);
+    const { signal } = resolveController;
+    this.setStreaming(true);
+
+    const args = toolMessage.toolCall?.args;
+    // Thread the signal INTO the bridge — short-circuits the confirm bubble
+    // and the execute() race on cancel(), so a late confirm-approval after
+    // cancel() cannot fire a host-page side effect with no matching /resume.
+    const execPromise = this.client.executeWebMcpToolCall(
+      wireToolName,
+      args,
+      signal,
+    );
+
+    try {
+      let resumeOutput: unknown;
+      if (!execPromise) {
+        // Client has no bridge (config.webmcp.enabled !== true). Resume with
+        // an error so the dispatch can advance instead of hanging.
+        resumeOutput = {
+          isError: true,
+          content: [
+            { type: "text", text: "WebMCP not enabled on this widget." },
+          ],
+        };
+      } else {
+        resumeOutput = await execPromise;
+      }
+      // If cancel() fired during execute, the bridge returned an aborted
+      // result — don't post it. The server's SSE has been torn down; a
+      // /resume now would just produce an orphan dispatch on the server.
+      // Streaming/teardown is handled by the shared `finally` below (gated on
+      // the resolve set) so we don't clobber a sibling resolve or a live
+      // dispatch's controller here.
+      if (signal.aborted) {
+        return;
+      }
+      // Mark resolved as soon as the HTTP /resume returns OK — not after the
+      // SSE stream finishes. `connectStream` swallows downstream SSE errors
+      // (they surface via onError, not by rethrowing), so awaiting it doesn't
+      // tell us whether the server actually processed the resume. Marking
+      // here pairs with the dedupe semantics: a successful POST means the
+      // server got the answer; later step_await re-emits for the same
+      // toolCall.id are stale and must not re-execute the page tool.
+      // Key the resume by the per-call id (core#3878) when present; the server
+      // prefers it over tool name. Falls back to the wire tool name for legacy
+      // servers — the original name-keyed contract, still correct for a single
+      // call (only same-tool PARALLEL calls could collide on the name).
+      const resumeKey =
+        toolMessage.agentMetadata?.webMcpToolCallId ?? wireToolName;
+      await this.resumeWithToolOutput(executionId, resumeKey, resumeOutput, {
+        onHttpOk: () => {
+          this.webMcpResolvedKeys.add(dedupeKey);
+        },
+        signal,
+      });
+    } catch (error) {
+      const isAbortError =
+        error instanceof Error &&
+        (error.name === "AbortError" ||
+          error.message.includes("aborted") ||
+          error.message.includes("abort"));
+      // Streaming/teardown handled by the shared `finally` (gated on the
+      // resolve set) — do NOT null the shared `this.abortController` here; it
+      // may belong to a live dispatch or sibling resolve, not to us.
+      if (!isAbortError) {
+        // The bridge normalizes tool errors into result objects, so reaching
+        // here means a network failure during `/resume` itself, OR a stream
+        // hookup error. Surface to onError, but DO NOT mark resolved — a
+        // later step_await re-emit should be allowed to retry the resume.
+        this.callbacks.onError?.(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    } finally {
+      this.webMcpInflightKeys.delete(dedupeKey);
+      this.webMcpResolveControllers.delete(resolveController);
+      // Only flip streaming off when this was the last in-flight resolve AND
+      // no shared dispatch is live. Otherwise a finishing resolve would hide
+      // the typing indicator while a sibling (parallel) or successor (chained)
+      // resolve — or a live dispatch — is still running.
+      if (this.webMcpResolveControllers.size === 0 && !this.abortController) {
+        this.setStreaming(false);
+      }
+    }
+  }
+
+  /**
+   * POST `/resume` with a SINGLE tool's output and pipe the resulting SSE
+   * stream back through `connectStream`. Shared by every single-call local-tool
+   * resolve path (ask_user_question and single WebMCP calls). Parallel WebMCP
+   * calls use `resolveWebMcpToolCallBatch`, which posts one resume for many.
+   *
+   * `resumeKey` is the `toolOutputs` map key: the per-call `webMcpToolCallId`
+   * for WebMCP (core#3878), or the tool name for ask_user_question / legacy
+   * servers. `onHttpOk` runs synchronously between the HTTP-status check and the
+   * stream pipe; it lets the WebMCP resolve path commit the dedupe flag at
+   * "server accepted the answer" rather than "stream finished cleanly".
+   */
+  private async resumeWithToolOutput(
+    executionId: string,
+    resumeKey: string,
+    output: unknown,
+    options?: { onHttpOk?: () => void; signal?: AbortSignal },
+  ): Promise<void> {
+    const response = await this.client.resumeFlow(
+      executionId,
+      { [resumeKey]: output },
+      { signal: options?.signal },
+    );
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => null);
+      throw new Error(errorData?.error ?? `Resume failed: ${response.status}`);
+    }
+    options?.onHttpOk?.();
+    if (response.body) {
+      await this.connectStream(response.body, { allowReentry: true });
+    } else if (this.webMcpResolveControllers.size === 0) {
+      // No stream to pipe. Clear streaming only when no WebMCP resolve is in
+      // flight — for a WebMCP caller the current resolve's controller is still
+      // in the set, so its own `finally` (gated on the set draining) owns the
+      // teardown. Non-WebMCP callers (ask_user_question) keep the old behavior.
+      this.setStreaming(false);
+      this.abortController = null;
+    }
+  }
+
+  /**
+   * Tear down every in-flight WebMCP resolve and advance the epoch. Each
+   * resolve owns a dedicated AbortController (chained/parallel resolves don't
+   * share one), so we abort them individually; the aborts propagate into the
+   * bridge's execute race and into each `/resume` fetch signal. Bumping
+   * `webMcpEpoch` strands any resolve still deferred in a queued microtask —
+   * it captured the prior epoch and bails before installing a fresh
+   * controller, so it can't escape this teardown. Called from every stop /
+   * new-turn boundary (cancel, clearMessages, hydrateMessages, sendMessage).
+   */
+  private abortWebMcpResolves(): void {
+    for (const controller of this.webMcpResolveControllers) {
+      controller.abort();
+    }
+    this.webMcpResolveControllers.clear();
+    // Settle every approval bubble still awaiting a click. The bridge parks a
+    // resolve on `await requestConfirm(...)` (→ requestWebMcpApproval) and only
+    // re-checks `signal.aborted` AFTER that await returns — aborting the
+    // controller above does NOT unblock it. Left unsettled, the bridge's
+    // execute(), its `/resume`, and the resolve's `finally` would all hang
+    // forever (and the resolver map would leak across teardowns). Route through
+    // `resolveWebMcpApproval(…, "denied")` so each parked Promise resolves
+    // `false` AND its bubble message flips out of `pending` (no stale "Approve/
+    // Deny" left clickable). The bridge then returns cleanly and its
+    // post-confirm `signal.aborted` guard bails before any host-page side effect
+    // or stale `/resume`. Snapshot the keys first — resolveWebMcpApproval
+    // mutates the map as it deletes each resolver.
+    for (const approvalMessageId of [...this.webMcpApprovalResolvers.keys()]) {
+      this.resolveWebMcpApproval(approvalMessageId, "denied");
+    }
+    // Drop any awaits buffered for a not-yet-flushed batch — their messages are
+    // being torn down, and a microtask-deferred flush must not survive. The
+    // epoch bump below also strands an already-scheduled flush.
+    this.webMcpAwaitBatches.clear();
+    this.webMcpEpoch++;
+  }
+
   public cancel() {
     this.abortController?.abort();
     this.abortController = null;
+    // 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.
+    this.abortWebMcpResolves();
+    this.webMcpInflightKeys.clear();
     // Stop any in-progress audio too — when the user hits "stop", they want
     // the assistant to actually stop talking, not just stop generating tokens.
     // Both helpers are safe no-ops when audio isn't configured.
@@ -1296,9 +2048,17 @@ export class AgentWidgetSession {
     this.stopSpeaking();
     this.abortController?.abort();
     this.abortController = null;
+    // 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();
     this.messages = [];
     this.agentExecution = null;
     this.clearArtifactState();
+    // Clearing messages also wipes the WebMCP dedupe state — a fresh
+    // conversation should not refuse to call a webmcp:* tool just because
+    // a tool with the same key resolved in the prior conversation.
+    this.webMcpInflightKeys.clear();
+    this.webMcpResolvedKeys.clear();
     this.setStreaming(false);
     this.setStatus("idle");
     this.callbacks.onMessagesChanged([...this.messages]);
@@ -1423,6 +2183,13 @@ export class AgentWidgetSession {
   public hydrateMessages(messages: AgentWidgetMessage[]) {
     this.abortController?.abort();
     this.abortController = null;
+    // Hydration replaces the conversation — abort and forget every in-flight
+    // WebMCP resolve; their messages are about to be replaced.
+    this.abortWebMcpResolves();
+    // Wipe the WebMCP dedupe state alongside the message restore — the
+    // incoming snapshot is treated as a fresh conversation context.
+    this.webMcpInflightKeys.clear();
+    this.webMcpResolvedKeys.clear();
     this.messages = this.sortMessages(
       messages.map((message) => ({
         ...message,
@@ -1451,6 +2218,36 @@ export class AgentWidgetSession {
     if (event.type === "message") {
       this.upsertMessage(event.message);
 
+      // WebMCP auto-resolve: when a step_await emits a tool-variant message
+      // for a `webmcp:*` tool, drive the bridge to execute it and post the
+      // result to /resume. Unlike ask_user_question, no user pill click is
+      // required — the bridge's confirm bubble is the only interactive surface.
+      //
+      // Defer via `queueMicrotask` so handleEvent returns FIRST. The current
+      // SSE consumer is still mid-loop; once we return, the dispatch's
+      // `connectStream` sees end-of-stream (server closes the SSE at
+      // step_await), flips status to "idle", and clears `abortController`
+      // before our resolve grabs them. Without this, the original dispatch's
+      // finalizer would clobber the new abort controller and `streaming=true`
+      // set inside `resolveWebMcpToolCall`.
+      //
+      // ALWAYS resolve when the wire name carries the `webmcp:` prefix, even
+      // if the bridge is non-operational. Otherwise the dispatch stays paused
+      // indefinitely — `resolveWebMcpToolCall` translates the missing-bridge
+      // case into an isError result that resumes the flow cleanly.
+      const tc = event.message.toolCall;
+      if (
+        event.message.agentMetadata?.awaitingLocalTool === true &&
+        tc?.name &&
+        isWebMcpToolName(tc.name)
+      ) {
+        // Collect the await into its executionId's batch instead of resolving
+        // it on the spot. Parallel same-tool calls (core#3878) arrive as
+        // separate `step_await`s in the same stream; batching lets us post ONE
+        // `/resume` keyed by per-call id (see `enqueueWebMcpAwait`).
+        this.enqueueWebMcpAwait(event.message);
+      }
+
       // Track agent execution state from message metadata
       if (event.message.agentMetadata?.executionId) {
         if (!this.agentExecution) {
@@ -1471,17 +2268,49 @@ export class AgentWidgetSession {
       if (event.status === "connecting") {
         this.setStreaming(true);
       } else if (event.status === "idle" || event.status === "error") {
-        this.setStreaming(false);
-        this.abortController = null;
-        // Mark agent execution as complete when streaming ends
+        // 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
+        // own `finally` flips streaming off once the resolve set drains.
+        if (this.webMcpResolveControllers.size === 0) {
+          this.setStreaming(false);
+          this.abortController = null;
+        }
+        // Mark agent execution as complete when streaming ends — UNLESS local
+        // tools are still outstanding. A batched WebMCP resume is deferred to
+        // the microtask below (so `webMcpResolveControllers` is still empty
+        // here) and a chained resolve may be mid-flight; marking the run
+        // 'complete' now would make isAgentRunning() report a finished run while
+        // page tools are still executing. Stay 'running' — the resume stream's
+        // own idle (with batches drained and resolves settled) marks it done.
+        const webMcpPending =
+          this.webMcpAwaitBatches.size > 0 ||
+          this.webMcpResolveControllers.size > 0;
         if (this.agentExecution?.status === 'running') {
-          this.agentExecution.status = event.status === "error" ? 'error' : 'complete';
+          if (event.status === "error") {
+            this.agentExecution.status = 'error';
+          } else if (!webMcpPending) {
+            this.agentExecution.status = 'complete';
+          }
         }
+        // The stream that delivered any local-tool `step_await`s has now ended,
+        // so every parallel await it carried is collected. Flush them as ONE
+        // batched `/resume` per executionId (deferred — see
+        // scheduleWebMcpBatchFlush). Runs AFTER the teardown above so a resolve
+        // doesn't fight the end-of-stream streaming/abortController reset.
+        this.scheduleWebMcpBatchFlush();
       }
     } else if (event.type === "error") {
       this.setStatus("error");
-      this.setStreaming(false);
-      this.abortController = null;
+      // 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
+      // (or null a controller) for a sibling/successor resolve still in flight.
+      // The resolve's own `finally` flips streaming off once the set drains.
+      if (this.webMcpResolveControllers.size === 0) {
+        this.setStreaming(false);
+        this.abortController = null;
+      }
       if (this.agentExecution?.status === 'running') {
         this.agentExecution.status = 'error';
       }
@@ -1668,6 +2497,33 @@ export class AgentWidgetSession {
           awaitingLocalTool: false,
         };
       }
+      // WebMCP equivalent: once a `webmcp:*` tool has started resolving
+      // (inflight) or resolved, a duplicate `step_await` re-emit must not
+      // flip `awaitingLocalTool` back to true and resurrect the "waiting on
+      // local tool" UI. resolveWebMcpToolCall's dedupe path returns without
+      // re-touching the message, so correct the merge here (also avoids a
+      // one-frame flash before that microtask runs).
+      const reTcName = withSequence.toolCall?.name;
+      const reExecId = withSequence.agentMetadata?.executionId;
+      const reTcId = withSequence.toolCall?.id;
+      if (
+        reTcName &&
+        isWebMcpToolName(reTcName) &&
+        reExecId &&
+        reTcId &&
+        withSequence.agentMetadata?.awaitingLocalTool === true
+      ) {
+        const reKey = `${reExecId}:${reTcId}`;
+        if (
+          this.webMcpInflightKeys.has(reKey) ||
+          this.webMcpResolvedKeys.has(reKey)
+        ) {
+          merged.agentMetadata = {
+            ...(merged.agentMetadata ?? {}),
+            awaitingLocalTool: false,
+          };
+        }
+      }
       return merged;
     });
     this.messages = this.sortMessages(this.messages);