@runtypelabs/persona 1.44.2 → 1.46.0

package/src/session.ts

@@ -3,6 +3,7 @@ import {
   AgentWidgetConfig,
   AgentWidgetEvent,
   AgentWidgetMessage,
+  AgentWidgetApproval,
   AgentExecutionState,
   ClientSession,
   ContentPart,
@@ -540,6 +541,125 @@ export class AgentWidgetSession {
     }
   }
 
+  /**
+   * Connect an external SSE stream (e.g. from an approval endpoint) and
+   * process it through the SDK's native event pipeline.
+   */
+  public async connectStream(
+    stream: ReadableStream<Uint8Array>,
+    options?: { assistantMessageId?: string }
+  ): Promise<void> {
+    if (this.streaming) return;
+    this.abortController?.abort();
+    this.setStreaming(true);
+
+    try {
+      await this.client.processStream(
+        stream,
+        this.handleEvent,
+        options?.assistantMessageId
+      );
+    } catch (error) {
+      this.setStatus("error");
+      this.setStreaming(false);
+      this.abortController = null;
+      this.callbacks.onError?.(
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+
+  /**
+   * Resolve a tool approval request (approve or deny).
+   * Updates the approval message status, calls the API (or custom onDecision),
+   * and pipes the response stream through connectStream().
+   */
+  public async resolveApproval(
+    approval: AgentWidgetApproval,
+    decision: 'approved' | 'denied'
+  ): Promise<void> {
+    // 1. Update approval message status immediately for responsive UI
+    const approvalMessageId = `approval-${approval.id}`;
+    const updatedApproval: AgentWidgetApproval = {
+      ...approval,
+      status: decision,
+      resolvedAt: Date.now(),
+    };
+    const updatedMessage: AgentWidgetMessage = {
+      id: approvalMessageId,
+      role: "assistant",
+      content: "",
+      createdAt: new Date().toISOString(),
+      streaming: false,
+      variant: "approval",
+      approval: updatedApproval,
+    };
+    this.upsertMessage(updatedMessage);
+
+    // 2. Call onDecision callback if provided, otherwise use client.resolveApproval()
+    const approvalConfig = this.config.approval;
+    const onDecision = approvalConfig && typeof approvalConfig === 'object' ? approvalConfig.onDecision : undefined;
+
+    try {
+      let response: Response | ReadableStream<Uint8Array> | void;
+
+      if (onDecision) {
+        response = await onDecision(
+          {
+            approvalId: approval.id,
+            executionId: approval.executionId,
+            agentId: approval.agentId,
+            toolName: approval.toolName,
+          },
+          decision
+        );
+      } else {
+        response = await this.client.resolveApproval(
+          {
+            agentId: approval.agentId,
+            executionId: approval.executionId,
+            approvalId: approval.id,
+          },
+          decision
+        );
+      }
+
+      // 3. Pipe through connectStream if we got a response with a body
+      if (response) {
+        let stream: ReadableStream<Uint8Array> | null = null;
+        if (response instanceof Response) {
+          if (!response.ok) {
+            const errorData = await response.json().catch(() => null);
+            throw new Error(
+              errorData?.error ?? `Approval request failed: ${response.status}`
+            );
+          }
+          stream = response.body;
+        } else if (response instanceof ReadableStream) {
+          stream = response;
+        }
+
+        if (stream) {
+          await this.connectStream(stream);
+        } else if (decision === 'denied') {
+          // No stream body for denied — inject a denial message
+          this.appendMessage({
+            id: `denial-${approval.id}`,
+            role: "assistant",
+            content: "Tool execution was denied by user.",
+            createdAt: new Date().toISOString(),
+            streaming: false,
+            sequence: this.nextSequence(),
+          });
+        }
+      }
+    } catch (error) {
+      this.callbacks.onError?.(
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+
   public cancel() {
     this.abortController?.abort();
     this.abortController = null;

package/src/styles/widget.css

@@ -1817,3 +1817,71 @@
 .tvw-feedback-shake {
   animation: tvw-feedback-shake 0.5s ease-in-out;
 }
+
+/* ============================================
+   Tool & Reasoning Bubble Theme Styles
+   ============================================ */
+
+/* Content areas: replace ghost tvw-bg-gray-50 / tvw-border-gray-200 */
+.vanilla-tool-bubble .tvw-border-t,
+.vanilla-reasoning-bubble .tvw-border-t {
+  border-top-color: var(--cw-border, #e5e7eb);
+  background-color: var(--cw-container, #f9fafb);
+}
+
+/* Tool bubble code blocks: replace ghost tvw-bg-white / tvw-border-gray-100 */
+.vanilla-tool-bubble pre {
+  background-color: var(--cw-surface, #ffffff);
+  border-color: var(--cw-border, #f1f5f9);
+}
+
+/* Collapsible header hover (tool + reasoning) */
+.vanilla-tool-bubble button[data-expand-header],
+.vanilla-reasoning-bubble button[data-expand-header] {
+  transition: background-color 0.15s ease;
+}
+.vanilla-tool-bubble button[data-expand-header]:hover,
+.vanilla-reasoning-bubble button[data-expand-header]:hover {
+  background-color: var(--cw-container, #f8fafc);
+}
+
+/* ============================================
+   Approval Bubble Theme Styles
+   ============================================ */
+
+/* Approval bubble defaults (overridden by inline styles when config exists) */
+.vanilla-approval-bubble {
+  background-color: var(--cw-surface, #ffffff);
+  border-color: var(--cw-border, #e5e7eb);
+}
+
+/* Approval status badges — rgba() so they work on any surface */
+.tvw-approval-badge-approved {
+  background-color: rgba(22, 163, 74, 0.12);
+  color: #16a34a;
+}
+.tvw-approval-badge-denied {
+  background-color: rgba(220, 38, 38, 0.12);
+  color: #dc2626;
+}
+.tvw-approval-badge-timeout {
+  background-color: rgba(202, 138, 4, 0.12);
+  color: #ca8a04;
+}
+
+/* Approval button hover/active states */
+.vanilla-approval-bubble [data-approval-action] {
+  transition: opacity 0.15s ease, transform 0.1s ease, background-color 0.15s ease;
+}
+.vanilla-approval-bubble [data-approval-action="approve"]:hover {
+  opacity: 0.85;
+}
+.vanilla-approval-bubble [data-approval-action="approve"]:active {
+  transform: scale(0.97);
+}
+.vanilla-approval-bubble [data-approval-action="deny"]:hover {
+  background-color: rgba(220, 38, 38, 0.08);
+}
+.vanilla-approval-bubble [data-approval-action="deny"]:active {
+  transform: scale(0.97);
+}

package/src/types.ts

@@ -357,6 +357,8 @@ export type AgentWidgetControllerEventMap = {
   "message:copy": AgentWidgetMessage;
   "eventStream:opened": { timestamp: number };
   "eventStream:closed": { timestamp: number };
+  "approval:requested": { approval: AgentWidgetApproval; message: AgentWidgetMessage };
+  "approval:resolved": { approval: AgentWidgetApproval; decision: string };
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -693,6 +695,48 @@ export type AgentWidgetVoiceRecognitionConfig = {
   autoResume?: boolean | "assistant";
 };
 
+/**
+ * Configuration for tool approval bubbles.
+ * Controls styling, labels, and behavior of the approval UI.
+ */
+export type AgentWidgetApprovalConfig = {
+  /** Background color of the approval bubble */
+  backgroundColor?: string;
+  /** Border color of the approval bubble */
+  borderColor?: string;
+  /** Color for the title text */
+  titleColor?: string;
+  /** Color for the description text */
+  descriptionColor?: string;
+  /** Background color for the approve button */
+  approveButtonColor?: string;
+  /** Text color for the approve button */
+  approveButtonTextColor?: string;
+  /** Background color for the deny button */
+  denyButtonColor?: string;
+  /** Text color for the deny button */
+  denyButtonTextColor?: string;
+  /** Background color for the parameters block */
+  parameterBackgroundColor?: string;
+  /** Text color for the parameters block */
+  parameterTextColor?: string;
+  /** Title text displayed above the description */
+  title?: string;
+  /** Label for the approve button */
+  approveLabel?: string;
+  /** Label for the deny button */
+  denyLabel?: string;
+  /**
+   * Custom handler for approval decisions.
+   * Return void to let the SDK auto-resolve via the API,
+   * or return a Response/ReadableStream for custom handling.
+   */
+  onDecision?: (
+    data: { approvalId: string; executionId: string; agentId: string; toolName: string },
+    decision: 'approved' | 'denied'
+  ) => Promise<Response | ReadableStream<Uint8Array> | void>;
+};
+
 export type AgentWidgetToolCallConfig = {
   backgroundColor?: string;
   borderColor?: string;
@@ -1770,6 +1814,13 @@ export type AgentWidgetConfig = {
    */
   colorScheme?: 'auto' | 'light' | 'dark';
   features?: AgentWidgetFeatureFlags;
+  /**
+   * When true, focus the chat input after the panel opens and the open animation completes.
+   * Applies to launcher mode (user click, controller.open(), autoExpand) and inline mode (on init).
+   * Skip when voice is active to avoid stealing focus from voice UI.
+   * @default false
+   */
+  autoFocusInput?: boolean;
   launcher?: AgentWidgetLauncherConfig;
   initialMessages?: AgentWidgetMessage[];
   suggestionChips?: string[];
@@ -1781,6 +1832,23 @@ export type AgentWidgetConfig = {
   statusIndicator?: AgentWidgetStatusIndicatorConfig;
   voiceRecognition?: AgentWidgetVoiceRecognitionConfig;
   toolCall?: AgentWidgetToolCallConfig;
+  /**
+   * Configuration for tool approval bubbles.
+   * Set to `false` to disable built-in approval handling entirely.
+   *
+   * @example
+   * ```typescript
+   * config: {
+   *   approval: {
+   *     title: "Permission Required",
+   *     approveLabel: "Allow",
+   *     denyLabel: "Block",
+   *     approveButtonColor: "#16a34a"
+   *   }
+   * }
+   * ```
+   */
+  approval?: AgentWidgetApprovalConfig | false;
   postprocessMessage?: (context: {
     text: string;
     message: AgentWidgetMessage;
@@ -2129,7 +2197,23 @@ export type AgentWidgetToolCall = {
   durationMs?: number;
 };
 
-export type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool";
+/**
+ * Represents a tool approval request in the chat conversation.
+ * Created when the agent requires human approval before executing a tool.
+ */
+export type AgentWidgetApproval = {
+  id: string;
+  status: "pending" | "approved" | "denied" | "timeout";
+  agentId: string;
+  executionId: string;
+  toolName: string;
+  toolType?: string;
+  description: string;
+  parameters?: unknown;
+  resolvedAt?: number;
+};
+
+export type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
 
 /**
  * Represents a message in the chat conversation.
@@ -2165,6 +2249,8 @@ export type AgentWidgetMessage = {
   reasoning?: AgentWidgetReasoning;
   toolCall?: AgentWidgetToolCall;
   tools?: AgentWidgetToolCall[];
+  /** Approval data for messages with variant "approval" */
+  approval?: AgentWidgetApproval;
   viaVoice?: boolean;
   /**
    * Raw structured payload for this message (e.g., JSON action response).

package/src/ui.ts

@@ -37,6 +37,7 @@ import { MessageTransform, MessageActionCallbacks, LoadingIndicatorRenderer } fr
 import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
+import { createApprovalBubble } from "./components/approval-bubble";
 import { createSuggestions } from "./components/suggestions";
 import { EventStreamBuffer } from "./utils/event-stream-buffer";
 import { EventStreamStore } from "./utils/event-stream-store";
@@ -259,6 +260,14 @@ type Controller = {
   showNPSFeedback: (options?: Partial<NPSFeedbackOptions>) => void;
   submitCSATFeedback: (rating: number, comment?: string) => Promise<void>;
   submitNPSFeedback: (rating: number, comment?: string) => Promise<void>;
+  /**
+   * Connect an external SSE stream and process it through the SDK's
+   * native event pipeline (tools, reasoning, streaming text, etc.).
+   */
+  connectStream: (
+    stream: ReadableStream<Uint8Array>,
+    options?: { assistantMessageId?: string }
+  ) => Promise<void>;
   /** Push a raw event into the event stream buffer (for testing/debugging) */
   __pushEventStreamEvent: (event: { type: string; payload: unknown }) => void;
   /** Opens the event stream panel */
@@ -267,6 +276,17 @@ type Controller = {
   hideEventStream: () => void;
   /** Returns current visibility state of the event stream panel */
   isEventStreamVisible: () => boolean;
+  /**
+   * Focus the chat input. Returns true if focus succeeded, false if panel is closed
+   * (launcher mode) or textarea is unavailable.
+   */
+  focusInput: () => boolean;
+  /**
+   * Programmatically resolve a pending approval.
+   * @param approvalId - The approval ID to resolve
+   * @param decision - "approved" or "denied"
+   */
+  resolveApproval: (approvalId: string, decision: 'approved' | 'denied') => Promise<void>;
 };
 
 const buildPostprocessor = (
@@ -442,6 +462,7 @@ export const createAgentExperience = (
 
   let launcherEnabled = config.launcher?.enabled ?? true;
   let autoExpand = config.launcher?.autoExpand ?? false;
+  const autoFocusInput = config.autoFocusInput ?? false;
   let prevAutoExpand = autoExpand;
   let prevLauncherEnabled = launcherEnabled;
   let prevHeaderLayout = config.layout?.header?.layout;
@@ -959,6 +980,46 @@ export const createAgentExperience = (
     }
   });
 
+  // Add event delegation for approval action buttons (approve/deny)
+  messagesWrapper.addEventListener('click', (event) => {
+    const target = event.target as HTMLElement;
+    const approvalButton = target.closest('button[data-approval-action]') as HTMLElement;
+    if (!approvalButton) return;
+
+    event.preventDefault();
+    event.stopPropagation();
+
+    const approvalBubble = approvalButton.closest('.vanilla-approval-bubble') as HTMLElement;
+    if (!approvalBubble) return;
+
+    const messageId = approvalBubble.getAttribute('data-message-id');
+    if (!messageId) return;
+
+    const action = approvalButton.getAttribute('data-approval-action') as 'approve' | 'deny';
+    if (!action) return;
+
+    const decision = action === 'approve' ? 'approved' as const : 'denied' as const;
+
+    // Find the approval message
+    const messages = session.getMessages();
+    const approvalMessage = messages.find(m => m.id === messageId);
+    if (!approvalMessage?.approval) return;
+
+    // Disable buttons immediately for responsive UI
+    const buttonsContainer = approvalBubble.querySelector('[data-approval-buttons]') as HTMLElement;
+    if (buttonsContainer) {
+      const buttons = buttonsContainer.querySelectorAll('button');
+      buttons.forEach(btn => {
+        (btn as HTMLButtonElement).disabled = true;
+        btn.style.opacity = '0.5';
+        btn.style.cursor = 'not-allowed';
+      });
+    }
+
+    // Resolve the approval
+    session.resolveApproval(approvalMessage.approval, decision);
+  });
+
   panel.appendChild(container);
   mount.appendChild(wrapper);
 
@@ -1414,6 +1475,15 @@ export const createAgentExperience = (
       ) {
         eventBus.emit("assistant:complete", message);
       }
+
+      // Emit approval events
+      if (message.variant === "approval" && message.approval) {
+        if (!previous) {
+          eventBus.emit("approval:requested", { approval: message.approval, message });
+        } else if (message.approval.status !== "pending") {
+          eventBus.emit("approval:resolved", { approval: message.approval, decision: message.approval.status });
+        }
+      }
     });
 
     messageState.clear();
@@ -1462,6 +1532,9 @@ export const createAgentExperience = (
         if (message.variant === "tool" && p.renderToolCall) {
           return true;
         }
+        if (message.variant === "approval" && p.renderApproval) {
+          return true;
+        }
         if (!message.variant && p.renderMessage) {
           return true;
         }
@@ -1486,6 +1559,13 @@ export const createAgentExperience = (
             defaultRenderer: () => createToolBubble(message, config),
             config
           });
+        } else if (message.variant === "approval" && message.approval && matchingPlugin.renderApproval) {
+          if (config.approval === false) return;
+          bubble = matchingPlugin.renderApproval({
+            message,
+            defaultRenderer: () => createApprovalBubble(message, config),
+            config
+          });
         } else if (matchingPlugin.renderMessage) {
           bubble = matchingPlugin.renderMessage({
             message,
@@ -1566,6 +1646,9 @@ export const createAgentExperience = (
         } else if (message.variant === "tool" && message.toolCall) {
           if (!showToolCalls) return;
           bubble = createToolBubble(message, config);
+        } else if (message.variant === "approval" && message.approval) {
+          if (config.approval === false) return;
+          bubble = createApprovalBubble(message, config);
         } else {
           // Check for custom message renderers in layout config
           const messageLayoutConfig = config.layout?.messages;
@@ -1621,8 +1704,10 @@ export const createAgentExperience = (
     
     // Also check if there's a recently completed assistant message (streaming just ended)
     // This prevents flicker when the message completes but isStreaming hasn't updated yet
+    // Approval-variant messages are UI controls, not content — exclude them so the typing
+    // indicator still shows while the agent resumes after approval
     const lastMessage = messages[messages.length - 1];
-    const hasRecentAssistantResponse = lastMessage?.role === "assistant" && !lastMessage.streaming;
+    const hasRecentAssistantResponse = lastMessage?.role === "assistant" && !lastMessage.streaming && lastMessage.variant !== "approval";
 
     if (isStreaming && messages.some((msg) => msg.role === "user") && !hasStreamingAssistantMessage && !hasRecentAssistantResponse) {
       // Get loading indicator using priority chain: plugin -> config -> default
@@ -1843,6 +1928,16 @@ export const createAgentExperience = (
     });
   };
 
+  const maybeFocusInput = () => {
+    if (voiceState.active) return;
+    if (!textarea) return;
+    textarea.focus();
+  };
+
+  eventBus.on("widget:opened", () => {
+    if (config.autoFocusInput) setTimeout(() => maybeFocusInput(), 200);
+  });
+
   const updateCopy = () => {
     introTitle.textContent = config.copy?.welcomeTitle ?? "Hello 👋";
     introSubtitle.textContent =
@@ -2425,6 +2520,14 @@ export const createAgentExperience = (
   scheduleAutoScroll(true);
   maybeRestoreVoiceFromMetadata();
 
+  if (autoFocusInput) {
+    if (!launcherEnabled) {
+      setTimeout(() => maybeFocusInput(), 0);
+    } else if (open) {
+      setTimeout(() => maybeFocusInput(), 200);
+    }
+  }
+
   const recalcPanelHeight = () => {
     const sidebarMode = config.launcher?.sidebarMode ?? false;
     const fullHeight = sidebarMode || (config.launcher?.fullHeight ?? false);
@@ -3950,6 +4053,12 @@ export const createAgentExperience = (
       }
       session.injectTestEvent(event);
     },
+    async connectStream(
+      stream: ReadableStream<Uint8Array>,
+      options?: { assistantMessageId?: string }
+    ): Promise<void> {
+      return session.connectStream(stream, options);
+    },
     /** Push a raw event into the event stream buffer (for testing/debugging) */
     __pushEventStreamEvent(event: { type: string; payload: unknown }): void {
       if (eventStreamBuffer) {
@@ -3972,6 +4081,22 @@ export const createAgentExperience = (
     isEventStreamVisible(): boolean {
       return eventStreamVisible;
     },
+    focusInput(): boolean {
+      if (launcherEnabled && !open) return false;
+      if (!textarea) return false;
+      textarea.focus();
+      return true;
+    },
+    async resolveApproval(approvalId: string, decision: 'approved' | 'denied'): Promise<void> {
+      const messages = session.getMessages();
+      const approvalMessage = messages.find(
+        m => m.variant === "approval" && m.approval?.id === approvalId
+      );
+      if (!approvalMessage?.approval) {
+        throw new Error(`Approval not found: ${approvalId}`);
+      }
+      return session.resolveApproval(approvalMessage.approval, decision);
+    },
     getMessages() {
       return session.getMessages();
     },
@@ -4107,26 +4232,40 @@ export const createAgentExperience = (
   // ============================================================================
   // INSTANCE-SCOPED WINDOW EVENTS FOR PROGRAMMATIC CONTROL
   // ============================================================================
-  if (showEventStreamToggle && typeof window !== "undefined") {
+  if (typeof window !== "undefined") {
     const instanceId = mount.getAttribute("data-persona-instance") || mount.id || "persona-" + Math.random().toString(36).slice(2, 8);
-    const handleShowEvent = (e: Event) => {
-      const detail = (e as CustomEvent).detail;
-      if (!detail?.instanceId || detail.instanceId === instanceId) {
-        controller.showEventStream();
-      }
-    };
-    const handleHideEvent = (e: Event) => {
+
+    const handleFocusInput = (e: Event) => {
       const detail = (e as CustomEvent).detail;
       if (!detail?.instanceId || detail.instanceId === instanceId) {
-        controller.hideEventStream();
+        controller.focusInput();
       }
     };
-    window.addEventListener("persona:showEventStream", handleShowEvent);
-    window.addEventListener("persona:hideEventStream", handleHideEvent);
+    window.addEventListener("persona:focusInput", handleFocusInput);
     destroyCallbacks.push(() => {
-      window.removeEventListener("persona:showEventStream", handleShowEvent);
-      window.removeEventListener("persona:hideEventStream", handleHideEvent);
+      window.removeEventListener("persona:focusInput", handleFocusInput);
     });
+
+    if (showEventStreamToggle) {
+      const handleShowEvent = (e: Event) => {
+        const detail = (e as CustomEvent).detail;
+        if (!detail?.instanceId || detail.instanceId === instanceId) {
+          controller.showEventStream();
+        }
+      };
+      const handleHideEvent = (e: Event) => {
+        const detail = (e as CustomEvent).detail;
+        if (!detail?.instanceId || detail.instanceId === instanceId) {
+          controller.hideEventStream();
+        }
+      };
+      window.addEventListener("persona:showEventStream", handleShowEvent);
+      window.addEventListener("persona:hideEventStream", handleHideEvent);
+      destroyCallbacks.push(() => {
+        window.removeEventListener("persona:showEventStream", handleShowEvent);
+        window.removeEventListener("persona:hideEventStream", handleHideEvent);
+      });
+    }
   }
 
   // ============================================================================