@runtypelabs/persona 3.29.1 → 3.31.0

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;
@@ -1113,6 +1161,7 @@ type RuntypeAgentSSEEvent = {
     };
     iteration?: number;
     parameters?: Record<string, unknown>;
+    reason?: string;
     seq: number;
     startedAt: string;
     timeout: number;
@@ -1384,6 +1433,7 @@ type RuntypeFlowSSEEvent = {
     when: string;
 } | {
     executionId?: string;
+    reason?: string;
     seq?: number;
     type: "step_await";
     [key: string]: unknown;
@@ -1715,6 +1765,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;
@@ -2110,6 +2166,29 @@ type AgentWidgetArtifactsFeature = {
         defaultRenderer: () => HTMLElement;
     }) => HTMLElement | null;
 };
+/**
+ * How the transcript scrolls while an assistant response streams in.
+ *
+ * - `"follow"` (default): keep the newest content pinned to the bottom of the
+ *   viewport, pausing when the user scrolls up and resuming when they return
+ *   to the bottom.
+ * - `"anchor-top"`: on send, scroll the user's message near the top of the
+ *   viewport and hold it there while the response streams in beneath it
+ *   (ChatGPT-style). The transcript never auto-scrolls during streaming.
+ * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
+ *   way back to the latest content.
+ */
+type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
+type AgentWidgetScrollBehaviorFeature = {
+    /** Scroll behavior during streamed responses. @default "follow" */
+    mode?: AgentWidgetScrollMode;
+    /**
+     * Gap (px) kept between the anchored user message and the top of the
+     * viewport in `"anchor-top"` mode.
+     * @default 16
+     */
+    anchorTopOffset?: number;
+};
 type AgentWidgetScrollToBottomFeature = {
     /**
      * When true, Persona shows a scroll-to-bottom affordance when the user breaks
@@ -2373,6 +2452,8 @@ type AgentWidgetFeatureFlags = {
     composerHistory?: boolean;
     /** Shared transcript + event stream scroll-to-bottom affordance. */
     scrollToBottom?: AgentWidgetScrollToBottomFeature;
+    /** Transcript scroll behavior during streamed responses. */
+    scrollBehavior?: AgentWidgetScrollBehaviorFeature;
     /** Collapsed transcript behavior for tool call rows. */
     toolCallDisplay?: AgentWidgetToolCallDisplayFeature;
     /** Collapsed transcript behavior for reasoning rows. */
@@ -3029,6 +3110,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 +3135,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 +3159,67 @@ type AgentWidgetApprovalConfig = {
     approveLabel?: string;
     /** Label for the deny button */
     denyLabel?: string;
+    /**
+     * Color for the agent-authored reason line (the agent's per-call
+     * justification, shown attributed below the summary when present).
+     */
+    reasonColor?: string;
+    /**
+     * Label prefix for the agent-authored reason line.
+     * Defaults to "Agent's stated reason:".
+     */
+    reasonLabel?: 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;
+        /**
+         * Agent-authored justification for this specific call, when the agent
+         * provided one. It is the agent's own claim — if you fold it into the
+         * summary, keep it attributed to the agent.
+         */
+        reason?: 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;
@@ -4863,6 +5009,13 @@ type AgentWidgetApproval = {
     toolName: string;
     toolType?: string;
     description: string;
+    /**
+     * Agent-authored justification for this specific call (the agent's own
+     * claim about its intent, extracted server-side from the reserved
+     * `_approvalReason` parameter). Render it attributed to the agent and as
+     * plain text — it is approver context, not a system statement.
+     */
+    reason?: string;
     parameters?: unknown;
     resolvedAt?: number;
 };