@runtypelabs/persona 3.21.3 → 3.22.0

package/dist/index.d.cts

@@ -800,6 +800,13 @@ type AgentWidgetRequestPayload = {
     metadata?: Record<string, unknown>;
     /** Per-turn template variables for /v1/client/chat (merged as root-level {{var}} in Runtype). */
     inputs?: Record<string, unknown>;
+    /**
+     * Per-turn page-discovered tools (WebMCP). Sent to Runtype's dispatch so the
+     * agent can call them as `webmcp:<name>`. The widget snapshots
+     * `document.modelContext.__getRegisteredTools()` each turn and ships only
+     * the JSON-serializable surface (no `execute`).
+     */
+    clientTools?: ClientToolDefinition[];
 };
 /**
  * Configuration for agent loop behavior.
@@ -884,6 +891,114 @@ type AgentWidgetAgentRequestPayload = {
     options: AgentRequestOptions;
     context?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
+    /**
+     * Per-turn page-discovered tools (WebMCP) — same shape as
+     * `AgentWidgetRequestPayload.clientTools`.
+     */
+    clientTools?: ClientToolDefinition[];
+};
+/**
+ * Wire shape for a single client-discovered tool sent on `dispatch.clientTools[]`.
+ *
+ * Mirrors the SDK's `ClientToolDefinition` in `@runtypelabs/sdk`. Only the
+ * JSON-serializable surface of a WebMCP tool — the `execute` function stays
+ * client-side; the server merges these into the agent's tool catalog under
+ * the `webmcp:` namespace.
+ */
+type ClientToolDefinition = {
+    /** Bare tool name; the server prepends `webmcp:` on the wire. */
+    name: string;
+    description: string;
+    /** JSON Schema (per WebMCP spec) — passed through as-is. */
+    parametersSchema?: object;
+    /** Set to `'webmcp'` for tools discovered via the polyfill. */
+    origin?: 'webmcp' | 'local';
+    /** Origin of the page that registered the tool — for server-side audit. */
+    pageOrigin?: string;
+    /**
+     * WebMCP `Tool.annotations` (spec). Not used for gating server-side; the
+     * widget reads these client-side. Forwarded so traces/dashboards can show
+     * `readOnlyHint` / `untrustedContentHint` on tool-call records.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+};
+/**
+ * Information passed to the confirm-bubble handler before a `webmcp:*` tool
+ * call executes. Every WebMCP tool routes through this single gate.
+ */
+type WebMcpConfirmInfo = {
+    /** Bare tool name (no `webmcp:` prefix). */
+    toolName: string;
+    args: unknown;
+    description?: string;
+    annotations?: {
+        readOnlyHint?: boolean;
+        untrustedContentHint?: boolean;
+    };
+    /**
+     * Why the confirm was requested. Currently always `'gate'` — the default
+     * confirm-by-default gate that fires before every `webmcp:*` call. (The
+     * `@mcp-b/webmcp-polyfill` owns the spec's `requestUserInteraction` callback
+     * internally, so Persona no longer surfaces a nested in-tool confirm.)
+     */
+    reason: 'gate';
+};
+/**
+ * Resolves to `true` if the user approves the tool call; `false` to decline.
+ */
+type WebMcpConfirmHandler = (info: WebMcpConfirmInfo) => Promise<boolean>;
+/**
+ * Persona's normalized tool-result shape sent back to the agent on `/resume`.
+ * Mirrors the MCP `CallToolResult` content shape; arbitrary `execute()` return
+ * values are wrapped as a single text block at the bridge boundary.
+ */
+type WebMcpToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: string;
+        [key: string]: unknown;
+    }>;
+    isError?: boolean;
+    /** Pass-through of the tool's `annotations.untrustedContentHint`. */
+    annotations?: {
+        untrustedContentHint?: boolean;
+    };
+};
+/**
+ * Widget-level WebMCP configuration. Set `enabled: true` to opt in. The
+ * surface's server-side `webmcp` policy is the source of truth for which
+ * tools are accepted — these client-side options are convenience filters.
+ */
+type AgentWidgetWebMcpConfig = {
+    /** Master switch. Default: `false` (widget never installs the polyfill). */
+    enabled?: boolean;
+    /**
+     * Glob-ish name patterns to include client-side. `'*'` matches any chars
+     * except `:`. Patterns are matched against the bare tool name (no `webmcp:`
+     * prefix). If unset, all registered tools are included.
+     */
+    allowlist?: string[];
+    /**
+     * Per-tool gate policy. Called before the confirm gate for every
+     * `webmcp:*` call; return `true` to approve immediately and skip the
+     * confirmation UI entirely. Use this to auto-allow read-only tools (e.g.
+     * a catalog search) while still gating mutating ones. Only consulted on
+     * the default-UI path — a custom `onConfirm` takes full control instead.
+     */
+    autoApprove?: (info: WebMcpConfirmInfo) => boolean;
+    /**
+     * Confirm gate handler. When omitted, Persona renders its native in-panel
+     * approval bubble (the same chrome used for server-driven tool approvals)
+     * and resolves on the user's Approve/Deny click. Supply this to override
+     * with a custom confirmer (e.g. a route-level modal). The legacy
+     * `window.confirm` fallback only applies when no widget UI is attached.
+     */
+    onConfirm?: WebMcpConfirmHandler;
 };
 /**
  * Agent execution state tracking.
@@ -925,6 +1040,16 @@ type AgentMessageMetadata = {
      * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
      */
     awaitingLocalTool?: boolean;
+    /**
+     * The provider per-call id (`toolu_…`) carried on the `step_await` /
+     * `flow_await` events for a LOCAL tool (core#3878). Present only when the
+     * server emits it. Two PARALLEL calls to the same tool in one turn share a
+     * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
+     * so this is the key the widget batches a single `/resume` on — preferred
+     * over tool name, which collides for same-tool parallel calls. Absent →
+     * fall back to the legacy name-keyed resume contract.
+     */
+    webMcpToolCallId?: string;
     /**
      * Set to `true` once the user has picked / typed / dismissed an answer for
      * an `ask_user_question` tool call, so renderers stop re-mounting the
@@ -1537,6 +1662,14 @@ type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
     showToolCalls?: boolean;
     showEventStreamToggle?: boolean;
+    /**
+     * Up/Down arrow navigation through previously sent user messages in the
+     * composer, for quick re-entry or editing (shell / Slack style). History is
+     * only entered when the caret is at the start of the input, so normal
+     * multi-line cursor movement is preserved. Set to `false` to disable.
+     * @default true
+     */
+    composerHistory?: boolean;
     /** Shared transcript + event stream scroll-to-bottom affordance. */
     scrollToBottom?: AgentWidgetScrollToBottomFeature;
     /** Collapsed transcript behavior for tool call rows. */
@@ -2643,6 +2776,8 @@ type ClientChatRequest = {
     /** Per-turn inputs for Runtype prompt templates (e.g. {{page_url}}). */
     inputs?: Record<string, unknown>;
     context?: Record<string, unknown>;
+    /** WebMCP page-discovered tools — same shape as `dispatch.clientTools[]`. */
+    clientTools?: ClientToolDefinition[];
 };
 /**
  * Feedback types supported by the API
@@ -3438,6 +3573,31 @@ type AgentWidgetLoadingIndicatorConfig = {
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
+    /**
+     * Override the assistant-bubble copy shown when a dispatch fails before any
+     * response streams back (connection refused, CORS, 4xx/5xx, malformed
+     * stream). Provide a static string, or a function of the error so you can
+     * tailor the message per failure and decide whether to surface the raw
+     * reason. When omitted, a default message is shown that includes the
+     * underlying error detail.
+     *
+     * Returning an empty string suppresses the fallback bubble entirely (the
+     * `onError` callback still fires).
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   // Static
+     *   errorMessage: "We're having trouble connecting. Please try again."
+     *   // Or dynamic
+     *   errorMessage: (error) =>
+     *     error.message.includes("Failed to fetch")
+     *       ? "You appear to be offline."
+     *       : "Something went wrong. Please try again."
+     * }
+     * ```
+     */
+    errorMessage?: string | ((error: Error) => string);
     /**
      * Agent configuration for agent execution mode.
      * When provided, the widget uses agent loop execution instead of flow dispatch.
@@ -3669,6 +3829,26 @@ type AgentWidgetConfig = {
      * ```
      */
     approval?: AgentWidgetApprovalConfig | false;
+    /**
+     * WebMCP — consume page-registered tools (`document.modelContext.registerTool`).
+     * When `enabled`, the widget installs `@mcp-b/webmcp-polyfill`, snapshots the
+     * registry on every dispatch, ships it as `clientTools[]`, and executes
+     * returned `webmcp:*` tool calls with confirm-by-default gating.
+     *
+     * Server-side policy on the chat surface is the source of truth — these
+     * fields layer on top.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   webmcp: {
+     *     enabled: true,
+     *     allowlist: ['search_*', 'list_*'],
+     *   }
+     * }
+     * ```
+     */
+    webmcp?: AgentWidgetWebMcpConfig;
     postprocessMessage?: (context: {
         text: string;
         message: AgentWidgetMessage;
@@ -4448,11 +4628,36 @@ declare class AgentWidgetClient {
     private onSSEEvent?;
     private clientSession;
     private sessionInitPromise;
+    private readonly webMcpBridge;
     constructor(config?: AgentWidgetConfig);
     /**
      * Set callback for capturing raw SSE events
      */
     setSSEEventCallback(callback: SSEEventCallback): void;
+    /**
+     * WebMCP: wire (or replace) the confirm-bubble handler. Called from
+     * `ui.ts` once the widget panel is built and the approval-bubble
+     * chrome is ready to render.
+     */
+    setWebMcpConfirmHandler(handler: WebMcpConfirmHandler | null): void;
+    /**
+     * WebMCP: `true` when the bridge installed the polyfill and can both
+     * snapshot the page registry and execute returned `webmcp:*` tool calls.
+     * `false` for any guard miss (no `document.modelContext`, polyfill not yet
+     * installed, or `config.webmcp.enabled` not set).
+     */
+    isWebMcpOperational(): boolean;
+    /**
+     * WebMCP: execute a returned `webmcp:<name>` tool call against the page's
+     * registry and return the normalized MCP-shaped result for `/resume`. The
+     * bridge handles confirm-bubble gating, the 30s timeout, error
+     * normalization, and `signal`-driven abort — callers never see throws.
+     *
+     * Returns `null` when WebMCP is not enabled on this client (signal to the
+     * session that it should fall back to the legacy local-tool resume path,
+     * if any).
+     */
+    executeWebMcpToolCall(wireToolName: string, args: unknown, signal?: AbortSignal): Promise<WebMcpToolResult> | null;
     /**
      * Get the current SSE event callback (used to preserve across client recreation)
      */
@@ -4581,16 +4786,26 @@ declare class AgentWidgetClient {
      * (client-executed) tools. Used by the built-in `ask_user_question`
      * answer-pill sheet, but generic enough for any LOCAL tool.
      *
-     * Posts to the upstream `/resume` endpoint (the dispatch URL with
-     * `/dispatch` replaced by `/resume` — works for both direct-to-Runtype
-     * and the persona proxy) and returns the raw Response so the caller can
-     * pipe its SSE body through `connectStream()`.
+     * Routes by mode:
+     *  - **client-token mode**: POST `${apiBase}/v1/client/resume` (the
+     *    session-authenticated sibling of `/v1/client/chat`; runtypelabs/core#3889),
+     *    with the active `sessionId` in the body and no Bearer key — a browser
+     *    client-token page holds no secret. `clientTools` are already persisted
+     *    server-side from the dispatch turn, so only `toolOutputs` is re-sent.
+     *  - **dispatch / proxy mode**: POST `${apiUrl}/resume` — Runtype mounts
+     *    resume as a child of `/v1/dispatch`, so the URL is `${apiUrl}/resume`,
+     *    and proxies follow the same shape (`/api/chat/dispatch/resume`).
+     *
+     * Returns the raw Response so the caller can pipe its SSE body through
+     * `connectStream()`.
      *
      * @param executionId - The paused execution id carried on `step_await`.
-     * @param toolOutputs - Map keyed by tool name → the tool's result value.
+     * @param toolOutputs - Map keyed by per-call `toolCallId` (core#3878),
+     *   falling back to tool name for legacy servers → the tool's result value.
      */
     resumeFlow(executionId: string, toolOutputs: Record<string, unknown>, options?: {
         streamResponse?: boolean;
+        signal?: AbortSignal;
     }): Promise<Response>;
     private buildAgentPayload;
     private buildPayload;
@@ -4627,6 +4842,13 @@ declare class AgentWidgetSession {
     private agentExecution;
     private artifacts;
     private selectedArtifactId;
+    private webMcpInflightKeys;
+    private webMcpResolvedKeys;
+    private webMcpResolveControllers;
+    private webMcpEpoch;
+    private webMcpApprovalResolvers;
+    private webMcpApprovalSeq;
+    private webMcpAwaitBatches;
     private voiceProvider;
     private voiceActive;
     private voiceStatus;
@@ -4867,6 +5089,28 @@ declare class AgentWidgetSession {
         assistantMessageId?: string;
         allowReentry?: boolean;
     }): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    requestWebMcpApproval(info: WebMcpConfirmInfo): Promise<boolean>;
+    /**
+     * 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).
+     */
+    resolveWebMcpApproval(approvalMessageId: string, decision: "approved" | "denied"): void;
     /**
      * Resolve a tool approval request (approve or deny).
      * Updates the approval message status, calls the API (or custom onDecision),
@@ -4904,6 +5148,97 @@ declare class AgentWidgetSession {
      */
     markAskUserQuestionResolved(toolMessage: AgentWidgetMessage, answers?: Record<string, string | string[]>): void;
     resolveAskUserQuestion(toolMessage: AgentWidgetMessage, answer: string | Record<string, string | string[]>): Promise<void>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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 resolveWebMcpToolCallBatch;
+    /**
+     * 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.
+     */
+    resolveWebMcpToolCall(toolMessage: AgentWidgetMessage): Promise<void>;
+    /**
+     * 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 resumeWithToolOutput;
+    /**
+     * 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;
     cancel(): void;
     clearMessages(): void;
     getArtifacts(): PersonaArtifactRecord[];
@@ -5154,6 +5489,139 @@ type WidgetHostLayout = {
 };
 declare const createWidgetHostLayout: (target: HTMLElement, config?: AgentWidgetConfig) => WidgetHostLayout;
 
+/**
+ * WebMCP consumption bridge.
+ *
+ * Owns the per-widget lifecycle of `@mcp-b/webmcp-polyfill`:
+ *   - installs the polyfill (lazily, only when enabled) so `document.modelContext`
+ *     is present;
+ *   - snapshots the host page's tool registry per dispatch turn for
+ *     `dispatch.clientTools[]`;
+ *   - executes `webmcp:*` tool calls returned by the agent, mediating a single
+ *     confirm-bubble gate before invoking the page's `execute()`.
+ *
+ * Spec reference: WebMCP (https://webmachinelearning.github.io/webmcp/).
+ * Wire-level merging, namespace prefixing, and server-side allowlist
+ * enforcement live on the Runtype API; this bridge mirrors those checks
+ * client-side as a usability convenience, not a security boundary.
+ *
+ * About `@mcp-b/webmcp-polyfill`: it polyfills the *strict standard surface*
+ * only (`registerTool` / `getTools` / `executeTool` on `document.modelContext`),
+ * with no MCP-B-only extensions. The spec standardizes the *producer* side;
+ * Persona is an in-page *consumer*, so it reads the registry via the
+ * producer-facing preview API:
+ *   - `getTools()` — async; returns `{ name, description, inputSchema }` where
+ *     `inputSchema` is a JSON *string*. Annotations are not exposed here.
+ *   - `executeTool(toolInfo, inputArgsJson, { signal })` — async; validates args
+ *     against the tool's schema, runs `execute()`, and returns the raw result as
+ *     a JSON *string* (or `null` for `undefined`). Honors `signal` for abort.
+ *
+ * The polyfill auto-installs `document.modelContext` at module-evaluation time,
+ * so it is imported *dynamically* and only when `config.webmcp.enabled === true`
+ * — a static import would install the global for every widget consumer,
+ * including those that never opted into WebMCP.
+ *
+ * Confirm model: every `webmcp:*` call goes through one confirm gate before
+ * `execute()` runs, regardless of `annotations.readOnlyHint`. (The polyfill owns
+ * the spec's `client.requestUserInteraction` callback internally; Persona cannot
+ * inject a nested confirm there, so the single outer gate is the whole story.)
+ */
+
+/** Server-applied wire prefix; strip when looking up registry entries. */
+declare const WEBMCP_TOOL_PREFIX = "webmcp:";
+declare class WebMcpBridge {
+    private readonly config;
+    private confirmHandler;
+    private readonly timeoutMs;
+    /** `true` once the polyfill has been (idempotently) installed. */
+    private installed;
+    /** Memoizes the one-shot async install so concurrent callers share it. */
+    private readyPromise;
+    /**
+     * Warn-once latch for a present-but-incompatible `document.modelContext`
+     * (some other / older WebMCP polyfill squatting the global). `getModelContext`
+     * is hit on every snapshot + execute, so we log the diagnostic only once.
+     */
+    private incompatibleContextWarned;
+    constructor(config: AgentWidgetWebMcpConfig);
+    /**
+     * Override the confirm handler post-construction. Used by `ui.ts` to wire
+     * the in-panel approval bubble after the client has been built (the widget
+     * lifecycle constructs the client before the panel renders).
+     */
+    setConfirmHandler(handler: WebMcpConfirmHandler | null): void;
+    /**
+     * `true` when the bridge can both snapshot the registry AND execute returned
+     * tool calls — i.e. the polyfill is installed and `document.modelContext`
+     * exposes the consumer surface (`getTools` / `executeTool`). Native browsers
+     * that ship `document.modelContext` satisfy this too.
+     *
+     * Synchronous and best-effort: returns `false` until the lazy install has
+     * resolved (see `ensureReady`). The snapshot/execute paths await readiness
+     * themselves, so this is purely an advisory check for callers.
+     */
+    isOperational(): boolean;
+    /**
+     * Per-turn snapshot for `dispatch.clientTools[]`. Returns the JSON-only
+     * surface — `execute` stays client-side, reached later via `executeToolCall`.
+     *
+     * Async because the strict polyfill's `getTools()` is async. Both payload
+     * builders in `client.ts` already `await`, so this adds no new ceremony.
+     */
+    snapshotForDispatch(): Promise<ClientToolDefinition[]>;
+    /**
+     * Execute a `webmcp:<name>` tool call returned by the agent and return the
+     * normalized MCP-shaped result for `/resume`.
+     *
+     * Failure modes — all return `{ isError: true, content: [...] }` rather than
+     * throwing, so the dispatch can resume cleanly:
+     *   - bridge not operational
+     *   - tool not in registry (e.g. unmounted between snapshot and call)
+     *   - tool excluded by the client allowlist
+     *   - user declined the confirm gate
+     *   - `execute()` threw or failed schema validation
+     *   - `execute()` exceeded the 30s timeout
+     *   - `signal` fired (session-level `cancel()`)
+     *
+     * When `signal` is provided, abort is honored at three points: before the
+     * confirm bubble renders, after the user approves but before `execute()`
+     * runs, and (via a combined `AbortController`) during `execute()` itself.
+     * Honoring abort BEFORE the confirm prevents a late approval after `cancel()`
+     * from firing a host-page side effect with no matching `/resume`.
+     */
+    executeToolCall(wireToolName: string, args: unknown, signal?: AbortSignal): Promise<WebMcpToolResult>;
+    /**
+     * Lazily install `@mcp-b/webmcp-polyfill` the first time the bridge needs the
+     * registry. Idempotent and memoized. Dynamic import keeps the polyfill out of
+     * the main bundle and prevents it from installing `document.modelContext` for
+     * widget consumers that never enable WebMCP.
+     *
+     * Producer pages should still install the polyfill themselves (or import it)
+     * before registering tools — Persona's install is a fallback, and a page that
+     * registers tools at load before Persona's first dispatch needs the global to
+     * already exist.
+     */
+    private ensureReady;
+    private install;
+    /**
+     * Read the consumer surface off `document.modelContext`, returning `null`
+     * when it is absent or doesn't expose the producer-preview API we rely on.
+     */
+    private getModelContext;
+    private requestConfirm;
+    private passesClientAllowlist;
+}
+/**
+ * Strip the server-applied `webmcp:` prefix from a wire-format tool name.
+ * Exported for tests; widget code should always go through the bridge.
+ */
+declare const stripWebMcpPrefix: (name: string) => string;
+/**
+ * `true` when `wireToolName` carries the `webmcp:` prefix. Used by `client.ts`
+ * to route `step_await` events.
+ */
+declare const isWebMcpToolName: (name: string) => boolean;
+
 declare const createLocalStorageAdapter: (key?: string) => AgentWidgetStorageAdapter;
 
 type ActionManagerProcessContext = {
@@ -6779,4 +7247,4 @@ declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
 declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
 declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
 
-export { ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, type AskUserQuestionOption, type AskUserQuestionPayload, type AskUserQuestionPrompt, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComboButtonHandle, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateComboButtonOptions, type CreateDropdownOptions, type CreateIconButtonOptions, type CreateLabelButtonOptions, type CreateStandardBubbleOptions, type CreateThemeOptions, type CreateToggleGroupOptions, DEFAULT_COMPONENTS, DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH, DEFAULT_FLOATING_LAUNCHER_WIDTH, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DemoCarouselHandle, type DemoCarouselItem, type DemoCarouselOptions, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IconName, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectComponentDirectiveOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LabelButtonTokens, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type StreamAnimationContext, type StreamAnimationPlugin, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createAskUserQuestionBubble, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDemoCarousel, createDirectivePostprocessor, createDropdownMenu, createFlexibleJsonStreamParser, createIconButton, createImagePart, createJsonStreamParser, createLabelButton, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createToggleGroup, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, ensureAskUserQuestionSheet, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isAskUserQuestionMessage, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, renderLucideIcon, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };
+export { ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetActionContext, type AgentWidgetActionEventPayload, type AgentWidgetActionHandler, type AgentWidgetActionHandlerResult, type AgentWidgetActionParser, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetContextProvider, type AgentWidgetContextProviderContext, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetParsedAction, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type AgentWidgetWebMcpConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, type AskUserQuestionOption, type AskUserQuestionPayload, type AskUserQuestionPrompt, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type ClientToolDefinition, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComboButtonHandle, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateComboButtonOptions, type CreateDropdownOptions, type CreateIconButtonOptions, type CreateLabelButtonOptions, type CreateStandardBubbleOptions, type CreateThemeOptions, type CreateToggleGroupOptions, DEFAULT_COMPONENTS, DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH, DEFAULT_FLOATING_LAUNCHER_WIDTH, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DemoCarouselHandle, type DemoCarouselItem, type DemoCarouselOptions, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IconName, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectComponentDirectiveOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LabelButtonTokens, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type StreamAnimationContext, type StreamAnimationPlugin, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, WEBMCP_TOOL_PREFIX, WebMcpBridge, type WebMcpConfirmHandler, type WebMcpConfirmInfo, type WebMcpToolResult, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createAskUserQuestionBubble, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDemoCarousel, createDirectivePostprocessor, createDropdownMenu, createFlexibleJsonStreamParser, createIconButton, createImagePart, createJsonStreamParser, createLabelButton, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createToggleGroup, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, ensureAskUserQuestionSheet, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isAskUserQuestionMessage, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, isWebMcpToolName, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, renderLucideIcon, resolveDockConfig, resolveSanitizer, resolveTokens, stripWebMcpPrefix, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };