@runtypelabs/persona 3.29.1 → 3.30.0

package/dist/theme-editor.d.cts

@@ -306,6 +306,8 @@ interface ApprovalTokens {
         background: TokenReference<'color'>;
         border: TokenReference<'color'>;
         text: TokenReference<'color'>;
+        /** Box-shadow for the approval bubble (token ref or raw CSS, e.g. `none`). */
+        shadow: string;
     };
     approve: ComponentTokenSet;
     deny: ComponentTokenSet;
@@ -628,13 +630,59 @@ interface AgentWidgetPlugin {
         config: AgentWidgetConfig;
     }) => HTMLElement | null;
     /**
-     * Custom renderer for approval bubbles
-     * Return null to use default renderer
+     * Custom renderer for approval bubbles.
+     *
+     * Return an `HTMLElement` to fully own the approval UI, `defaultRenderer()`
+     * to render (or wrap) the built-in bubble, or `null` to fall through to the
+     * default. Unlike the built-in bubble — whose Approve/Deny buttons are wired
+     * via delegation — a fully custom element resolves the approval by calling
+     * the `approve`/`deny` callbacks. Both route through the same path the
+     * built-in buttons use (optimistic update, `onDecision`, in-place anchoring).
+     *
+     * An approval is a single binary gate, so there are exactly two outcomes.
+     * Pass `{ remember: true }` to flag a "remember this" affordance (e.g. an
+     * "Always allow" button); the current approval resolves identically, but the
+     * flag is forwarded to `config.approval.onDecision` so you can persist a
+     * don't-ask-again policy for future approvals.
+     *
+     * `renderApproval` is called again whenever the approval's status changes, so
+     * branch on `message.approval?.status` to render the resolved state (and tear
+     * down any global listeners you added while pending).
+     *
+     * @example
+     * ```typescript
+     * // An alternative prompt: "Always allow" / "Allow once" / "Deny".
+     * renderApproval: ({ message, approve, deny }) => {
+     *   const approval = message.approval;
+     *   if (!approval || approval.status !== "pending") return null; // default renders resolved state
+     *   const root = document.createElement("div");
+     *   root.textContent = `${approval.toolName} requires approval`;
+     *
+     *   const always = document.createElement("button");
+     *   always.textContent = "Always allow";
+     *   always.addEventListener("click", () => approve({ remember: true }));
+     *
+     *   const once = document.createElement("button");
+     *   once.textContent = "Allow once";
+     *   once.addEventListener("click", () => approve());
+     *
+     *   const no = document.createElement("button");
+     *   no.textContent = "Deny";
+     *   no.addEventListener("click", () => deny());
+     *
+     *   root.append(always, once, no);
+     *   return root;
+     * }
+     * ```
      */
     renderApproval?: (context: {
         message: AgentWidgetMessage;
         defaultRenderer: () => HTMLElement;
         config: AgentWidgetConfig;
+        /** Resolve this approval as approved. Pass `{ remember: true }` for an "Always allow" affordance. */
+        approve: (options?: AgentWidgetApprovalDecisionOptions) => void;
+        /** Resolve this approval as denied. Pass `{ remember: true }` for an "Always deny" affordance. */
+        deny: (options?: AgentWidgetApprovalDecisionOptions) => void;
     }) => HTMLElement | null;
     /**
      * Custom renderer for loading indicator
@@ -1446,6 +1494,12 @@ type WebMcpConfirmInfo = {
     toolName: string;
     args: unknown;
     description?: string;
+    /**
+     * Display title the tool declared via the WebMCP spec's
+     * `ToolDescriptor.title` (e.g. `"Add to Cart"`). Absent when the tool
+     * didn't declare one.
+     */
+    title?: string;
     annotations?: {
         readOnlyHint?: boolean;
         untrustedContentHint?: boolean;
@@ -2807,6 +2861,22 @@ type TextToSpeechConfig = {
     /** Speech pitch (0 - 2). Default: 1 */
     pitch?: number;
 };
+/**
+ * Extra context for an approval decision, surfaced to `onDecision` and to the
+ * `approve`/`deny` callbacks passed to the `renderApproval` plugin hook.
+ */
+type AgentWidgetApprovalDecisionOptions = {
+    /**
+     * The user chose a "remember this" affordance (e.g. an "Always allow"
+     * button) rather than a one-time decision. The widget resolves the *current*
+     * approval identically whether or not this is set — an approval bubble is a
+     * single binary gate (`approved`/`denied`). Persisting a don't-ask-again
+     * policy for *future* approvals (auto-resolving them, or not surfacing them)
+     * is the integrator's responsibility, typically inside `onDecision`.
+     * Defaults to absent/`false`.
+     */
+    remember?: boolean;
+};
 /**
  * Configuration for tool approval bubbles.
  * Controls styling, labels, and behavior of the approval UI.
@@ -2816,6 +2886,8 @@ type AgentWidgetApprovalConfig = {
     backgroundColor?: string;
     /** Border color of the approval bubble */
     borderColor?: string;
+    /** Box-shadow for the approval bubble; pass `"none"` to remove it. Overrides the default `persona-shadow-sm`. */
+    shadow?: string;
     /** Color for the title text */
     titleColor?: string;
     /** Color for the description text */
@@ -2838,20 +2910,51 @@ type AgentWidgetApprovalConfig = {
     approveLabel?: string;
     /** Label for the deny button */
     denyLabel?: string;
+    /**
+     * How the technical details (the tool's agent-facing description and the
+     * raw parameters JSON) are presented:
+     * - `"collapsed"` (default) — hidden behind a "Show details" toggle
+     * - `"expanded"` — visible, with the toggle available to hide them
+     * - `"hidden"` — never rendered
+     */
+    detailsDisplay?: "collapsed" | "expanded" | "hidden";
+    /** Label for the toggle that reveals the technical details */
+    showDetailsLabel?: string;
+    /** Label for the toggle that hides the technical details */
+    hideDetailsLabel?: string;
+    /**
+     * Build the user-facing summary line for an approval request. Overrides the
+     * default "The assistant wants to use “Tool name”." copy. Return a falsy
+     * value to fall back to the default for that approval. `displayTitle` is
+     * the display name the tool declared via the WebMCP spec's
+     * `ToolDescriptor.title`, when one exists.
+     */
+    formatDescription?: (approval: {
+        toolName: string;
+        toolType?: string;
+        description: string;
+        parameters?: unknown;
+        displayTitle?: string;
+    }) => string | undefined;
     /**
      * Custom handler for approval decisions.
      * Return void to let the SDK auto-resolve via the API,
      * or return a Response/ReadableStream for custom handling.
+     *
+     * `options.remember` is `true` when the decision came from a "remember this"
+     * affordance (e.g. an "Always allow" button in a custom `renderApproval`
+     * plugin). Use it to persist a don't-ask-again policy for future approvals;
+     * the current approval resolves the same way regardless.
      */
     onDecision?: (data: {
         approvalId: string;
         executionId: string;
         agentId: string;
         toolName: string;
-    }, decision: 'approved' | 'denied') => Promise<Response | ReadableStream<Uint8Array> | void>;
+    }, decision: 'approved' | 'denied', options?: AgentWidgetApprovalDecisionOptions) => Promise<Response | ReadableStream<Uint8Array> | void>;
 };
 type AgentWidgetToolCallConfig$1 = {
-    /** Box-shadow for tool-call bubbles; overrides `theme.toolBubbleShadow` when set. */
+    /** Box-shadow for tool-call bubbles; pass `"none"` to remove it. Overrides the `components.toolBubble.shadow` token / `--persona-tool-bubble-shadow`. */
     shadow?: string;
     /** Background color of the tool call bubble container. */
     backgroundColor?: string;
@@ -5337,8 +5440,10 @@ type Controller = {
      * Programmatically resolve a pending approval.
      * @param approvalId - The approval ID to resolve
      * @param decision - "approved" or "denied"
+     * @param options - Optional decision context (e.g. `{ remember: true }`),
+     *   forwarded to `config.approval.onDecision`.
      */
-    resolveApproval: (approvalId: string, decision: 'approved' | 'denied') => Promise<void>;
+    resolveApproval: (approvalId: string, decision: 'approved' | 'denied', options?: AgentWidgetApprovalDecisionOptions) => Promise<void>;
 };
 type AgentWidgetController = Controller;
 
@@ -5385,7 +5490,7 @@ declare const MOCK_WORKSPACE_CONTENT = "\n    <div class=\"preview-workspace-con
  */
 declare function buildSrcdoc(mountId: string, shellMode: 'light' | 'dark', docked: boolean, widgetCssPath: string): string;
 type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
-type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'assistant-code-block' | 'assistant-markdown-table' | 'assistant-image' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete';
+type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'assistant-code-block' | 'assistant-markdown-table' | 'assistant-image' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete' | 'approval-request';
 declare function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string;
 declare function createPreviewTranscriptEntry(preset: PreviewTranscriptEntryPreset, index?: number): AgentWidgetMessage;
 declare function appendPreviewTranscriptEntry(messages: AgentWidgetMessage[], preset: PreviewTranscriptEntryPreset): AgentWidgetMessage[];

package/dist/theme-editor.d.ts

@@ -306,6 +306,8 @@ interface ApprovalTokens {
         background: TokenReference<'color'>;
         border: TokenReference<'color'>;
         text: TokenReference<'color'>;
+        /** Box-shadow for the approval bubble (token ref or raw CSS, e.g. `none`). */
+        shadow: string;
     };
     approve: ComponentTokenSet;
     deny: ComponentTokenSet;
@@ -628,13 +630,59 @@ interface AgentWidgetPlugin {
         config: AgentWidgetConfig;
     }) => HTMLElement | null;
     /**
-     * Custom renderer for approval bubbles
-     * Return null to use default renderer
+     * Custom renderer for approval bubbles.
+     *
+     * Return an `HTMLElement` to fully own the approval UI, `defaultRenderer()`
+     * to render (or wrap) the built-in bubble, or `null` to fall through to the
+     * default. Unlike the built-in bubble — whose Approve/Deny buttons are wired
+     * via delegation — a fully custom element resolves the approval by calling
+     * the `approve`/`deny` callbacks. Both route through the same path the
+     * built-in buttons use (optimistic update, `onDecision`, in-place anchoring).
+     *
+     * An approval is a single binary gate, so there are exactly two outcomes.
+     * Pass `{ remember: true }` to flag a "remember this" affordance (e.g. an
+     * "Always allow" button); the current approval resolves identically, but the
+     * flag is forwarded to `config.approval.onDecision` so you can persist a
+     * don't-ask-again policy for future approvals.
+     *
+     * `renderApproval` is called again whenever the approval's status changes, so
+     * branch on `message.approval?.status` to render the resolved state (and tear
+     * down any global listeners you added while pending).
+     *
+     * @example
+     * ```typescript
+     * // An alternative prompt: "Always allow" / "Allow once" / "Deny".
+     * renderApproval: ({ message, approve, deny }) => {
+     *   const approval = message.approval;
+     *   if (!approval || approval.status !== "pending") return null; // default renders resolved state
+     *   const root = document.createElement("div");
+     *   root.textContent = `${approval.toolName} requires approval`;
+     *
+     *   const always = document.createElement("button");
+     *   always.textContent = "Always allow";
+     *   always.addEventListener("click", () => approve({ remember: true }));
+     *
+     *   const once = document.createElement("button");
+     *   once.textContent = "Allow once";
+     *   once.addEventListener("click", () => approve());
+     *
+     *   const no = document.createElement("button");
+     *   no.textContent = "Deny";
+     *   no.addEventListener("click", () => deny());
+     *
+     *   root.append(always, once, no);
+     *   return root;
+     * }
+     * ```
      */
     renderApproval?: (context: {
         message: AgentWidgetMessage;
         defaultRenderer: () => HTMLElement;
         config: AgentWidgetConfig;
+        /** Resolve this approval as approved. Pass `{ remember: true }` for an "Always allow" affordance. */
+        approve: (options?: AgentWidgetApprovalDecisionOptions) => void;
+        /** Resolve this approval as denied. Pass `{ remember: true }` for an "Always deny" affordance. */
+        deny: (options?: AgentWidgetApprovalDecisionOptions) => void;
     }) => HTMLElement | null;
     /**
      * Custom renderer for loading indicator
@@ -1446,6 +1494,12 @@ type WebMcpConfirmInfo = {
     toolName: string;
     args: unknown;
     description?: string;
+    /**
+     * Display title the tool declared via the WebMCP spec's
+     * `ToolDescriptor.title` (e.g. `"Add to Cart"`). Absent when the tool
+     * didn't declare one.
+     */
+    title?: string;
     annotations?: {
         readOnlyHint?: boolean;
         untrustedContentHint?: boolean;
@@ -2807,6 +2861,22 @@ type TextToSpeechConfig = {
     /** Speech pitch (0 - 2). Default: 1 */
     pitch?: number;
 };
+/**
+ * Extra context for an approval decision, surfaced to `onDecision` and to the
+ * `approve`/`deny` callbacks passed to the `renderApproval` plugin hook.
+ */
+type AgentWidgetApprovalDecisionOptions = {
+    /**
+     * The user chose a "remember this" affordance (e.g. an "Always allow"
+     * button) rather than a one-time decision. The widget resolves the *current*
+     * approval identically whether or not this is set — an approval bubble is a
+     * single binary gate (`approved`/`denied`). Persisting a don't-ask-again
+     * policy for *future* approvals (auto-resolving them, or not surfacing them)
+     * is the integrator's responsibility, typically inside `onDecision`.
+     * Defaults to absent/`false`.
+     */
+    remember?: boolean;
+};
 /**
  * Configuration for tool approval bubbles.
  * Controls styling, labels, and behavior of the approval UI.
@@ -2816,6 +2886,8 @@ type AgentWidgetApprovalConfig = {
     backgroundColor?: string;
     /** Border color of the approval bubble */
     borderColor?: string;
+    /** Box-shadow for the approval bubble; pass `"none"` to remove it. Overrides the default `persona-shadow-sm`. */
+    shadow?: string;
     /** Color for the title text */
     titleColor?: string;
     /** Color for the description text */
@@ -2838,20 +2910,51 @@ type AgentWidgetApprovalConfig = {
     approveLabel?: string;
     /** Label for the deny button */
     denyLabel?: string;
+    /**
+     * How the technical details (the tool's agent-facing description and the
+     * raw parameters JSON) are presented:
+     * - `"collapsed"` (default) — hidden behind a "Show details" toggle
+     * - `"expanded"` — visible, with the toggle available to hide them
+     * - `"hidden"` — never rendered
+     */
+    detailsDisplay?: "collapsed" | "expanded" | "hidden";
+    /** Label for the toggle that reveals the technical details */
+    showDetailsLabel?: string;
+    /** Label for the toggle that hides the technical details */
+    hideDetailsLabel?: string;
+    /**
+     * Build the user-facing summary line for an approval request. Overrides the
+     * default "The assistant wants to use “Tool name”." copy. Return a falsy
+     * value to fall back to the default for that approval. `displayTitle` is
+     * the display name the tool declared via the WebMCP spec's
+     * `ToolDescriptor.title`, when one exists.
+     */
+    formatDescription?: (approval: {
+        toolName: string;
+        toolType?: string;
+        description: string;
+        parameters?: unknown;
+        displayTitle?: string;
+    }) => string | undefined;
     /**
      * Custom handler for approval decisions.
      * Return void to let the SDK auto-resolve via the API,
      * or return a Response/ReadableStream for custom handling.
+     *
+     * `options.remember` is `true` when the decision came from a "remember this"
+     * affordance (e.g. an "Always allow" button in a custom `renderApproval`
+     * plugin). Use it to persist a don't-ask-again policy for future approvals;
+     * the current approval resolves the same way regardless.
      */
     onDecision?: (data: {
         approvalId: string;
         executionId: string;
         agentId: string;
         toolName: string;
-    }, decision: 'approved' | 'denied') => Promise<Response | ReadableStream<Uint8Array> | void>;
+    }, decision: 'approved' | 'denied', options?: AgentWidgetApprovalDecisionOptions) => Promise<Response | ReadableStream<Uint8Array> | void>;
 };
 type AgentWidgetToolCallConfig$1 = {
-    /** Box-shadow for tool-call bubbles; overrides `theme.toolBubbleShadow` when set. */
+    /** Box-shadow for tool-call bubbles; pass `"none"` to remove it. Overrides the `components.toolBubble.shadow` token / `--persona-tool-bubble-shadow`. */
     shadow?: string;
     /** Background color of the tool call bubble container. */
     backgroundColor?: string;
@@ -5337,8 +5440,10 @@ type Controller = {
      * Programmatically resolve a pending approval.
      * @param approvalId - The approval ID to resolve
      * @param decision - "approved" or "denied"
+     * @param options - Optional decision context (e.g. `{ remember: true }`),
+     *   forwarded to `config.approval.onDecision`.
      */
-    resolveApproval: (approvalId: string, decision: 'approved' | 'denied') => Promise<void>;
+    resolveApproval: (approvalId: string, decision: 'approved' | 'denied', options?: AgentWidgetApprovalDecisionOptions) => Promise<void>;
 };
 type AgentWidgetController = Controller;
 
@@ -5385,7 +5490,7 @@ declare const MOCK_WORKSPACE_CONTENT = "\n    <div class=\"preview-workspace-con
  */
 declare function buildSrcdoc(mountId: string, shellMode: 'light' | 'dark', docked: boolean, widgetCssPath: string): string;
 type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
-type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'assistant-code-block' | 'assistant-markdown-table' | 'assistant-image' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete';
+type PreviewTranscriptEntryPreset = 'user-message' | 'assistant-message' | 'assistant-code-block' | 'assistant-markdown-table' | 'assistant-image' | 'reasoning-streaming' | 'reasoning-complete' | 'tool-running' | 'tool-complete' | 'approval-request';
 declare function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string;
 declare function createPreviewTranscriptEntry(preset: PreviewTranscriptEntryPreset, index?: number): AgentWidgetMessage;
 declare function appendPreviewTranscriptEntry(messages: AgentWidgetMessage[], preset: PreviewTranscriptEntryPreset): AgentWidgetMessage[];