@runtypelabs/persona 3.29.1 → 3.30.0

package/dist/plugin-kit.cjs

@@ -0,0 +1 @@
+"use strict";var w=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var M=Object.prototype.hasOwnProperty;var N=(e,t)=>{for(var o in t)w(e,o,{get:t[o],enumerable:!0})},I=(e,t,o,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of H(t))!M.call(e,r)&&r!==o&&w(e,r,{get:()=>t[r],enumerable:!(n=C(t,r))||n.enumerable});return e};var O=e=>I(w({},"__esModule",{value:!0}),e);var B={};N(B,{createPopover:()=>$,getStyleRoot:()=>g,injectStyles:()=>z,isEditableEventTarget:()=>W});module.exports=O(B);function g(e){var o,n;let t=(o=e.getRootNode)==null?void 0:o.call(e);return t instanceof ShadowRoot||t instanceof Document?t:(n=e.ownerDocument)!=null?n:document}function v(e,t,o){var s;let n=e instanceof Document?e.head:e,r=t.replace(/["\\]/g,"\\$&");if(n.querySelector(`style[data-persona-plugin-style="${r}"]`))return;let c=(e instanceof Document?e:(s=e.ownerDocument)!=null?s:document).createElement("style");c.setAttribute("data-persona-plugin-style",t),c.textContent=o,n.appendChild(c)}function z(e,t,o){var l;if(e instanceof Document||e instanceof ShadowRoot){v(e,t,o);return}let n=e;if(n.isConnected){v(g(n),t,o);return}let r=(l=n.ownerDocument)!=null?l:document;v(r,t,o),queueMicrotask(()=>{let c=g(n);c!==r&&v(c,t,o)})}function A(e){var o,n;let t=(o=e.getRootNode)==null?void 0:o.call(e);return t instanceof ShadowRoot?t:((n=e.ownerDocument)!=null?n:document).body}function $(e){var y;let{anchor:t,content:o,placement:n="bottom-start",offset:r=6,matchAnchorWidth:l=!1,zIndex:c=2147483e3,onOpen:s,onDismiss:a}=e,S=(y=e.container)!=null?y:A(t),d=!1,m=null,h=()=>{if(!d)return;let i=t.getBoundingClientRect();o.style.position="fixed",l&&(o.style.minWidth=`${i.width}px`);let f=n==="top-start"||n==="top-end"?i.top-r-o.getBoundingClientRect().height:i.bottom+r,u=n==="bottom-end"||n==="top-end"?i.right-o.getBoundingClientRect().width:i.left;o.style.top=`${f}px`,o.style.left=`${u}px`},p=()=>{d&&(d=!1,m&&(m(),m=null),o.remove())},E=()=>{var x,b,P;if(d)return;d=!0,c!=null&&(o.style.zIndex=String(c)),S.appendChild(o),h();let i=(b=((x=t.ownerDocument)!=null?x:document).defaultView)!=null?b:window,f=(P=t.ownerDocument)!=null?P:document,u=()=>{if(!t.isConnected){p(),a==null||a("anchor-removed");return}h()},R=D=>{let L=typeof D.composedPath=="function"?D.composedPath():[];L.includes(o)||L.includes(t)||(p(),a==null||a("outside"))},T=i.setTimeout(()=>{f.addEventListener("pointerdown",R,!0)},0);i.addEventListener("scroll",u,!0),i.addEventListener("resize",u),m=()=>{i.clearTimeout(T),f.removeEventListener("pointerdown",R,!0),i.removeEventListener("scroll",u,!0),i.removeEventListener("resize",u)},s==null||s()};return{get isOpen(){return d},open:E,close:p,toggle:()=>d?p():E(),reposition:h,destroy:p}}function W(e){return(typeof e.composedPath=="function"?e.composedPath():[]).some(o=>o instanceof HTMLElement&&(o.tagName==="INPUT"||o.tagName==="TEXTAREA"||o.isContentEditable))}0&&(module.exports={createPopover,getStyleRoot,injectStyles,isEditableEventTarget});

package/dist/plugin-kit.d.cts

@@ -0,0 +1,98 @@
+/**
+ * Resolve the root a node's styles should live in.
+ *
+ * Returns the node's `ShadowRoot` when it (or an ancestor) is shadowed, the
+ * owning `Document` otherwise. A `<style>` placed in this root reaches the node
+ * regardless of whether the widget runs in light or shadow DOM. For a detached
+ * node (one not yet mounted) this falls back to the owning document.
+ */
+declare function getStyleRoot(node: Node): Document | ShadowRoot;
+/**
+ * Inject a plugin's CSS once into the correct root — the widget's shadow root
+ * when shadowed, the document head otherwise. Idempotent: keyed by `id`, so it
+ * is safe to call on every render.
+ *
+ * Pass the element you're about to return from a render hook. While building, an
+ * element is detached and its eventual root is unknown, so this injects into the
+ * owning document immediately (covering the default light-DOM case with no
+ * flash) and then, on the next microtask — after the widget has mounted the
+ * element — re-resolves and also injects into its shadow root if it landed in
+ * one. You may also pass an explicit `Document` or `ShadowRoot`.
+ *
+ * @example
+ * ```ts
+ * renderApproval: ({ message, approve, deny }) => {
+ *   const card = buildCard(message.approval, approve, deny);
+ *   injectStyles(card, "my-approval-plugin", CSS);
+ *   return card;
+ * }
+ * ```
+ */
+declare function injectStyles(target: Node | Document | ShadowRoot, id: string, css: string): void;
+type PopoverPlacement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
+interface PopoverOptions {
+    /** Element the popover is positioned against. */
+    anchor: HTMLElement;
+    /** The floating element (menu, tooltip, panel). Built detached; mounted on `open`. */
+    content: HTMLElement;
+    /** Where to place `content` relative to `anchor`. Default `"bottom-start"`. */
+    placement?: PopoverPlacement;
+    /** Gap in px between anchor and content. Default `6`. */
+    offset?: number;
+    /** Set `content`'s `min-width` to the anchor's width. Default `false`. */
+    matchAnchorWidth?: boolean;
+    /**
+     * Inline `z-index` for `content`. Default `2147483000` so it overlays the rest
+     * of the widget. Pass `null` to leave z-index to your own CSS.
+     */
+    zIndex?: number | null;
+    /**
+     * Where to mount `content`. Defaults to the anchor's shadow root (when
+     * shadowed) or `document.body` — keeping it inside the same style + stacking
+     * scope as the anchor while escaping the transcript's scroll clipping.
+     */
+    container?: HTMLElement | ShadowRoot;
+    onOpen?: () => void;
+    /** Fired when the popover closes by itself (outside click or the anchor leaving the DOM). */
+    onDismiss?: (reason: "outside" | "anchor-removed") => void;
+}
+interface PopoverHandle {
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** Recompute position from the current anchor rect (called automatically on scroll/resize). */
+    reposition(): void;
+    /** Close and release all listeners; the handle is inert afterward. */
+    destroy(): void;
+}
+/**
+ * A floating popover anchored to an element: `fixed`-positioned (so it overlays
+ * the rest of the widget and isn't clipped by scroll containers), dismissed on
+ * outside pointerdown, repositioned on scroll/resize, and auto-closed if the
+ * anchor leaves the DOM. Mount your styles with {@link injectStyles}.
+ *
+ * @example
+ * ```ts
+ * const popover = createPopover({
+ *   anchor: splitButton,
+ *   content: menu,
+ *   placement: "bottom-start",
+ *   matchAnchorWidth: true,
+ * });
+ * caret.addEventListener("click", () => popover.toggle());
+ * // on teardown: popover.destroy();
+ * ```
+ */
+declare function createPopover(options: PopoverOptions): PopoverHandle;
+/**
+ * Whether an event originated from an editable element (`<input>`, `<textarea>`,
+ * or `contenteditable`). Use it to avoid hijacking keys like Enter/Escape while
+ * the user is typing in the composer.
+ *
+ * Inspects the composed path, so it works for events that cross the widget's
+ * Shadow-DOM boundary (where `event.target` is retargeted to the host).
+ */
+declare function isEditableEventTarget(event: Event): boolean;
+
+export { type PopoverHandle, type PopoverOptions, type PopoverPlacement, createPopover, getStyleRoot, injectStyles, isEditableEventTarget };

package/dist/plugin-kit.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Resolve the root a node's styles should live in.
+ *
+ * Returns the node's `ShadowRoot` when it (or an ancestor) is shadowed, the
+ * owning `Document` otherwise. A `<style>` placed in this root reaches the node
+ * regardless of whether the widget runs in light or shadow DOM. For a detached
+ * node (one not yet mounted) this falls back to the owning document.
+ */
+declare function getStyleRoot(node: Node): Document | ShadowRoot;
+/**
+ * Inject a plugin's CSS once into the correct root — the widget's shadow root
+ * when shadowed, the document head otherwise. Idempotent: keyed by `id`, so it
+ * is safe to call on every render.
+ *
+ * Pass the element you're about to return from a render hook. While building, an
+ * element is detached and its eventual root is unknown, so this injects into the
+ * owning document immediately (covering the default light-DOM case with no
+ * flash) and then, on the next microtask — after the widget has mounted the
+ * element — re-resolves and also injects into its shadow root if it landed in
+ * one. You may also pass an explicit `Document` or `ShadowRoot`.
+ *
+ * @example
+ * ```ts
+ * renderApproval: ({ message, approve, deny }) => {
+ *   const card = buildCard(message.approval, approve, deny);
+ *   injectStyles(card, "my-approval-plugin", CSS);
+ *   return card;
+ * }
+ * ```
+ */
+declare function injectStyles(target: Node | Document | ShadowRoot, id: string, css: string): void;
+type PopoverPlacement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
+interface PopoverOptions {
+    /** Element the popover is positioned against. */
+    anchor: HTMLElement;
+    /** The floating element (menu, tooltip, panel). Built detached; mounted on `open`. */
+    content: HTMLElement;
+    /** Where to place `content` relative to `anchor`. Default `"bottom-start"`. */
+    placement?: PopoverPlacement;
+    /** Gap in px between anchor and content. Default `6`. */
+    offset?: number;
+    /** Set `content`'s `min-width` to the anchor's width. Default `false`. */
+    matchAnchorWidth?: boolean;
+    /**
+     * Inline `z-index` for `content`. Default `2147483000` so it overlays the rest
+     * of the widget. Pass `null` to leave z-index to your own CSS.
+     */
+    zIndex?: number | null;
+    /**
+     * Where to mount `content`. Defaults to the anchor's shadow root (when
+     * shadowed) or `document.body` — keeping it inside the same style + stacking
+     * scope as the anchor while escaping the transcript's scroll clipping.
+     */
+    container?: HTMLElement | ShadowRoot;
+    onOpen?: () => void;
+    /** Fired when the popover closes by itself (outside click or the anchor leaving the DOM). */
+    onDismiss?: (reason: "outside" | "anchor-removed") => void;
+}
+interface PopoverHandle {
+    readonly isOpen: boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** Recompute position from the current anchor rect (called automatically on scroll/resize). */
+    reposition(): void;
+    /** Close and release all listeners; the handle is inert afterward. */
+    destroy(): void;
+}
+/**
+ * A floating popover anchored to an element: `fixed`-positioned (so it overlays
+ * the rest of the widget and isn't clipped by scroll containers), dismissed on
+ * outside pointerdown, repositioned on scroll/resize, and auto-closed if the
+ * anchor leaves the DOM. Mount your styles with {@link injectStyles}.
+ *
+ * @example
+ * ```ts
+ * const popover = createPopover({
+ *   anchor: splitButton,
+ *   content: menu,
+ *   placement: "bottom-start",
+ *   matchAnchorWidth: true,
+ * });
+ * caret.addEventListener("click", () => popover.toggle());
+ * // on teardown: popover.destroy();
+ * ```
+ */
+declare function createPopover(options: PopoverOptions): PopoverHandle;
+/**
+ * Whether an event originated from an editable element (`<input>`, `<textarea>`,
+ * or `contenteditable`). Use it to avoid hijacking keys like Enter/Escape while
+ * the user is typing in the composer.
+ *
+ * Inspects the composed path, so it works for events that cross the widget's
+ * Shadow-DOM boundary (where `event.target` is retargeted to the host).
+ */
+declare function isEditableEventTarget(event: Event): boolean;
+
+export { type PopoverHandle, type PopoverOptions, type PopoverPlacement, createPopover, getStyleRoot, injectStyles, isEditableEventTarget };

package/dist/plugin-kit.js

@@ -0,0 +1 @@
+function D(t){var e,n;let o=(e=t.getRootNode)==null?void 0:e.call(t);return o instanceof ShadowRoot||o instanceof Document?o:(n=t.ownerDocument)!=null?n:document}function v(t,o,e){var s;let n=t instanceof Document?t.head:t,c=o.replace(/["\\]/g,"\\$&");if(n.querySelector(`style[data-persona-plugin-style="${c}"]`))return;let i=(t instanceof Document?t:(s=t.ownerDocument)!=null?s:document).createElement("style");i.setAttribute("data-persona-plugin-style",o),i.textContent=e,n.appendChild(i)}function C(t,o,e){var l;if(t instanceof Document||t instanceof ShadowRoot){v(t,o,e);return}let n=t;if(n.isConnected){v(D(n),o,e);return}let c=(l=n.ownerDocument)!=null?l:document;v(c,o,e),queueMicrotask(()=>{let i=D(n);i!==c&&v(i,o,e)})}function T(t){var e,n;let o=(e=t.getRootNode)==null?void 0:e.call(t);return o instanceof ShadowRoot?o:((n=t.ownerDocument)!=null?n:document).body}function H(t){var g;let{anchor:o,content:e,placement:n="bottom-start",offset:c=6,matchAnchorWidth:l=!1,zIndex:i=2147483e3,onOpen:s,onDismiss:a}=t,L=(g=t.container)!=null?g:T(o),d=!1,m=null,h=()=>{if(!d)return;let r=o.getBoundingClientRect();e.style.position="fixed",l&&(e.style.minWidth=`${r.width}px`);let f=n==="top-start"||n==="top-end"?r.top-c-e.getBoundingClientRect().height:r.bottom+c,u=n==="bottom-end"||n==="top-end"?r.right-e.getBoundingClientRect().width:r.left;e.style.top=`${f}px`,e.style.left=`${u}px`},p=()=>{d&&(d=!1,m&&(m(),m=null),e.remove())},w=()=>{var y,R,x;if(d)return;d=!0,i!=null&&(e.style.zIndex=String(i)),L.appendChild(e),h();let r=(R=((y=o.ownerDocument)!=null?y:document).defaultView)!=null?R:window,f=(x=o.ownerDocument)!=null?x:document,u=()=>{if(!o.isConnected){p(),a==null||a("anchor-removed");return}h()},E=b=>{let P=typeof b.composedPath=="function"?b.composedPath():[];P.includes(e)||P.includes(o)||(p(),a==null||a("outside"))},S=r.setTimeout(()=>{f.addEventListener("pointerdown",E,!0)},0);r.addEventListener("scroll",u,!0),r.addEventListener("resize",u),m=()=>{r.clearTimeout(S),f.removeEventListener("pointerdown",E,!0),r.removeEventListener("scroll",u,!0),r.removeEventListener("resize",u)},s==null||s()};return{get isOpen(){return d},open:w,close:p,toggle:()=>d?p():w(),reposition:h,destroy:p}}function M(t){return(typeof t.composedPath=="function"?t.composedPath():[]).some(e=>e instanceof HTMLElement&&(e.tagName==="INPUT"||e.tagName==="TEXTAREA"||e.isContentEditable))}export{H as createPopover,D as getStyleRoot,C as injectStyles,M as isEditableEventTarget};

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

@@ -416,13 +416,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
@@ -797,6 +843,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;
@@ -1715,6 +1763,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;
@@ -3029,6 +3083,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.
@@ -3038,6 +3108,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 */
@@ -3060,20 +3132,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 = {
-    /** 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;

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

@@ -416,13 +416,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
@@ -797,6 +843,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;
@@ -1715,6 +1763,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;
@@ -3029,6 +3083,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.
@@ -3038,6 +3108,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 */
@@ -3060,20 +3132,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 = {
-    /** 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;