@runtypelabs/persona 1.41.0 → 1.43.0

package/src/types.ts

@@ -73,6 +73,91 @@ export type AgentWidgetRequestPayload = {
   metadata?: Record<string, unknown>;
 };
 
+// ============================================================================
+// Agent Execution Types
+// ============================================================================
+
+/**
+ * Configuration for agent loop behavior.
+ */
+export type AgentLoopConfig = {
+  /** Maximum number of reasoning iterations */
+  maxIterations: number;
+  /** Stop condition: 'auto' for automatic detection, or a custom JS expression */
+  stopCondition?: 'auto' | string;
+  /** Enable periodic reflection during execution */
+  enableReflection?: boolean;
+  /** Number of iterations between reflections */
+  reflectionInterval?: number;
+};
+
+/**
+ * Agent configuration for agent execution mode.
+ * When provided in the widget config, enables agent loop execution instead of flow dispatch.
+ */
+export type AgentConfig = {
+  /** Agent display name */
+  name: string;
+  /** Model identifier (e.g., 'openai:gpt-4o-mini') */
+  model: string;
+  /** System prompt for the agent */
+  systemPrompt: string;
+  /** Temperature for model responses */
+  temperature?: number;
+  /** Loop configuration for multi-iteration execution */
+  loopConfig?: AgentLoopConfig;
+};
+
+/**
+ * Options for agent execution requests.
+ */
+export type AgentRequestOptions = {
+  /** Whether to stream the response (should be true for widget usage) */
+  streamResponse?: boolean;
+  /** Record mode: 'virtual' for no persistence, 'existing'/'create' for database records */
+  recordMode?: 'virtual' | 'existing' | 'create';
+  /** Whether to store results server-side */
+  storeResults?: boolean;
+  /** Enable debug mode for additional event data */
+  debugMode?: boolean;
+};
+
+/**
+ * Request payload for agent execution mode.
+ */
+export type AgentWidgetAgentRequestPayload = {
+  agent: AgentConfig;
+  messages: AgentWidgetRequestPayloadMessage[];
+  options: AgentRequestOptions;
+  context?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * Agent execution state tracking.
+ */
+export type AgentExecutionState = {
+  executionId: string;
+  agentId: string;
+  agentName: string;
+  status: 'running' | 'complete' | 'error';
+  currentIteration: number;
+  maxIterations: number;
+  startedAt?: number;
+  completedAt?: number;
+  stopReason?: 'max_iterations' | 'complete' | 'error' | 'manual';
+};
+
+/**
+ * Metadata attached to messages created during agent execution.
+ */
+export type AgentMessageMetadata = {
+  executionId?: string;
+  iteration?: number;
+  turnId?: string;
+  agentName?: string;
+};
+
 export type AgentWidgetRequestMiddlewareContext = {
   payload: AgentWidgetRequestPayload;
   config: AgentWidgetConfig;
@@ -270,11 +355,138 @@ export type AgentWidgetControllerEventMap = {
   "widget:state": AgentWidgetStateSnapshot;
   "message:feedback": AgentWidgetMessageFeedback;
   "message:copy": AgentWidgetMessage;
+  "eventStream:opened": { timestamp: number };
+  "eventStream:closed": { timestamp: number };
 };
 
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
+  showEventStreamToggle?: boolean;
+  /** Configuration for the Event Stream inspector view */
+  eventStream?: EventStreamConfig;
+};
+
+export type SSEEventRecord = {
+  id: string;
+  type: string;
+  timestamp: number;
+  payload: string;
+};
+
+// ============================================================================
+// Event Stream Configuration Types
+// ============================================================================
+
+/**
+ * Badge color configuration for event stream event types.
+ */
+export type EventStreamBadgeColor = {
+  /** Background color (CSS value) */
+  bg: string;
+  /** Text color (CSS value) */
+  text: string;
+};
+
+/**
+ * Configuration for the Event Stream inspector view.
+ */
+export type EventStreamConfig = {
+  /**
+   * Custom badge color mappings by event type prefix or exact type.
+   * Keys are matched as exact match first, then prefix match (keys ending with "_").
+   * @example { "flow_": { bg: "#dcfce7", text: "#166534" }, "error": { bg: "#fecaca", text: "#991b1b" } }
+   */
+  badgeColors?: Record<string, EventStreamBadgeColor>;
+  /**
+   * Timestamp display format.
+   * - "relative": Shows time offset from first event (+0.000s, +0.361s)
+   * - "absolute": Shows wall-clock time (HH:MM:SS.mmm)
+   * @default "relative"
+   */
+  timestampFormat?: "absolute" | "relative";
+  /**
+   * Whether to show sequential event numbers (1, 2, 3...).
+   * @default true
+   */
+  showSequenceNumbers?: boolean;
+  /**
+   * Maximum events to keep in the ring buffer.
+   * @default 500
+   */
+  maxEvents?: number;
+  /**
+   * Fields to extract from event payloads for description text.
+   * The first matching field value is displayed after the badge.
+   * @default ["flowName", "stepName", "name", "tool", "toolName"]
+   */
+  descriptionFields?: string[];
+  /**
+   * Custom CSS class names to append to event stream UI elements.
+   * Each value is a space-separated class string appended to the element's default classes.
+   */
+  classNames?: {
+    /** The toggle button in the widget header (activity icon). */
+    toggleButton?: string;
+    /** Additional classes applied to the toggle button when the event stream is open. */
+    toggleButtonActive?: string;
+    /** The outer event stream panel/container. */
+    panel?: string;
+    /** The toolbar header bar (title, filter, copy all). */
+    headerBar?: string;
+    /** The search bar wrapper. */
+    searchBar?: string;
+    /** The search text input. */
+    searchInput?: string;
+    /** Each event row wrapper. */
+    eventRow?: string;
+    /** The "new events" scroll indicator pill. */
+    scrollIndicator?: string;
+  };
+};
+
+/**
+ * Context for the renderEventStreamView plugin hook.
+ */
+export type EventStreamViewRenderContext = {
+  config: AgentWidgetConfig;
+  events: SSEEventRecord[];
+  defaultRenderer: () => HTMLElement;
+  onClose?: () => void;
+};
+
+/**
+ * Context for the renderEventStreamRow plugin hook.
+ */
+export type EventStreamRowRenderContext = {
+  event: SSEEventRecord;
+  index: number;
+  config: AgentWidgetConfig;
+  defaultRenderer: () => HTMLElement;
+  isExpanded: boolean;
+  onToggleExpand: () => void;
+};
+
+/**
+ * Context for the renderEventStreamToolbar plugin hook.
+ */
+export type EventStreamToolbarRenderContext = {
+  config: AgentWidgetConfig;
+  defaultRenderer: () => HTMLElement;
+  eventCount: number;
+  filteredCount: number;
+  onFilterChange: (type: string) => void;
+  onSearchChange: (term: string) => void;
+};
+
+/**
+ * Context for the renderEventStreamPayload plugin hook.
+ */
+export type EventStreamPayloadRenderContext = {
+  event: SSEEventRecord;
+  config: AgentWidgetConfig;
+  defaultRenderer: () => HTMLElement;
+  parsedPayload: unknown;
 };
 
 export type AgentWidgetTheme = {
@@ -1399,6 +1611,41 @@ export type AgentWidgetLoadingIndicatorConfig = {
 export type AgentWidgetConfig = {
   apiUrl?: string;
   flowId?: string;
+  /**
+   * Agent configuration for agent execution mode.
+   * When provided, the widget uses agent loop execution instead of flow dispatch.
+   * Mutually exclusive with `flowId`.
+   *
+   * @example
+   * ```typescript
+   * config: {
+   *   agent: {
+   *     name: 'Assistant',
+   *     model: 'openai:gpt-4o-mini',
+   *     systemPrompt: 'You are a helpful assistant.',
+   *     loopConfig: { maxIterations: 3, stopCondition: 'auto' }
+   *   }
+   * }
+   * ```
+   */
+  agent?: AgentConfig;
+  /**
+   * Options for agent execution requests.
+   * Only used when `agent` is configured.
+   *
+   * @default { streamResponse: true, recordMode: 'virtual' }
+   */
+  agentOptions?: AgentRequestOptions;
+  /**
+   * Controls how multiple agent iterations are displayed in the chat UI.
+   * Only used when `agent` is configured.
+   *
+   * - `'separate'`: Each iteration creates a new assistant message bubble
+   * - `'merged'`: All iterations stream into a single assistant message
+   *
+   * @default 'separate'
+   */
+  iterationDisplay?: 'separate' | 'merged';
   /**
    * Client token for direct browser-to-API communication.
    * When set, the widget uses /v1/client/* endpoints instead of /v1/dispatch.
@@ -1944,6 +2191,11 @@ export type AgentWidgetMessage = {
    * }
    */
   llmContent?: string;
+  /**
+   * Metadata for messages created during agent loop execution.
+   * Contains execution context like iteration number and turn ID.
+   */
+  agentMetadata?: AgentMessageMetadata;
 };
 
 // ============================================================================

package/src/ui.ts

@@ -38,6 +38,9 @@ import { createStandardBubble, createTypingIndicator } from "./components/messag
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
 import { createSuggestions } from "./components/suggestions";
+import { EventStreamBuffer } from "./utils/event-stream-buffer";
+import { EventStreamStore } from "./utils/event-stream-store";
+import { createEventStreamView } from "./components/event-stream-view";
 import { enhanceWithForms } from "./components/forms";
 import { pluginRegistry } from "./plugins/registry";
 import { mergeWithDefaults } from "./defaults";
@@ -172,6 +175,10 @@ type Controller = {
    * Convenience method for injecting system messages.
    */
   injectSystemMessage: (options: InjectSystemMessageOptions) => AgentWidgetMessage;
+  /**
+   * Inject multiple messages in a single batch with one sort and one render pass.
+   */
+  injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
   /**
    * @deprecated Use injectMessage() instead.
    */
@@ -199,6 +206,14 @@ type Controller = {
   showNPSFeedback: (options?: Partial<NPSFeedbackOptions>) => void;
   submitCSATFeedback: (rating: number, comment?: string) => Promise<void>;
   submitNPSFeedback: (rating: number, comment?: 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 */
+  showEventStream: () => void;
+  /** Closes the event stream panel */
+  hideEventStream: () => void;
+  /** Returns current visibility state of the event stream panel */
+  isEventStreamVisible: () => boolean;
 };
 
 const buildPostprocessor = (
@@ -260,10 +275,12 @@ export const createAgentExperience = (
   initialConfig?: AgentWidgetConfig,
   runtimeOptions?: { debugTools?: boolean }
 ): Controller => {
-  // Tailwind config uses important: "#persona-root", so ensure mount has this ID
-  if (!mount.id || mount.id !== "persona-root") {
-    mount.id = "persona-root";
+  // Preserve original mount id as data attribute for window event instance scoping,
+  // then set mount.id to "persona-root" (required by Tailwind important: "#persona-root")
+  if (mount.id && mount.id !== "persona-root" && !mount.getAttribute("data-persona-instance")) {
+    mount.setAttribute("data-persona-instance", mount.id);
   }
+  mount.id = "persona-root";
 
   let config = mergeWithDefaults(initialConfig) as AgentWidgetConfig;
   // Note: applyThemeVariables is called after applyFullHeightStyles() below
@@ -404,7 +421,24 @@ export const createAgentExperience = (
   let postprocess = buildPostprocessor(config, actionManager, handleResubmitRequested);
   let showReasoning = config.features?.showReasoning ?? true;
   let showToolCalls = config.features?.showToolCalls ?? true;
-  
+  let showEventStreamToggle = config.features?.showEventStreamToggle ?? false;
+  const persistKeyPrefix = (typeof config.persistState === 'object' ? config.persistState?.keyPrefix : undefined) ?? "persona-";
+  const eventStreamDbName = `${persistKeyPrefix}event-stream`;
+  let eventStreamStore = showEventStreamToggle ? new EventStreamStore(eventStreamDbName) : null;
+  const eventStreamMaxEvents = config.features?.eventStream?.maxEvents ?? 2000;
+  let eventStreamBuffer = showEventStreamToggle ? new EventStreamBuffer(eventStreamMaxEvents, eventStreamStore) : null;
+  let eventStreamView: ReturnType<typeof createEventStreamView> | null = null;
+  let eventStreamVisible = false;
+  let eventStreamRAF: number | null = null;
+  let eventStreamLastUpdate = 0;
+
+  // Open IndexedDB store and restore persisted events into the buffer
+  eventStreamStore?.open().then(() => {
+    return eventStreamBuffer?.restore();
+  }).catch(err => {
+    if (config.debug) console.warn('[AgentWidget] IndexedDB not available for event stream:', err);
+  });
+
   // Create message action callbacks that emit events and optionally send to API
   const messageActionCallbacks: MessageActionCallbacks = {
     onCopy: (message: AgentWidgetMessage) => {
@@ -519,6 +553,101 @@ export const createAgentExperience = (
     }
   }
 
+  // Event stream toggle functions (lifted to outer scope for controller access)
+  const toggleEventStreamOn = () => {
+    if (!eventStreamBuffer) return;
+    eventStreamVisible = true;
+    if (!eventStreamView && eventStreamBuffer) {
+      eventStreamView = createEventStreamView({
+        buffer: eventStreamBuffer,
+        getFullHistory: () => eventStreamBuffer!.getAllFromStore(),
+        onClose: () => toggleEventStreamOff(),
+        config,
+        plugins,
+      });
+    }
+    if (eventStreamView) {
+      body.style.display = "none";
+      footer.parentNode?.insertBefore(eventStreamView.element, footer);
+      eventStreamView.update();
+    }
+    if (eventStreamToggleBtn) {
+      eventStreamToggleBtn.classList.remove("tvw-text-cw-muted");
+      eventStreamToggleBtn.classList.add("tvw-text-cw-accent");
+      eventStreamToggleBtn.style.boxShadow = "inset 0 0 0 1.5px var(--cw-accent, #3b82f6)";
+      const activeClasses = config.features?.eventStream?.classNames?.toggleButtonActive;
+      if (activeClasses) activeClasses.split(/\s+/).forEach(c => c && eventStreamToggleBtn!.classList.add(c));
+    }
+    // Start RAF-based update loop (throttled to ~200ms)
+    const rafLoop = () => {
+      if (!eventStreamVisible) return;
+      const now = Date.now();
+      if (now - eventStreamLastUpdate >= 200) {
+        eventStreamView?.update();
+        eventStreamLastUpdate = now;
+      }
+      eventStreamRAF = requestAnimationFrame(rafLoop);
+    };
+    eventStreamLastUpdate = 0;
+    eventStreamRAF = requestAnimationFrame(rafLoop);
+    eventBus.emit("eventStream:opened", { timestamp: Date.now() });
+  };
+
+  const toggleEventStreamOff = () => {
+    if (!eventStreamVisible) return;
+    eventStreamVisible = false;
+    if (eventStreamView) {
+      eventStreamView.element.remove();
+    }
+    body.style.display = "";
+    if (eventStreamToggleBtn) {
+      eventStreamToggleBtn.classList.remove("tvw-text-cw-accent");
+      eventStreamToggleBtn.classList.add("tvw-text-cw-muted");
+      eventStreamToggleBtn.style.boxShadow = "";
+      const activeClasses = config.features?.eventStream?.classNames?.toggleButtonActive;
+      if (activeClasses) activeClasses.split(/\s+/).forEach(c => c && eventStreamToggleBtn!.classList.remove(c));
+    }
+    // Cancel RAF update loop
+    if (eventStreamRAF !== null) {
+      cancelAnimationFrame(eventStreamRAF);
+      eventStreamRAF = null;
+    }
+    eventBus.emit("eventStream:closed", { timestamp: Date.now() });
+  };
+
+  // Event stream toggle button
+  let eventStreamToggleBtn: HTMLButtonElement | null = null;
+  if (showEventStreamToggle) {
+    const esClassNames = config.features?.eventStream?.classNames;
+    const toggleBtnClasses = "tvw-inline-flex tvw-items-center tvw-justify-center tvw-rounded-full tvw-text-cw-muted hover:tvw-bg-gray-100 tvw-cursor-pointer tvw-border-none tvw-bg-transparent tvw-p-1" + (esClassNames?.toggleButton ? " " + esClassNames.toggleButton : "");
+    eventStreamToggleBtn = createElement("button", toggleBtnClasses) as HTMLButtonElement;
+    eventStreamToggleBtn.style.width = "28px";
+    eventStreamToggleBtn.style.height = "28px";
+    eventStreamToggleBtn.type = "button";
+    eventStreamToggleBtn.setAttribute("aria-label", "Event Stream");
+    eventStreamToggleBtn.title = "Event Stream";
+    const activityIcon = renderLucideIcon("activity", "18px", "currentColor", 1.5);
+    if (activityIcon) eventStreamToggleBtn.appendChild(activityIcon);
+
+    // Insert before clear chat button wrapper or close button wrapper
+    const clearChatWrapper = panelElements.clearChatButtonWrapper;
+    const closeWrapper = panelElements.closeButtonWrapper;
+    const insertBefore = clearChatWrapper || closeWrapper;
+    if (insertBefore && insertBefore.parentNode === header) {
+      header.insertBefore(eventStreamToggleBtn, insertBefore);
+    } else {
+      header.appendChild(eventStreamToggleBtn);
+    }
+
+    eventStreamToggleBtn.addEventListener("click", () => {
+      if (eventStreamVisible) {
+        toggleEventStreamOff();
+      } else {
+        toggleEventStreamOn();
+      }
+    });
+  }
+
   // Plugin hook: renderComposer - allow plugins to provide custom composer
   const composerPlugin = plugins.find(p => p.renderComposer);
   if (composerPlugin?.renderComposer) {
@@ -887,6 +1016,21 @@ export const createAgentExperience = (
 
   const destroyCallbacks: Array<() => void> = [];
 
+  // Event stream cleanup
+  if (showEventStreamToggle) {
+    destroyCallbacks.push(() => {
+      if (eventStreamRAF !== null) {
+        cancelAnimationFrame(eventStreamRAF);
+        eventStreamRAF = null;
+      }
+      eventStreamView?.destroy();
+      eventStreamView = null;
+      eventStreamBuffer?.destroy();
+      eventStreamBuffer = null;
+      eventStreamStore = null;
+    });
+  }
+
   // Set up theme observer for auto color scheme detection
   let cleanupThemeObserver: (() => void) | null = null;
   const setupThemeObserver = () => {
@@ -1670,6 +1814,18 @@ export const createAgentExperience = (
     }
   });
 
+  // Wire up event stream buffer to capture SSE events
+  if (eventStreamBuffer) {
+    session.setSSEEventCallback((type: string, payload: unknown) => {
+      eventStreamBuffer?.push({
+        id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        type,
+        timestamp: Date.now(),
+        payload: JSON.stringify(payload)
+      });
+    });
+  }
+
   if (pendingStoredState) {
     pendingStoredState
       .then((state) => {
@@ -2254,6 +2410,10 @@ export const createAgentExperience = (
       }
       persistentMetadata = {};
       actionManager.syncFromMetadata();
+
+      // Clear event stream buffer and store
+      eventStreamBuffer?.clear();
+      eventStreamView?.update();
     });
   };
 
@@ -2304,6 +2464,66 @@ export const createAgentExperience = (
       autoExpand = config.launcher?.autoExpand ?? false;
       showReasoning = config.features?.showReasoning ?? true;
       showToolCalls = config.features?.showToolCalls ?? true;
+      const prevShowEventStreamToggle = showEventStreamToggle;
+      showEventStreamToggle = config.features?.showEventStreamToggle ?? false;
+
+      // Handle dynamic event stream feature flag toggling
+      if (showEventStreamToggle && !prevShowEventStreamToggle) {
+        // Flag changed from false to true - create buffer/store if needed
+        if (!eventStreamBuffer) {
+          eventStreamStore = new EventStreamStore(eventStreamDbName);
+          eventStreamBuffer = new EventStreamBuffer(eventStreamMaxEvents, eventStreamStore);
+          eventStreamStore.open().then(() => eventStreamBuffer?.restore()).catch(() => {});
+          // Register the SSE event callback
+          session.setSSEEventCallback((type: string, payload: unknown) => {
+            eventStreamBuffer!.push({
+              id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+              type,
+              timestamp: Date.now(),
+              payload: JSON.stringify(payload)
+            });
+          });
+        }
+        // Add header toggle button if not present
+        if (!eventStreamToggleBtn && header) {
+          const dynEsClassNames = config.features?.eventStream?.classNames;
+          const dynToggleBtnClasses = "tvw-inline-flex tvw-items-center tvw-justify-center tvw-rounded-full tvw-text-cw-muted hover:tvw-bg-gray-100 tvw-cursor-pointer tvw-border-none tvw-bg-transparent tvw-p-1" + (dynEsClassNames?.toggleButton ? " " + dynEsClassNames.toggleButton : "");
+          eventStreamToggleBtn = createElement("button", dynToggleBtnClasses) as HTMLButtonElement;
+          eventStreamToggleBtn.style.width = "28px";
+          eventStreamToggleBtn.style.height = "28px";
+          eventStreamToggleBtn.type = "button";
+          eventStreamToggleBtn.setAttribute("aria-label", "Event Stream");
+          eventStreamToggleBtn.title = "Event Stream";
+          const activityIcon = renderLucideIcon("activity", "18px", "currentColor", 1.5);
+          if (activityIcon) eventStreamToggleBtn.appendChild(activityIcon);
+          const clearChatWrapper = panelElements.clearChatButtonWrapper;
+          const closeWrapper = panelElements.closeButtonWrapper;
+          const insertBefore = clearChatWrapper || closeWrapper;
+          if (insertBefore && insertBefore.parentNode === header) {
+            header.insertBefore(eventStreamToggleBtn, insertBefore);
+          } else {
+            header.appendChild(eventStreamToggleBtn);
+          }
+          eventStreamToggleBtn.addEventListener("click", () => {
+            if (eventStreamVisible) {
+              toggleEventStreamOff();
+            } else {
+              toggleEventStreamOn();
+            }
+          });
+        }
+      } else if (!showEventStreamToggle && prevShowEventStreamToggle) {
+        // Flag changed from true to false - hide and clean up
+        toggleEventStreamOff();
+        if (eventStreamToggleBtn) {
+          eventStreamToggleBtn.remove();
+          eventStreamToggleBtn = null;
+        }
+        eventStreamBuffer?.clear();
+        eventStreamStore?.destroy();
+        eventStreamBuffer = null;
+        eventStreamStore = null;
+      }
 
       if (config.launcher?.enabled === false && launcherButtonInstance) {
         launcherButtonInstance.destroy();
@@ -3450,6 +3670,10 @@ export const createAgentExperience = (
       }
       persistentMetadata = {};
       actionManager.syncFromMetadata();
+
+      // Clear event stream buffer and store
+      eventStreamBuffer?.clear();
+      eventStreamView?.update();
     },
     setMessage(message: string): boolean {
       if (!textarea) return false;
@@ -3552,6 +3776,12 @@ export const createAgentExperience = (
       }
       return session.injectSystemMessage(options);
     },
+    injectMessageBatch(optionsList: InjectMessageOptions[]): AgentWidgetMessage[] {
+      if (!open && launcherEnabled) {
+        setOpenState(true, "system");
+      }
+      return session.injectMessageBatch(optionsList);
+    },
     /** @deprecated Use injectMessage() instead */
     injectTestMessage(event: AgentWidgetEvent) {
       // Auto-open widget if closed and launcher is enabled
@@ -3560,6 +3790,28 @@ export const createAgentExperience = (
       }
       session.injectTestEvent(event);
     },
+    /** Push a raw event into the event stream buffer (for testing/debugging) */
+    __pushEventStreamEvent(event: { type: string; payload: unknown }): void {
+      if (eventStreamBuffer) {
+        eventStreamBuffer.push({
+          id: `evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+          type: event.type,
+          timestamp: Date.now(),
+          payload: JSON.stringify(event.payload)
+        });
+      }
+    },
+    showEventStream(): void {
+      if (!showEventStreamToggle || !eventStreamBuffer) return;
+      toggleEventStreamOn();
+    },
+    hideEventStream(): void {
+      if (!eventStreamVisible) return;
+      toggleEventStreamOff();
+    },
+    isEventStreamVisible(): boolean {
+      return eventStreamVisible;
+    },
     getMessages() {
       return session.getMessages();
     },
@@ -3692,6 +3944,31 @@ export const createAgentExperience = (
     });
   }
 
+  // ============================================================================
+  // INSTANCE-SCOPED WINDOW EVENTS FOR PROGRAMMATIC CONTROL
+  // ============================================================================
+  if (showEventStreamToggle && 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 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);
+    });
+  }
+
   // ============================================================================
   // STATE PERSISTENCE ACROSS PAGE NAVIGATIONS
   // ============================================================================