@runtypelabs/persona 3.31.1 → 3.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +17 -10
  2. package/dist/animations/glyph-cycle.d.cts +1 -1
  3. package/dist/animations/glyph-cycle.d.ts +1 -1
  4. package/dist/animations/{types-quh7NmYD.d.cts → types-CthJFfNx.d.cts} +7 -0
  5. package/dist/animations/{types-quh7NmYD.d.ts → types-CthJFfNx.d.ts} +7 -0
  6. package/dist/animations/wipe.d.cts +1 -1
  7. package/dist/animations/wipe.d.ts +1 -1
  8. package/dist/codegen.cjs +1 -1
  9. package/dist/codegen.js +1 -1
  10. package/dist/index.cjs +43 -43
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +320 -8
  13. package/dist/index.d.ts +320 -8
  14. package/dist/index.global.js +193 -192
  15. package/dist/index.global.js.map +1 -1
  16. package/dist/index.js +43 -43
  17. package/dist/index.js.map +1 -1
  18. package/dist/launcher.global.js +117 -117
  19. package/dist/launcher.global.js.map +1 -1
  20. package/dist/smart-dom-reader.d.cts +110 -2
  21. package/dist/smart-dom-reader.d.ts +110 -2
  22. package/dist/theme-editor.cjs +30 -30
  23. package/dist/theme-editor.d.cts +124 -5
  24. package/dist/theme-editor.d.ts +124 -5
  25. package/dist/theme-editor.js +30 -30
  26. package/package.json +3 -3
  27. package/src/ask-user-question-tool.test.ts +148 -0
  28. package/src/ask-user-question-tool.ts +138 -0
  29. package/src/client.ts +43 -9
  30. package/src/codegen.test.ts +0 -14
  31. package/src/components/messages.ts +10 -0
  32. package/src/components/suggestions.ts +49 -6
  33. package/src/index-core.ts +15 -0
  34. package/src/runtime/host-layout.test.ts +206 -9
  35. package/src/runtime/host-layout.ts +121 -8
  36. package/src/runtime/init.test.ts +2 -2
  37. package/src/session.ts +188 -32
  38. package/src/session.webmcp.test.ts +48 -0
  39. package/src/suggest-replies-tool.test.ts +445 -0
  40. package/src/suggest-replies-tool.ts +152 -0
  41. package/src/theme-editor/index.ts +2 -0
  42. package/src/theme-editor/webmcp/index.ts +2 -0
  43. package/src/theme-editor/webmcp/types.ts +16 -3
  44. package/src/types.ts +108 -2
  45. package/src/ui.docked.test.ts +2 -2
  46. package/src/ui.suggest-replies.test.ts +237 -0
  47. package/src/ui.ts +57 -13
  48. package/src/utils/dock.test.ts +23 -1
  49. package/src/utils/dock.ts +2 -0
  50. package/src/voice/voice.test.ts +0 -51
  51. package/src/install-config.test.ts +0 -38
@@ -1412,12 +1412,44 @@ type AgentToolsConfig = {
1412
1412
  mcpServers?: Array<Record<string, unknown>>;
1413
1413
  /** Maximum number of tool invocations per execution */
1414
1414
  maxToolCalls?: number;
1415
+ /** How the model is steered toward tools: let it decide, force a call, or disable */
1416
+ toolCallStrategy?: "auto" | "required" | "none";
1417
+ /** Per-tool invocation limits / requirements keyed by tool name */
1418
+ perToolLimits?: Record<string, {
1419
+ maxCalls?: number;
1420
+ required?: boolean;
1421
+ }>;
1415
1422
  /** Tool approval configuration for human-in-the-loop workflows */
1416
1423
  approval?: {
1417
1424
  /** Tool names/patterns to require approval for, or true for all tools */
1418
1425
  require: string[] | boolean;
1419
1426
  /** Approval timeout in milliseconds (default: 300000 / 5 minutes) */
1420
1427
  timeout?: number;
1428
+ /** Ask the agent to state its intent alongside approval requests (default: true) */
1429
+ requestReason?: boolean;
1430
+ };
1431
+ /**
1432
+ * Enables the synthesized `spawn_subagent` tool: the model can spin up
1433
+ * ad-hoc child agents at runtime, restricted to `toolPool` (tool IDs /
1434
+ * runtime-tool names already granted to the parent agent).
1435
+ */
1436
+ subagentConfig?: {
1437
+ toolPool: string[];
1438
+ defaultMaxTurns?: number;
1439
+ maxTurnsLimit?: number;
1440
+ maxSpawnsPerRun?: number;
1441
+ defaultModel?: string;
1442
+ allowNesting?: boolean;
1443
+ defaultTimeoutMs?: number;
1444
+ };
1445
+ /**
1446
+ * Enables the synthesized `code_mode` tool: the model writes JS that calls
1447
+ * pool tools inside a sandbox instead of issuing individual tool calls.
1448
+ */
1449
+ codeModeConfig?: {
1450
+ toolPool: string[];
1451
+ description?: string;
1452
+ timeoutMs?: number;
1421
1453
  };
1422
1454
  };
1423
1455
  /** Artifact kinds for the Persona sidebar and dispatch payload */
@@ -1473,8 +1505,13 @@ type ClientToolDefinition = {
1473
1505
  description: string;
1474
1506
  /** JSON Schema (per WebMCP spec) — passed through as-is. */
1475
1507
  parametersSchema?: object;
1476
- /** Set to `'webmcp'` for tools discovered via the polyfill. */
1477
- origin?: 'webmcp' | 'local';
1508
+ /**
1509
+ * `'webmcp'` for tools discovered via the polyfill (server prepends the
1510
+ * `webmcp:` wire prefix); `'sdk'` for widget/SDK-provided tools (name stays
1511
+ * bare on the wire). Matches the server's accepted enum — any other value
1512
+ * fails dispatch validation.
1513
+ */
1514
+ origin?: 'webmcp' | 'sdk';
1478
1515
  /** Origin of the page that registered the tool — for server-side audit. */
1479
1516
  pageOrigin?: string;
1480
1517
  /**
@@ -1603,6 +1640,13 @@ type AgentMessageMetadata = {
1603
1640
  * paginated stepper. Persists alongside `askUserQuestionAnswers`.
1604
1641
  */
1605
1642
  askUserQuestionIndex?: number;
1643
+ /**
1644
+ * Set to `true` once a `suggest_replies` tool call's fire-and-forget
1645
+ * `/resume` has been accepted by the server. Persisted belt-and-suspenders
1646
+ * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
1647
+ * never re-resume the call.
1648
+ */
1649
+ suggestRepliesResolved?: boolean;
1606
1650
  };
1607
1651
  type AgentWidgetRequestMiddlewareContext = {
1608
1652
  payload: AgentWidgetRequestPayload;
@@ -2248,6 +2292,37 @@ type AgentWidgetFeatureFlags = {
2248
2292
  * pills + optional free-text input.
2249
2293
  */
2250
2294
  askUserQuestion?: AgentWidgetAskUserQuestionFeature;
2295
+ /**
2296
+ * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
2297
+ * the tool, the widget shows the suggestions as tappable chips above the
2298
+ * composer (reusing the suggestion-chips surface) and immediately resumes
2299
+ * the execution — fire-and-forget, no user input awaited.
2300
+ */
2301
+ suggestReplies?: AgentWidgetSuggestRepliesFeature;
2302
+ };
2303
+ /**
2304
+ * Feature config for the built-in `suggest_replies` quick-reply chips.
2305
+ * Chips render in the existing suggestions slot above the composer and are
2306
+ * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
2307
+ * verbatim as the user's next message; chips clear once any user message
2308
+ * follows them.
2309
+ */
2310
+ type AgentWidgetSuggestRepliesFeature = {
2311
+ /**
2312
+ * Enable the feature. Defaults to true. When false, `suggest_replies`
2313
+ * renders as a regular tool bubble and is NOT auto-resumed — only set this
2314
+ * with no server-side `suggest_replies` declaration, or the execution
2315
+ * parks awaiting a resume that never comes.
2316
+ */
2317
+ enabled?: boolean;
2318
+ /**
2319
+ * Advertise the built-in `suggest_replies` tool to the agent on every
2320
+ * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
2321
+ * needed. Defaults to `false`: flows that already declare the tool via
2322
+ * `runtimeTools` would otherwise present it to the model twice. Ignored
2323
+ * when `enabled` is `false`.
2324
+ */
2325
+ expose?: boolean;
2251
2326
  };
2252
2327
  /**
2253
2328
  * Single selectable option in an `ask_user_question` prompt.
@@ -2308,6 +2383,19 @@ type AgentWidgetAskUserQuestionStyles = {
2308
2383
  type AgentWidgetAskUserQuestionFeature = {
2309
2384
  /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
2310
2385
  enabled?: boolean;
2386
+ /**
2387
+ * Advertise the built-in `ask_user_question` tool to the agent on every
2388
+ * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
2389
+ * needed. The tool ships with a model-facing description and JSON schema
2390
+ * matching {@link AskUserQuestionPayload}; when the model calls it, the
2391
+ * existing answer-pill sheet renders and the answer resumes the execution.
2392
+ *
2393
+ * Defaults to `false`: flows that already declare `ask_user_question` via
2394
+ * `runtimeTools` would otherwise present the tool to the model twice.
2395
+ * Ignored when `enabled` is `false` — never offer the agent a question
2396
+ * tool the widget can't render an answer UI for.
2397
+ */
2398
+ expose?: boolean;
2311
2399
  /** Slide-in animation duration in ms. Defaults to 180. */
2312
2400
  slideInMs?: number;
2313
2401
  /** Label for the free-text pill. Defaults to "Other…". */
@@ -2489,6 +2577,26 @@ type AgentWidgetDockConfig = {
2489
2577
  * it appears to emerge at full width like a floating widget.
2490
2578
  */
2491
2579
  reveal?: "resize" | "overlay" | "push" | "emerge";
2580
+ /**
2581
+ * Maximum height of the dock panel, applied as a viewport-overflow guard.
2582
+ *
2583
+ * The docked shell sizes itself with `height: 100%`, which only resolves when
2584
+ * an ancestor (usually `html, body { height: 100% }`) provides a definite
2585
+ * height. Without one, the dock column would otherwise grow with the
2586
+ * conversation and scroll off the page. This cap clamps the panel to the
2587
+ * viewport (and keeps the `resize`/`emerge` reveals pinned with
2588
+ * `position: sticky`; `push`/`overlay` get the cap only, since their
2589
+ * transform/absolute contexts defeat sticky) so a missing height chain
2590
+ * degrades gracefully instead of breaking the chat.
2591
+ *
2592
+ * - Set a CSS length (e.g. `"600px"`, `"80vh"`) to override the cap.
2593
+ * - Set `false` to disable the guard entirely (the panel then sizes purely
2594
+ * from the surrounding layout — make sure your page provides a definite
2595
+ * height all the way down to the dock target's parent).
2596
+ *
2597
+ * @default "100dvh"
2598
+ */
2599
+ maxHeight?: string | false;
2492
2600
  };
2493
2601
  /**
2494
2602
  * Layout configuration for `mountMode: "composer-bar"`. Controls how the
@@ -5768,8 +5876,15 @@ interface ToolTextContent {
5768
5876
  type: 'text';
5769
5877
  text: string;
5770
5878
  }
5879
+ /** MCP image content block: raw base64 (no `data:` prefix) plus its MIME type. */
5880
+ interface ToolImageContent {
5881
+ type: 'image';
5882
+ data: string;
5883
+ mimeType: string;
5884
+ }
5885
+ type ToolContent = ToolTextContent | ToolImageContent;
5771
5886
  interface ToolResult {
5772
- content: ToolTextContent[];
5887
+ content: ToolContent[];
5773
5888
  /** Optional machine-readable mirror of the text content. */
5774
5889
  structuredContent?: unknown;
5775
5890
  isError?: boolean;
@@ -5789,7 +5904,11 @@ interface WebMcpTool {
5789
5904
  annotations?: ToolAnnotations;
5790
5905
  execute: ToolExecute;
5791
5906
  }
5792
- /** Wrap a JSON-serializable payload in the MCP tool-result envelope. */
5907
+ /**
5908
+ * Wrap a JSON-serializable payload in the MCP tool-result envelope. Compact
5909
+ * JSON (no indentation) — the text is consumed by a model, where pretty-print
5910
+ * whitespace is pure token overhead.
5911
+ */
5793
5912
  declare function toolResult(payload: unknown): ToolResult;
5794
5913
  /**
5795
5914
  * Structural subset of `ThemeEditorState` (and the example app's `state`
@@ -5938,4 +6057,4 @@ declare function runContrastChecks(state: ThemeEditorLike, level?: ContrastLevel
5938
6057
  /** Compact contrast warnings for the regions a mutation touched. */
5939
6058
  declare function quickContrastWarnings(state: ThemeEditorLike, pairKeys: string[], variant?: 'light' | 'dark' | 'both', level?: ContrastLevel): ContrastWarning[];
5940
6059
 
5941
- export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolExecute, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };
6060
+ export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolContent, type ToolExecute, type ToolImageContent, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };
@@ -1412,12 +1412,44 @@ type AgentToolsConfig = {
1412
1412
  mcpServers?: Array<Record<string, unknown>>;
1413
1413
  /** Maximum number of tool invocations per execution */
1414
1414
  maxToolCalls?: number;
1415
+ /** How the model is steered toward tools: let it decide, force a call, or disable */
1416
+ toolCallStrategy?: "auto" | "required" | "none";
1417
+ /** Per-tool invocation limits / requirements keyed by tool name */
1418
+ perToolLimits?: Record<string, {
1419
+ maxCalls?: number;
1420
+ required?: boolean;
1421
+ }>;
1415
1422
  /** Tool approval configuration for human-in-the-loop workflows */
1416
1423
  approval?: {
1417
1424
  /** Tool names/patterns to require approval for, or true for all tools */
1418
1425
  require: string[] | boolean;
1419
1426
  /** Approval timeout in milliseconds (default: 300000 / 5 minutes) */
1420
1427
  timeout?: number;
1428
+ /** Ask the agent to state its intent alongside approval requests (default: true) */
1429
+ requestReason?: boolean;
1430
+ };
1431
+ /**
1432
+ * Enables the synthesized `spawn_subagent` tool: the model can spin up
1433
+ * ad-hoc child agents at runtime, restricted to `toolPool` (tool IDs /
1434
+ * runtime-tool names already granted to the parent agent).
1435
+ */
1436
+ subagentConfig?: {
1437
+ toolPool: string[];
1438
+ defaultMaxTurns?: number;
1439
+ maxTurnsLimit?: number;
1440
+ maxSpawnsPerRun?: number;
1441
+ defaultModel?: string;
1442
+ allowNesting?: boolean;
1443
+ defaultTimeoutMs?: number;
1444
+ };
1445
+ /**
1446
+ * Enables the synthesized `code_mode` tool: the model writes JS that calls
1447
+ * pool tools inside a sandbox instead of issuing individual tool calls.
1448
+ */
1449
+ codeModeConfig?: {
1450
+ toolPool: string[];
1451
+ description?: string;
1452
+ timeoutMs?: number;
1421
1453
  };
1422
1454
  };
1423
1455
  /** Artifact kinds for the Persona sidebar and dispatch payload */
@@ -1473,8 +1505,13 @@ type ClientToolDefinition = {
1473
1505
  description: string;
1474
1506
  /** JSON Schema (per WebMCP spec) — passed through as-is. */
1475
1507
  parametersSchema?: object;
1476
- /** Set to `'webmcp'` for tools discovered via the polyfill. */
1477
- origin?: 'webmcp' | 'local';
1508
+ /**
1509
+ * `'webmcp'` for tools discovered via the polyfill (server prepends the
1510
+ * `webmcp:` wire prefix); `'sdk'` for widget/SDK-provided tools (name stays
1511
+ * bare on the wire). Matches the server's accepted enum — any other value
1512
+ * fails dispatch validation.
1513
+ */
1514
+ origin?: 'webmcp' | 'sdk';
1478
1515
  /** Origin of the page that registered the tool — for server-side audit. */
1479
1516
  pageOrigin?: string;
1480
1517
  /**
@@ -1603,6 +1640,13 @@ type AgentMessageMetadata = {
1603
1640
  * paginated stepper. Persists alongside `askUserQuestionAnswers`.
1604
1641
  */
1605
1642
  askUserQuestionIndex?: number;
1643
+ /**
1644
+ * Set to `true` once a `suggest_replies` tool call's fire-and-forget
1645
+ * `/resume` has been accepted by the server. Persisted belt-and-suspenders
1646
+ * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
1647
+ * never re-resume the call.
1648
+ */
1649
+ suggestRepliesResolved?: boolean;
1606
1650
  };
1607
1651
  type AgentWidgetRequestMiddlewareContext = {
1608
1652
  payload: AgentWidgetRequestPayload;
@@ -2248,6 +2292,37 @@ type AgentWidgetFeatureFlags = {
2248
2292
  * pills + optional free-text input.
2249
2293
  */
2250
2294
  askUserQuestion?: AgentWidgetAskUserQuestionFeature;
2295
+ /**
2296
+ * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
2297
+ * the tool, the widget shows the suggestions as tappable chips above the
2298
+ * composer (reusing the suggestion-chips surface) and immediately resumes
2299
+ * the execution — fire-and-forget, no user input awaited.
2300
+ */
2301
+ suggestReplies?: AgentWidgetSuggestRepliesFeature;
2302
+ };
2303
+ /**
2304
+ * Feature config for the built-in `suggest_replies` quick-reply chips.
2305
+ * Chips render in the existing suggestions slot above the composer and are
2306
+ * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
2307
+ * verbatim as the user's next message; chips clear once any user message
2308
+ * follows them.
2309
+ */
2310
+ type AgentWidgetSuggestRepliesFeature = {
2311
+ /**
2312
+ * Enable the feature. Defaults to true. When false, `suggest_replies`
2313
+ * renders as a regular tool bubble and is NOT auto-resumed — only set this
2314
+ * with no server-side `suggest_replies` declaration, or the execution
2315
+ * parks awaiting a resume that never comes.
2316
+ */
2317
+ enabled?: boolean;
2318
+ /**
2319
+ * Advertise the built-in `suggest_replies` tool to the agent on every
2320
+ * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
2321
+ * needed. Defaults to `false`: flows that already declare the tool via
2322
+ * `runtimeTools` would otherwise present it to the model twice. Ignored
2323
+ * when `enabled` is `false`.
2324
+ */
2325
+ expose?: boolean;
2251
2326
  };
2252
2327
  /**
2253
2328
  * Single selectable option in an `ask_user_question` prompt.
@@ -2308,6 +2383,19 @@ type AgentWidgetAskUserQuestionStyles = {
2308
2383
  type AgentWidgetAskUserQuestionFeature = {
2309
2384
  /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
2310
2385
  enabled?: boolean;
2386
+ /**
2387
+ * Advertise the built-in `ask_user_question` tool to the agent on every
2388
+ * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
2389
+ * needed. The tool ships with a model-facing description and JSON schema
2390
+ * matching {@link AskUserQuestionPayload}; when the model calls it, the
2391
+ * existing answer-pill sheet renders and the answer resumes the execution.
2392
+ *
2393
+ * Defaults to `false`: flows that already declare `ask_user_question` via
2394
+ * `runtimeTools` would otherwise present the tool to the model twice.
2395
+ * Ignored when `enabled` is `false` — never offer the agent a question
2396
+ * tool the widget can't render an answer UI for.
2397
+ */
2398
+ expose?: boolean;
2311
2399
  /** Slide-in animation duration in ms. Defaults to 180. */
2312
2400
  slideInMs?: number;
2313
2401
  /** Label for the free-text pill. Defaults to "Other…". */
@@ -2489,6 +2577,26 @@ type AgentWidgetDockConfig = {
2489
2577
  * it appears to emerge at full width like a floating widget.
2490
2578
  */
2491
2579
  reveal?: "resize" | "overlay" | "push" | "emerge";
2580
+ /**
2581
+ * Maximum height of the dock panel, applied as a viewport-overflow guard.
2582
+ *
2583
+ * The docked shell sizes itself with `height: 100%`, which only resolves when
2584
+ * an ancestor (usually `html, body { height: 100% }`) provides a definite
2585
+ * height. Without one, the dock column would otherwise grow with the
2586
+ * conversation and scroll off the page. This cap clamps the panel to the
2587
+ * viewport (and keeps the `resize`/`emerge` reveals pinned with
2588
+ * `position: sticky`; `push`/`overlay` get the cap only, since their
2589
+ * transform/absolute contexts defeat sticky) so a missing height chain
2590
+ * degrades gracefully instead of breaking the chat.
2591
+ *
2592
+ * - Set a CSS length (e.g. `"600px"`, `"80vh"`) to override the cap.
2593
+ * - Set `false` to disable the guard entirely (the panel then sizes purely
2594
+ * from the surrounding layout — make sure your page provides a definite
2595
+ * height all the way down to the dock target's parent).
2596
+ *
2597
+ * @default "100dvh"
2598
+ */
2599
+ maxHeight?: string | false;
2492
2600
  };
2493
2601
  /**
2494
2602
  * Layout configuration for `mountMode: "composer-bar"`. Controls how the
@@ -5768,8 +5876,15 @@ interface ToolTextContent {
5768
5876
  type: 'text';
5769
5877
  text: string;
5770
5878
  }
5879
+ /** MCP image content block: raw base64 (no `data:` prefix) plus its MIME type. */
5880
+ interface ToolImageContent {
5881
+ type: 'image';
5882
+ data: string;
5883
+ mimeType: string;
5884
+ }
5885
+ type ToolContent = ToolTextContent | ToolImageContent;
5771
5886
  interface ToolResult {
5772
- content: ToolTextContent[];
5887
+ content: ToolContent[];
5773
5888
  /** Optional machine-readable mirror of the text content. */
5774
5889
  structuredContent?: unknown;
5775
5890
  isError?: boolean;
@@ -5789,7 +5904,11 @@ interface WebMcpTool {
5789
5904
  annotations?: ToolAnnotations;
5790
5905
  execute: ToolExecute;
5791
5906
  }
5792
- /** Wrap a JSON-serializable payload in the MCP tool-result envelope. */
5907
+ /**
5908
+ * Wrap a JSON-serializable payload in the MCP tool-result envelope. Compact
5909
+ * JSON (no indentation) — the text is consumed by a model, where pretty-print
5910
+ * whitespace is pure token overhead.
5911
+ */
5793
5912
  declare function toolResult(payload: unknown): ToolResult;
5794
5913
  /**
5795
5914
  * Structural subset of `ThemeEditorState` (and the example app's `state`
@@ -5938,4 +6057,4 @@ declare function runContrastChecks(state: ThemeEditorLike, level?: ContrastLevel
5938
6057
  /** Compact contrast warnings for the regions a mutation touched. */
5939
6058
  declare function quickContrastWarnings(state: ThemeEditorLike, pairKeys: string[], variant?: 'light' | 'dark' | 'both', level?: ContrastLevel): ContrastWarning[];
5940
6059
 
5941
- export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolExecute, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };
6060
+ export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, type BuildTranscriptStreamFramesOptions, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, CONTRAST_PAIRS, CSS_NAMED_COLORS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, type ContrastCheck, type ContrastLevel, type ContrastReport, type ContrastWarning, type CreateThemeEditorToolsOptions, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type EditTarget, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, type PreviewTranscriptEntryPreset, RADIUS_PRESETS, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleState, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorLike, type ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type ThemeSummary, type TokenRefOptions, type ToolAnnotations, type ToolContent, type ToolExecute, type ToolImageContent, type ToolResult, type ToolTextContent, type TranscriptStreamFrame, type WebMcpTool, ZOOM_MAX, ZOOM_MIN, appendPreviewTranscriptEntry, applySceneConfig, applyShellTheme, buildPreviewConfig, buildPreviewConfigWithMessages, buildShellCss, buildSrcdoc, buildSummary, buildTranscriptStreamFrames, coerceColor, coerceFamily, coerceIntensity, coerceRadius, coerceRoundnessStyle, coerceScheme, convertFromPx, convertToPx, createPreviewMessages, createPreviewTranscriptEntry, createThemeEditorTools, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getPreviewTranscriptPresetLabel, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, presetStreamsText, quickContrastWarnings, resolveRoleAssignment, resolveThemeColorPath, rgbToHex, runContrastChecks, scopeSection, tokenRefDisplayName, toolResult, wcagContrastRatio };