@runtypelabs/persona 3.31.1 → 3.34.0

package/dist/smart-dom-reader.d.cts

@@ -1681,12 +1681,44 @@ type AgentToolsConfig = {
     mcpServers?: Array<Record<string, unknown>>;
     /** Maximum number of tool invocations per execution */
     maxToolCalls?: number;
+    /** How the model is steered toward tools: let it decide, force a call, or disable */
+    toolCallStrategy?: "auto" | "required" | "none";
+    /** Per-tool invocation limits / requirements keyed by tool name */
+    perToolLimits?: Record<string, {
+        maxCalls?: number;
+        required?: boolean;
+    }>;
     /** Tool approval configuration for human-in-the-loop workflows */
     approval?: {
         /** Tool names/patterns to require approval for, or true for all tools */
         require: string[] | boolean;
         /** Approval timeout in milliseconds (default: 300000 / 5 minutes) */
         timeout?: number;
+        /** Ask the agent to state its intent alongside approval requests (default: true) */
+        requestReason?: boolean;
+    };
+    /**
+     * Enables the synthesized `spawn_subagent` tool: the model can spin up
+     * ad-hoc child agents at runtime, restricted to `toolPool` (tool IDs /
+     * runtime-tool names already granted to the parent agent).
+     */
+    subagentConfig?: {
+        toolPool: string[];
+        defaultMaxTurns?: number;
+        maxTurnsLimit?: number;
+        maxSpawnsPerRun?: number;
+        defaultModel?: string;
+        allowNesting?: boolean;
+        defaultTimeoutMs?: number;
+    };
+    /**
+     * Enables the synthesized `code_mode` tool: the model writes JS that calls
+     * pool tools inside a sandbox instead of issuing individual tool calls.
+     */
+    codeModeConfig?: {
+        toolPool: string[];
+        description?: string;
+        timeoutMs?: number;
     };
 };
 /** Artifact kinds for the Persona sidebar and dispatch payload */
@@ -1742,8 +1774,13 @@ type ClientToolDefinition = {
     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';
+    /**
+     * `'webmcp'` for tools discovered via the polyfill (server prepends the
+     * `webmcp:` wire prefix); `'sdk'` for widget/SDK-provided tools (name stays
+     * bare on the wire). Matches the server's accepted enum — any other value
+     * fails dispatch validation.
+     */
+    origin?: 'webmcp' | 'sdk';
     /** Origin of the page that registered the tool — for server-side audit. */
     pageOrigin?: string;
     /**
@@ -1872,6 +1909,13 @@ type AgentMessageMetadata = {
      * paginated stepper. Persists alongside `askUserQuestionAnswers`.
      */
     askUserQuestionIndex?: number;
+    /**
+     * Set to `true` once a `suggest_replies` tool call's fire-and-forget
+     * `/resume` has been accepted by the server. Persisted belt-and-suspenders
+     * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
+     * never re-resume the call.
+     */
+    suggestRepliesResolved?: boolean;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -2470,6 +2514,37 @@ type AgentWidgetFeatureFlags = {
      * pills + optional free-text input.
      */
     askUserQuestion?: AgentWidgetAskUserQuestionFeature;
+    /**
+     * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
+     * the tool, the widget shows the suggestions as tappable chips above the
+     * composer (reusing the suggestion-chips surface) and immediately resumes
+     * the execution — fire-and-forget, no user input awaited.
+     */
+    suggestReplies?: AgentWidgetSuggestRepliesFeature;
+};
+/**
+ * Feature config for the built-in `suggest_replies` quick-reply chips.
+ * Chips render in the existing suggestions slot above the composer and are
+ * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
+ * verbatim as the user's next message; chips clear once any user message
+ * follows them.
+ */
+type AgentWidgetSuggestRepliesFeature = {
+    /**
+     * Enable the feature. Defaults to true. When false, `suggest_replies`
+     * renders as a regular tool bubble and is NOT auto-resumed — only set this
+     * with no server-side `suggest_replies` declaration, or the execution
+     * parks awaiting a resume that never comes.
+     */
+    enabled?: boolean;
+    /**
+     * Advertise the built-in `suggest_replies` tool to the agent on every
+     * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+     * needed. Defaults to `false`: flows that already declare the tool via
+     * `runtimeTools` would otherwise present it to the model twice. Ignored
+     * when `enabled` is `false`.
+     */
+    expose?: boolean;
 };
 /**
  * Single selectable option in an `ask_user_question` prompt.
@@ -2530,6 +2605,19 @@ type AgentWidgetAskUserQuestionStyles = {
 type AgentWidgetAskUserQuestionFeature = {
     /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
     enabled?: boolean;
+    /**
+     * Advertise the built-in `ask_user_question` tool to the agent on every
+     * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+     * needed. The tool ships with a model-facing description and JSON schema
+     * matching {@link AskUserQuestionPayload}; when the model calls it, the
+     * existing answer-pill sheet renders and the answer resumes the execution.
+     *
+     * Defaults to `false`: flows that already declare `ask_user_question` via
+     * `runtimeTools` would otherwise present the tool to the model twice.
+     * Ignored when `enabled` is `false` — never offer the agent a question
+     * tool the widget can't render an answer UI for.
+     */
+    expose?: boolean;
     /** Slide-in animation duration in ms. Defaults to 180. */
     slideInMs?: number;
     /** Label for the free-text pill. Defaults to "Other…". */
@@ -2711,6 +2799,26 @@ type AgentWidgetDockConfig = {
      *   it appears to emerge at full width like a floating widget.
      */
     reveal?: "resize" | "overlay" | "push" | "emerge";
+    /**
+     * Maximum height of the dock panel, applied as a viewport-overflow guard.
+     *
+     * The docked shell sizes itself with `height: 100%`, which only resolves when
+     * an ancestor (usually `html, body { height: 100% }`) provides a definite
+     * height. Without one, the dock column would otherwise grow with the
+     * conversation and scroll off the page. This cap clamps the panel to the
+     * viewport (and keeps the `resize`/`emerge` reveals pinned with
+     * `position: sticky`; `push`/`overlay` get the cap only, since their
+     * transform/absolute contexts defeat sticky) so a missing height chain
+     * degrades gracefully instead of breaking the chat.
+     *
+     * - Set a CSS length (e.g. `"600px"`, `"80vh"`) to override the cap.
+     * - Set `false` to disable the guard entirely (the panel then sizes purely
+     *   from the surrounding layout — make sure your page provides a definite
+     *   height all the way down to the dock target's parent).
+     *
+     * @default "100dvh"
+     */
+    maxHeight?: string | false;
 };
 /**
  * Layout configuration for `mountMode: "composer-bar"`. Controls how the

package/dist/smart-dom-reader.d.ts

@@ -1681,12 +1681,44 @@ type AgentToolsConfig = {
     mcpServers?: Array<Record<string, unknown>>;
     /** Maximum number of tool invocations per execution */
     maxToolCalls?: number;
+    /** How the model is steered toward tools: let it decide, force a call, or disable */
+    toolCallStrategy?: "auto" | "required" | "none";
+    /** Per-tool invocation limits / requirements keyed by tool name */
+    perToolLimits?: Record<string, {
+        maxCalls?: number;
+        required?: boolean;
+    }>;
     /** Tool approval configuration for human-in-the-loop workflows */
     approval?: {
         /** Tool names/patterns to require approval for, or true for all tools */
         require: string[] | boolean;
         /** Approval timeout in milliseconds (default: 300000 / 5 minutes) */
         timeout?: number;
+        /** Ask the agent to state its intent alongside approval requests (default: true) */
+        requestReason?: boolean;
+    };
+    /**
+     * Enables the synthesized `spawn_subagent` tool: the model can spin up
+     * ad-hoc child agents at runtime, restricted to `toolPool` (tool IDs /
+     * runtime-tool names already granted to the parent agent).
+     */
+    subagentConfig?: {
+        toolPool: string[];
+        defaultMaxTurns?: number;
+        maxTurnsLimit?: number;
+        maxSpawnsPerRun?: number;
+        defaultModel?: string;
+        allowNesting?: boolean;
+        defaultTimeoutMs?: number;
+    };
+    /**
+     * Enables the synthesized `code_mode` tool: the model writes JS that calls
+     * pool tools inside a sandbox instead of issuing individual tool calls.
+     */
+    codeModeConfig?: {
+        toolPool: string[];
+        description?: string;
+        timeoutMs?: number;
     };
 };
 /** Artifact kinds for the Persona sidebar and dispatch payload */
@@ -1742,8 +1774,13 @@ type ClientToolDefinition = {
     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';
+    /**
+     * `'webmcp'` for tools discovered via the polyfill (server prepends the
+     * `webmcp:` wire prefix); `'sdk'` for widget/SDK-provided tools (name stays
+     * bare on the wire). Matches the server's accepted enum — any other value
+     * fails dispatch validation.
+     */
+    origin?: 'webmcp' | 'sdk';
     /** Origin of the page that registered the tool — for server-side audit. */
     pageOrigin?: string;
     /**
@@ -1872,6 +1909,13 @@ type AgentMessageMetadata = {
      * paginated stepper. Persists alongside `askUserQuestionAnswers`.
      */
     askUserQuestionIndex?: number;
+    /**
+     * Set to `true` once a `suggest_replies` tool call's fire-and-forget
+     * `/resume` has been accepted by the server. Persisted belt-and-suspenders
+     * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
+     * never re-resume the call.
+     */
+    suggestRepliesResolved?: boolean;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -2470,6 +2514,37 @@ type AgentWidgetFeatureFlags = {
      * pills + optional free-text input.
      */
     askUserQuestion?: AgentWidgetAskUserQuestionFeature;
+    /**
+     * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
+     * the tool, the widget shows the suggestions as tappable chips above the
+     * composer (reusing the suggestion-chips surface) and immediately resumes
+     * the execution — fire-and-forget, no user input awaited.
+     */
+    suggestReplies?: AgentWidgetSuggestRepliesFeature;
+};
+/**
+ * Feature config for the built-in `suggest_replies` quick-reply chips.
+ * Chips render in the existing suggestions slot above the composer and are
+ * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
+ * verbatim as the user's next message; chips clear once any user message
+ * follows them.
+ */
+type AgentWidgetSuggestRepliesFeature = {
+    /**
+     * Enable the feature. Defaults to true. When false, `suggest_replies`
+     * renders as a regular tool bubble and is NOT auto-resumed — only set this
+     * with no server-side `suggest_replies` declaration, or the execution
+     * parks awaiting a resume that never comes.
+     */
+    enabled?: boolean;
+    /**
+     * Advertise the built-in `suggest_replies` tool to the agent on every
+     * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+     * needed. Defaults to `false`: flows that already declare the tool via
+     * `runtimeTools` would otherwise present it to the model twice. Ignored
+     * when `enabled` is `false`.
+     */
+    expose?: boolean;
 };
 /**
  * Single selectable option in an `ask_user_question` prompt.
@@ -2530,6 +2605,19 @@ type AgentWidgetAskUserQuestionStyles = {
 type AgentWidgetAskUserQuestionFeature = {
     /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
     enabled?: boolean;
+    /**
+     * Advertise the built-in `ask_user_question` tool to the agent on every
+     * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+     * needed. The tool ships with a model-facing description and JSON schema
+     * matching {@link AskUserQuestionPayload}; when the model calls it, the
+     * existing answer-pill sheet renders and the answer resumes the execution.
+     *
+     * Defaults to `false`: flows that already declare `ask_user_question` via
+     * `runtimeTools` would otherwise present the tool to the model twice.
+     * Ignored when `enabled` is `false` — never offer the agent a question
+     * tool the widget can't render an answer UI for.
+     */
+    expose?: boolean;
     /** Slide-in animation duration in ms. Defaults to 180. */
     slideInMs?: number;
     /** Label for the free-text pill. Defaults to "Other…". */
@@ -2711,6 +2799,26 @@ type AgentWidgetDockConfig = {
      *   it appears to emerge at full width like a floating widget.
      */
     reveal?: "resize" | "overlay" | "push" | "emerge";
+    /**
+     * Maximum height of the dock panel, applied as a viewport-overflow guard.
+     *
+     * The docked shell sizes itself with `height: 100%`, which only resolves when
+     * an ancestor (usually `html, body { height: 100% }`) provides a definite
+     * height. Without one, the dock column would otherwise grow with the
+     * conversation and scroll off the page. This cap clamps the panel to the
+     * viewport (and keeps the `resize`/`emerge` reveals pinned with
+     * `position: sticky`; `push`/`overlay` get the cap only, since their
+     * transform/absolute contexts defeat sticky) so a missing height chain
+     * degrades gracefully instead of breaking the chat.
+     *
+     * - Set a CSS length (e.g. `"600px"`, `"80vh"`) to override the cap.
+     * - Set `false` to disable the guard entirely (the panel then sizes purely
+     *   from the surrounding layout — make sure your page provides a definite
+     *   height all the way down to the dock target's parent).
+     *
+     * @default "100dvh"
+     */
+    maxHeight?: string | false;
 };
 /**
  * Layout configuration for `mountMode: "composer-bar"`. Controls how the