@runtypelabs/persona 3.21.3 → 3.23.0

package/src/components/event-stream-view.ts

@@ -7,6 +7,7 @@ import {
   resolveFollowStateFromWheel
 } from "../utils/auto-follow";
 import type { EventStreamBuffer } from "../utils/event-stream-buffer";
+import type { ThroughputMetric } from "../utils/throughput-tracker";
 import type {
   SSEEventRecord,
   AgentWidgetConfig,
@@ -151,6 +152,36 @@ function formatEventForCopy(event: SSEEventRecord): string {
   );
 }
 
+// ============================================================================
+// Output Throughput Summary
+// ============================================================================
+
+/** Format the headline value, e.g. `23.9 tok/s` or `-- tok/s` when unavailable. */
+function formatThroughputValue(metric: ThroughputMetric): string {
+  if (
+    metric.tokensPerSecond === undefined ||
+    !Number.isFinite(metric.tokensPerSecond)
+  ) {
+    return "-- tok/s";
+  }
+  return `${metric.tokensPerSecond.toFixed(1)} tok/s`;
+}
+
+/** Compact supporting details: output tokens, duration, and usage/estimate source. */
+function formatThroughputMeta(metric: ThroughputMetric): string {
+  const parts: string[] = [];
+  if (metric.outputTokens !== undefined) {
+    parts.push(`${metric.outputTokens.toLocaleString()} tok`);
+  }
+  if (metric.durationMs !== undefined) {
+    parts.push(`${(metric.durationMs / 1000).toFixed(2)}s`);
+  }
+  if (metric.source) {
+    parts.push(metric.source);
+  }
+  return parts.join(" · ");
+}
+
 // ============================================================================
 // Inline Payload Component
 // ============================================================================
@@ -381,6 +412,12 @@ export type EventStreamViewOptions = {
   onClose?: () => void;
   config?: AgentWidgetConfig;
   plugins?: AgentWidgetPlugin[];
+  /**
+   * Optional accessor for the current output-throughput metric, derived from
+   * the same SSE event stream. When provided, a compact "Output throughput"
+   * summary row is rendered and refreshed on each update.
+   */
+  getThroughput?: () => ThroughputMetric;
 };
 
 export function createEventStreamView(
@@ -396,6 +433,7 @@ export function createEventStreamView(
     onClose,
     config,
     plugins = [],
+    getThroughput,
   } = options;
   const scrollToBottomConfig = config?.features?.scrollToBottom;
   const scrollToBottomEnabled = scrollToBottomConfig?.enabled !== false;
@@ -474,11 +512,17 @@ export function createEventStreamView(
     let copyAllBtn!: HTMLButtonElement;
     let searchInput!: HTMLInputElement;
     let searchClearBtn!: HTMLButtonElement;
+    // Inline "Throughput <tok/s>" group, rendered into the header bar next to
+    // the "Events" count when getThroughput is provided. The detailed
+    // breakdown is revealed on hover via the native title tooltip.
+    let throughputValueEl: HTMLElement | null = null;
+    let throughputContainer: HTMLElement | null = null;
+    let throughputTooltipEl: HTMLElement | null = null;
 
     function buildDefaultToolbar(): HTMLElement {
       const toolbarOuter = createElement(
         "div",
-        "persona-flex persona-flex-col persona-flex-shrink-0"
+        "persona-relative persona-flex persona-flex-col persona-flex-shrink-0"
       );
 
       // --- Header bar ---
@@ -502,6 +546,58 @@ export function createEventStreamView(
       );
       countBadge.textContent = "0";
 
+      // Inline throughput group: "Throughput  146.3 tok/s", grouped with the
+      // Events count. Hover reveals tokens · duration · source via a custom
+      // tooltip (shown instantly, unlike the slow native `title` delay).
+      if (getThroughput) {
+        throughputContainer = createElement(
+          "div",
+          "persona-relative persona-flex persona-items-center persona-gap-1.5 persona-whitespace-nowrap persona-ml-1"
+        );
+        throughputContainer.style.cursor = "help";
+        // Label styled to match the "Events" title.
+        const throughputLabel = createElement(
+          "span",
+          "persona-text-sm persona-font-medium persona-text-persona-primary persona-whitespace-nowrap"
+        );
+        throughputLabel.textContent = "Throughput";
+        // Same bounding box + styling as the Events count badge.
+        throughputValueEl = createElement(
+          "span",
+          "persona-text-[11px] persona-font-mono persona-bg-persona-container persona-text-persona-muted persona-px-2 persona-py-0.5 persona-rounded persona-border persona-border-persona-border persona-tabular-nums"
+        );
+        throughputValueEl.textContent = "-- tok/s";
+
+        // Custom hover tooltip — appears instantly (no native title delay).
+        // Appended to the (non-clipping) toolbar wrapper rather than the header
+        // bar, which has overflow-hidden and would clip a dropdown. Position is
+        // measured on hover so it sits just under the throughput group.
+        throughputTooltipEl = createElement(
+          "div",
+          "persona-absolute persona-z-50 persona-whitespace-nowrap persona-rounded persona-border persona-border-persona-border persona-bg-persona-container persona-text-persona-primary persona-text-[11px] persona-font-mono persona-px-2 persona-py-1 persona-shadow"
+        );
+        throughputTooltipEl.style.display = "none";
+        throughputTooltipEl.style.pointerEvents = "none";
+        const group = throughputContainer;
+        const tooltip = throughputTooltipEl;
+        const showTooltip = () => {
+          if (!tooltip.textContent) return;
+          const gRect = group.getBoundingClientRect();
+          const pRect = toolbarOuter.getBoundingClientRect();
+          tooltip.style.left = `${gRect.left - pRect.left}px`;
+          tooltip.style.top = `${gRect.bottom - pRect.top + 4}px`;
+          tooltip.style.display = "block";
+        };
+        const hideTooltip = () => {
+          tooltip.style.display = "none";
+        };
+        throughputContainer.addEventListener("mouseenter", showTooltip);
+        throughputContainer.addEventListener("mouseleave", hideTooltip);
+
+        throughputContainer.appendChild(throughputLabel);
+        throughputContainer.appendChild(throughputValueEl);
+      }
+
       const headerSpacer = createElement("div", "persona-flex-1");
 
       // Filter dropdown
@@ -540,6 +636,7 @@ export function createEventStreamView(
 
       headerBar.appendChild(title);
       headerBar.appendChild(countBadge);
+      if (throughputContainer) headerBar.appendChild(throughputContainer);
       headerBar.appendChild(headerSpacer);
       headerBar.appendChild(filterSelect);
       headerBar.appendChild(copyAllBtn);
@@ -592,6 +689,7 @@ export function createEventStreamView(
 
       toolbarOuter.appendChild(headerBar);
       toolbarOuter.appendChild(searchBar);
+      if (throughputTooltipEl) toolbarOuter.appendChild(throughputTooltipEl);
       return toolbarOuter;
     }
 
@@ -630,6 +728,28 @@ export function createEventStreamView(
     );
     truncationBanner.style.display = "none";
 
+    // Refresh the inline header throughput value + hover tooltip. The elements
+    // live in the header bar (built by buildDefaultToolbar); this is a no-op
+    // when getThroughput is absent or a plugin replaced the toolbar.
+    function updateThroughputSummary(): void {
+      if (!getThroughput || !throughputValueEl || !throughputContainer) return;
+      const metric = getThroughput();
+      throughputValueEl.textContent = formatThroughputValue(metric);
+      // Detailed breakdown is revealed on hover via the custom tooltip; mirror
+      // it into aria-label for assistive tech. When there's nothing to show,
+      // hide the tooltip so an empty box never flashes on hover.
+      const meta = formatThroughputMeta(metric);
+      if (throughputTooltipEl) {
+        throughputTooltipEl.textContent = meta;
+        if (!meta) throughputTooltipEl.style.display = "none";
+      }
+      if (meta) {
+        throughputContainer.setAttribute("aria-label", meta);
+      } else {
+        throughputContainer.removeAttribute("aria-label");
+      }
+    }
+
     // ========================================================================
     // Events List (simple DOM, no virtual scroller)
     // ========================================================================
@@ -804,6 +924,7 @@ export function createEventStreamView(
       lastRenderTime = Date.now();
       pendingUpdate = false;
 
+      updateThroughputSummary();
       updateFilterOptions();
 
       // Truncation banner

package/src/index.ts

@@ -20,6 +20,9 @@ export type {
   AgentWidgetStreamParser,
   AgentWidgetStreamParserResult,
   AgentWidgetRequestPayload,
+  // Context provider types (e.g. for config.contextProviders)
+  AgentWidgetContextProvider,
+  AgentWidgetContextProviderContext,
   AgentWidgetCustomFetch,
   AgentWidgetSSEEventParser,
   AgentWidgetSSEEventResult,
@@ -78,6 +81,12 @@ export type {
   // Approval types
   AgentWidgetApproval,
   AgentWidgetApprovalConfig,
+  // WebMCP — page-discovered tool consumption
+  AgentWidgetWebMcpConfig,
+  ClientToolDefinition,
+  WebMcpConfirmHandler,
+  WebMcpConfirmInfo,
+  WebMcpToolResult,
   // Event stream types
   SSEEventRecord,
   EventStreamConfig,
@@ -121,6 +130,12 @@ export {
 } from "./session";
 export { AgentWidgetClient } from "./client";
 export type { SSEEventCallback } from "./client";
+export {
+  WebMcpBridge,
+  WEBMCP_TOOL_PREFIX,
+  isWebMcpToolName,
+  stripWebMcpPrefix
+} from "./webmcp-bridge";
 export { createLocalStorageAdapter } from "./utils/storage";
 export {
   createActionManager,
@@ -212,6 +227,17 @@ export type {
   AgentWidgetStreamAnimationPlaceholder,
 } from "./types";
 
+// Action system types — needed to type the `actionHandlers` / `actionParsers`
+// config options and to author custom handlers/parsers.
+export type {
+  AgentWidgetActionHandler,
+  AgentWidgetActionHandlerResult,
+  AgentWidgetActionParser,
+  AgentWidgetParsedAction,
+  AgentWidgetActionContext,
+  AgentWidgetActionEventPayload,
+} from "./types";
+
 // Dropdown utility exports
 export { createDropdownMenu } from "./utils/dropdown";
 export type { DropdownMenuItem, CreateDropdownOptions, DropdownMenuHandle } from "./utils/dropdown";

package/src/session.test.ts

@@ -794,3 +794,261 @@ describe('AgentWidgetSession.resolveApproval', () => {
     expect(errors.length).toBe(1);
   });
 });
+
+describe('AgentWidgetSession - dispatch error fallback', () => {
+  const originalFetch = global.fetch;
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  // Make fetch reject so client.dispatch throws and the session falls back.
+  const failFetchWith = (error: Error) => {
+    global.fetch = vi.fn().mockRejectedValue(error);
+  };
+
+  const lastAssistantMessage = (
+    session: AgentWidgetSession
+  ): AgentWidgetMessage | undefined =>
+    [...session.getMessages()].reverse().find((m) => m.role === 'assistant');
+
+  it('shows the default message with the underlying error detail and fires onError', async () => {
+    failFetchWith(new Error('Failed to fetch'));
+    const errors: Error[] = [];
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onError: (e) => errors.push(e),
+      }
+    );
+
+    await session.sendMessage('Hello');
+
+    const assistant = lastAssistantMessage(session);
+    expect(assistant?.content).toContain("I couldn't reach the assistant");
+    expect(assistant?.content).toContain('_Details: Failed to fetch_');
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toBe('Failed to fetch');
+    expect(session.isStreaming()).toBe(false);
+    expect(session.getStatus()).toBe('idle');
+  });
+
+  it('uses a static errorMessage override verbatim', async () => {
+    failFetchWith(new Error('boom'));
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://example.invalid/chat',
+        errorMessage: 'We are having trouble connecting.',
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    await session.sendMessage('Hello');
+
+    const assistant = lastAssistantMessage(session);
+    expect(assistant?.content).toBe('We are having trouble connecting.');
+    expect(assistant?.content).not.toContain('Details');
+  });
+
+  it('passes the error to a function errorMessage override', async () => {
+    failFetchWith(new Error('Failed to fetch'));
+    const seen: Error[] = [];
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://example.invalid/chat',
+        errorMessage: (error) => {
+          seen.push(error);
+          return error.message.includes('Failed to fetch')
+            ? 'You appear to be offline.'
+            : 'Something went wrong.';
+        },
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    await session.sendMessage('Hello');
+
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toBeInstanceOf(Error);
+    expect(lastAssistantMessage(session)?.content).toBe(
+      'You appear to be offline.'
+    );
+  });
+
+  it('suppresses the fallback bubble when the override returns an empty string but still fires onError', async () => {
+    failFetchWith(new Error('boom'));
+    const errors: Error[] = [];
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://example.invalid/chat',
+        errorMessage: () => '',
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onError: (e) => errors.push(e),
+      }
+    );
+
+    await session.sendMessage('Hello');
+
+    expect(lastAssistantMessage(session)).toBeUndefined();
+    expect(errors).toHaveLength(1);
+    expect(session.isStreaming()).toBe(false);
+    expect(session.getStatus()).toBe('idle');
+  });
+
+  it('does NOT show a fallback bubble when the dispatch is aborted', async () => {
+    const abortErr = new Error('The operation was aborted');
+    abortErr.name = 'AbortError';
+    failFetchWith(abortErr);
+    const errors: Error[] = [];
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onError: (e) => errors.push(e),
+      }
+    );
+
+    await session.sendMessage('Hello');
+
+    expect(lastAssistantMessage(session)).toBeUndefined();
+    expect(errors).toHaveLength(0);
+  });
+
+  it('applies the override on continueConversation failures too', async () => {
+    failFetchWith(new Error('boom'));
+    const session = new AgentWidgetSession(
+      {
+        apiUrl: 'http://example.invalid/chat',
+        errorMessage: 'Custom continue error.',
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+
+    await session.continueConversation();
+
+    expect(lastAssistantMessage(session)?.content).toBe('Custom continue error.');
+  });
+});
+
+describe('AgentWidgetSession - WebMCP native approval gate', () => {
+  const makeSession = (
+    webmcp?: Record<string, unknown>
+  ): { session: AgentWidgetSession; getMessages: () => AgentWidgetMessage[] } => {
+    let messages: AgentWidgetMessage[] = [];
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://localhost:8000', webmcp: { enabled: true, ...webmcp } },
+      {
+        onMessagesChanged: (msgs) => { messages = msgs; },
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+      }
+    );
+    return { session, getMessages: () => messages };
+  };
+
+  it('renders a pending approval bubble and resolves true on approve', async () => {
+    const { session, getMessages } = makeSession();
+    const promise = session.requestWebMcpApproval({
+      toolName: 'add_to_cart',
+      args: { sku: 'SHOE-001' },
+      reason: 'gate',
+    });
+
+    const bubble = getMessages().find((m) => m.variant === 'approval');
+    expect(bubble).toBeDefined();
+    expect(bubble?.approval?.status).toBe('pending');
+    expect(bubble?.approval?.toolType).toBe('webmcp');
+    expect(bubble?.approval?.toolName).toBe('add_to_cart');
+    expect(bubble?.approval?.parameters).toEqual({ sku: 'SHOE-001' });
+
+    session.resolveWebMcpApproval(bubble!.id, 'approved');
+    await expect(promise).resolves.toBe(true);
+
+    const resolved = getMessages().find((m) => m.variant === 'approval');
+    expect(resolved?.approval?.status).toBe('approved');
+    expect(resolved?.approval?.resolvedAt).toBeDefined();
+  });
+
+  it('resolves false on deny and marks the bubble denied', async () => {
+    const { session, getMessages } = makeSession();
+    const promise = session.requestWebMcpApproval({
+      toolName: 'add_to_cart',
+      args: { sku: 'SHOE-002' },
+      reason: 'gate',
+    });
+    const bubble = getMessages().find((m) => m.variant === 'approval');
+
+    session.resolveWebMcpApproval(bubble!.id, 'denied');
+    await expect(promise).resolves.toBe(false);
+    expect(
+      getMessages().find((m) => m.variant === 'approval')?.approval?.status
+    ).toBe('denied');
+  });
+
+  it('auto-approves (no bubble) when autoApprove returns true', async () => {
+    const { session, getMessages } = makeSession({
+      autoApprove: (info: { toolName: string }) => info.toolName !== 'add_to_cart',
+    });
+
+    await expect(
+      session.requestWebMcpApproval({
+        toolName: 'search_products',
+        args: { query: 'shoes' },
+        reason: 'gate',
+      })
+    ).resolves.toBe(true);
+    // No approval bubble for an auto-approved (read-only) call.
+    expect(getMessages().some((m) => m.variant === 'approval')).toBe(false);
+  });
+
+  it('still gates a mutating tool when autoApprove excludes it', () => {
+    const { session, getMessages } = makeSession({
+      autoApprove: (info: { toolName: string }) => info.toolName !== 'add_to_cart',
+    });
+    void session.requestWebMcpApproval({
+      toolName: 'add_to_cart',
+      args: { sku: 'SHOE-001' },
+      reason: 'gate',
+    });
+    expect(getMessages().some((m) => m.variant === 'approval')).toBe(true);
+  });
+
+  it('treats a second resolve as a no-op', async () => {
+    const { session, getMessages } = makeSession();
+    const promise = session.requestWebMcpApproval({
+      toolName: 'add_to_cart',
+      args: {},
+      reason: 'gate',
+    });
+    const bubble = getMessages().find((m) => m.variant === 'approval');
+    session.resolveWebMcpApproval(bubble!.id, 'approved');
+    // Second call must not throw or flip the resolved status.
+    expect(() => session.resolveWebMcpApproval(bubble!.id, 'denied')).not.toThrow();
+    await expect(promise).resolves.toBe(true);
+    expect(
+      getMessages().find((m) => m.variant === 'approval')?.approval?.status
+    ).toBe('approved');
+  });
+});