@runtypelabs/persona 4.27.0 → 4.28.1

package/dist/index.d.cts

@@ -2413,6 +2413,9 @@ type RuntypeClientChatRequest = {
     sessionId: string;
     submitMode?: "normal" | "interrupt" | "steer";
     turnId?: string;
+    voice?: {
+        spoken?: boolean;
+    };
 };
 type RuntypeClientChatStreamEvent = RuntypeExecutionStreamEvent;
 type RuntypeClientResumeRequest = {
@@ -3455,9 +3458,8 @@ type WebMcpConfirmInfo = {
     };
     /**
      * 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.)
+     * confirm-by-default gate that fires before every `webmcp:*` call. Tool
+     * callbacks on v6 receive an AbortSignal, not a nested confirmation API.
      */
     reason: 'gate';
 };
@@ -7616,6 +7618,13 @@ type VoiceDelegationRequest = {
         role: string;
         content: unknown;
     }>;
+    /**
+     * Set when the server streams delegated answers (`delegation_stream`): called
+     * with each speakable piece of the turn's answer, in order, while it renders.
+     * The pieces, concatenated, are a prefix of the result's `text`; the result
+     * says how much of it with `streamedChars`.
+     */
+    stream?: (text: string) => void;
 };
 /**
  * How a delegated turn ended, or that it waits on an approval (contract
@@ -7646,6 +7655,12 @@ type VoiceDelegationResult = {
      * @default true
      */
     inChat?: boolean;
+    /**
+     * How many leading characters of `text` already went out through
+     * `request.stream` (the rest, such as an approval script, is unstreamed).
+     * Omitted or 0: nothing was streamed.
+     */
+    streamedChars?: number;
     /**
      * Set when the turn parked on approvals (`text` then asks for the decision).
      * Resolves with the terminal result once the visitor decides (or the
@@ -8558,6 +8573,14 @@ type ClientChatRequest = {
     turnId?: RuntypeClientChatRequest['turnId'];
     /** Whether this turn should interrupt a prior in-flight response (from Core public OpenAPI). */
     submitMode?: RuntypeClientChatRequest['submitMode'];
+    /**
+     * Spoken-reply hint, set on a delegated voice turn whose reply a voice model
+     * reads aloud: the server asks the agent for a speakable answer (the direct
+     * answer first, in plain sentences). Not persisted into history.
+     */
+    voice?: {
+        spoken: true;
+    };
 };
 /**
  * Feedback types supported by the API
@@ -9927,8 +9950,11 @@ type AgentWidgetConfig = {
     /**
      * 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.
+     * current document's registry on every dispatch, ships it as `clientTools[]`,
+     * and executes returned `webmcp:*` calls with confirm-by-default gating.
+     * Supports host-installed v5 JSON-string and v6 object-input contracts.
+     * The automatic fallback stays on v5 to preserve existing browser support
+     * and callback-result behavior.
      *
      * Server-side policy on the chat surface is the source of truth: these
      * fields layer on top.
@@ -11022,6 +11048,12 @@ type DispatchOptions = {
      * `submitMode: "interrupt"` so the server cancels the prior run.
      */
     interrupt?: boolean;
+    /**
+     * Client-token only: a voice model reads the reply aloud (a delegated voice
+     * turn). Sends `voice: { spoken: true }` so the server asks for a speakable
+     * answer.
+     */
+    voiceSpoken?: boolean;
 };
 type SSEHandler = (event: AgentWidgetEvent) => void;
 type SSEEventCallback = (eventType: string, payload: unknown) => void;
@@ -12650,26 +12682,19 @@ declare const createWidgetHostLayout: (target: HTMLElement, config?: AgentWidget
  * 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.)
+ * Supports v5's JSON-string input and v6's object input with a single call:
+ * the runtime passes a JSON object that also string-coerces to JSON text.
+ * Never infer the execution contract from metadata or retry a failed call.
+ * Only tools owned by this document are exposed: the wire addresses tools by
+ * name, not by frame. Callbacks must validate their own input.
+ *
+ * The automatic fallback stays on v5 to preserve its browser requirements and
+ * result semantics. Host pages may install v5 or v6 themselves; Persona does
+ * not replace an existing context. v5's initializeWebMCPPolyfill() and v6's
+ * installWebMCP() are both accepted by custom loaders.
+ *
+ * Every call passes one confirm gate before execution, regardless of
+ * annotations.readOnlyHint. v6 callbacks also receive an invocation signal.
  */
 
 /** Server-applied wire prefix; strip when looking up registry entries. */
@@ -12692,18 +12717,20 @@ interface ModelContextToolInfo {
      * object. `@mcp-b/webmcp-polyfill` made the switch in v5, and Chrome ships it
      * from 154.0.8013 (cross-document tools first) -- but Chrome 149-153, most of
      * the Origin Trial population, and 154's same-document tools still emit the
-     * string. Both are live in the field, so we accept both.
+     * string. Both input execution contracts are supported independently of
+     * schema representation.
      *
      * Absent when the tool registered no schema: v5 omits the member, where v4
      * always emitted a `{"type":"object"}` string.
      */
     inputSchema?: object | string;
+    /** Owning frame and origin, when supplied by the registry. Never sent on the wire. */
+    window?: Window;
+    origin?: string;
     /**
      * Display title declared on the tool (`ToolDescriptor.title` in the WebMCP
      * spec). The polyfill returns `""` when the tool didn't declare one. Note:
-     * `annotations` (incl. the legacy `annotations.title`) are NOT exposed on
-     * this strict consumer surface: top-level `title` is the only display-name
-     * channel available to us.
+     * top-level `title` is the display-name channel, not `annotations.title`.
      */
     title?: string;
     /**
@@ -12720,6 +12747,8 @@ interface ModelContextToolInfo {
 /** The slice of `@mcp-b/webmcp-polyfill` the bridge consumes on install. */
 type WebMcpPolyfillModule = {
     initializeWebMCPPolyfill: () => void;
+} | {
+    installWebMCP: () => void;
 };
 /**
  * Strip the server-applied `webmcp:` prefix from a wire-format tool name.
@@ -14516,7 +14545,7 @@ declare class WebMcpBridge$1 {
      *   - 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()` threw or returned a non-serializable result
      *   - `execute()` exceeded the 30s timeout
      *   - `signal` fired (session-level `cancel()`)
      *

package/dist/index.d.ts

@@ -2413,6 +2413,9 @@ type RuntypeClientChatRequest = {
     sessionId: string;
     submitMode?: "normal" | "interrupt" | "steer";
     turnId?: string;
+    voice?: {
+        spoken?: boolean;
+    };
 };
 type RuntypeClientChatStreamEvent = RuntypeExecutionStreamEvent;
 type RuntypeClientResumeRequest = {
@@ -3455,9 +3458,8 @@ type WebMcpConfirmInfo = {
     };
     /**
      * 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.)
+     * confirm-by-default gate that fires before every `webmcp:*` call. Tool
+     * callbacks on v6 receive an AbortSignal, not a nested confirmation API.
      */
     reason: 'gate';
 };
@@ -7616,6 +7618,13 @@ type VoiceDelegationRequest = {
         role: string;
         content: unknown;
     }>;
+    /**
+     * Set when the server streams delegated answers (`delegation_stream`): called
+     * with each speakable piece of the turn's answer, in order, while it renders.
+     * The pieces, concatenated, are a prefix of the result's `text`; the result
+     * says how much of it with `streamedChars`.
+     */
+    stream?: (text: string) => void;
 };
 /**
  * How a delegated turn ended, or that it waits on an approval (contract
@@ -7646,6 +7655,12 @@ type VoiceDelegationResult = {
      * @default true
      */
     inChat?: boolean;
+    /**
+     * How many leading characters of `text` already went out through
+     * `request.stream` (the rest, such as an approval script, is unstreamed).
+     * Omitted or 0: nothing was streamed.
+     */
+    streamedChars?: number;
     /**
      * Set when the turn parked on approvals (`text` then asks for the decision).
      * Resolves with the terminal result once the visitor decides (or the
@@ -8558,6 +8573,14 @@ type ClientChatRequest = {
     turnId?: RuntypeClientChatRequest['turnId'];
     /** Whether this turn should interrupt a prior in-flight response (from Core public OpenAPI). */
     submitMode?: RuntypeClientChatRequest['submitMode'];
+    /**
+     * Spoken-reply hint, set on a delegated voice turn whose reply a voice model
+     * reads aloud: the server asks the agent for a speakable answer (the direct
+     * answer first, in plain sentences). Not persisted into history.
+     */
+    voice?: {
+        spoken: true;
+    };
 };
 /**
  * Feedback types supported by the API
@@ -9927,8 +9950,11 @@ type AgentWidgetConfig = {
     /**
      * 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.
+     * current document's registry on every dispatch, ships it as `clientTools[]`,
+     * and executes returned `webmcp:*` calls with confirm-by-default gating.
+     * Supports host-installed v5 JSON-string and v6 object-input contracts.
+     * The automatic fallback stays on v5 to preserve existing browser support
+     * and callback-result behavior.
      *
      * Server-side policy on the chat surface is the source of truth: these
      * fields layer on top.
@@ -11022,6 +11048,12 @@ type DispatchOptions = {
      * `submitMode: "interrupt"` so the server cancels the prior run.
      */
     interrupt?: boolean;
+    /**
+     * Client-token only: a voice model reads the reply aloud (a delegated voice
+     * turn). Sends `voice: { spoken: true }` so the server asks for a speakable
+     * answer.
+     */
+    voiceSpoken?: boolean;
 };
 type SSEHandler = (event: AgentWidgetEvent) => void;
 type SSEEventCallback = (eventType: string, payload: unknown) => void;
@@ -12650,26 +12682,19 @@ declare const createWidgetHostLayout: (target: HTMLElement, config?: AgentWidget
  * 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.)
+ * Supports v5's JSON-string input and v6's object input with a single call:
+ * the runtime passes a JSON object that also string-coerces to JSON text.
+ * Never infer the execution contract from metadata or retry a failed call.
+ * Only tools owned by this document are exposed: the wire addresses tools by
+ * name, not by frame. Callbacks must validate their own input.
+ *
+ * The automatic fallback stays on v5 to preserve its browser requirements and
+ * result semantics. Host pages may install v5 or v6 themselves; Persona does
+ * not replace an existing context. v5's initializeWebMCPPolyfill() and v6's
+ * installWebMCP() are both accepted by custom loaders.
+ *
+ * Every call passes one confirm gate before execution, regardless of
+ * annotations.readOnlyHint. v6 callbacks also receive an invocation signal.
  */
 
 /** Server-applied wire prefix; strip when looking up registry entries. */
@@ -12692,18 +12717,20 @@ interface ModelContextToolInfo {
      * object. `@mcp-b/webmcp-polyfill` made the switch in v5, and Chrome ships it
      * from 154.0.8013 (cross-document tools first) -- but Chrome 149-153, most of
      * the Origin Trial population, and 154's same-document tools still emit the
-     * string. Both are live in the field, so we accept both.
+     * string. Both input execution contracts are supported independently of
+     * schema representation.
      *
      * Absent when the tool registered no schema: v5 omits the member, where v4
      * always emitted a `{"type":"object"}` string.
      */
     inputSchema?: object | string;
+    /** Owning frame and origin, when supplied by the registry. Never sent on the wire. */
+    window?: Window;
+    origin?: string;
     /**
      * Display title declared on the tool (`ToolDescriptor.title` in the WebMCP
      * spec). The polyfill returns `""` when the tool didn't declare one. Note:
-     * `annotations` (incl. the legacy `annotations.title`) are NOT exposed on
-     * this strict consumer surface: top-level `title` is the only display-name
-     * channel available to us.
+     * top-level `title` is the display-name channel, not `annotations.title`.
      */
     title?: string;
     /**
@@ -12720,6 +12747,8 @@ interface ModelContextToolInfo {
 /** The slice of `@mcp-b/webmcp-polyfill` the bridge consumes on install. */
 type WebMcpPolyfillModule = {
     initializeWebMCPPolyfill: () => void;
+} | {
+    installWebMCP: () => void;
 };
 /**
  * Strip the server-applied `webmcp:` prefix from a wire-format tool name.
@@ -14516,7 +14545,7 @@ declare class WebMcpBridge$1 {
      *   - 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()` threw or returned a non-serializable result
      *   - `execute()` exceeded the 30s timeout
      *   - `signal` fired (session-level `cancel()`)
      *