@runtypelabs/persona 3.35.0 → 3.37.0

package/dist/theme-editor.d.cts

@@ -4891,6 +4891,16 @@ type AgentWidgetConfig = {
      * ```
      */
     parseSSEEvent?: AgentWidgetSSEEventParser;
+    /**
+     * Wire vocabulary requested from the dispatch endpoint.
+     * - `'legacy'` (default): the current `agent_*` / `flow_*` SSE events.
+     * - `'unified'`: opt into the API's neutral unified event vocabulary by sending
+     *   `?events=unified`; incoming frames are transparently bridged back to the same
+     *   handlers, so rendering is unchanged. Requires an upstream that honors the
+     *   param — the widget detects the actual wire mode from the first stream frame
+     *   and falls back to legacy automatically if the param was ignored.
+     */
+    events?: "legacy" | "unified";
     /**
      * Called for every parsed SSE frame (after JSON parse), before native handling.
      * Use for lightweight side effects (e.g. telemetry). Does not replace native

package/dist/theme-editor.d.ts

@@ -4891,6 +4891,16 @@ type AgentWidgetConfig = {
      * ```
      */
     parseSSEEvent?: AgentWidgetSSEEventParser;
+    /**
+     * Wire vocabulary requested from the dispatch endpoint.
+     * - `'legacy'` (default): the current `agent_*` / `flow_*` SSE events.
+     * - `'unified'`: opt into the API's neutral unified event vocabulary by sending
+     *   `?events=unified`; incoming frames are transparently bridged back to the same
+     *   handlers, so rendering is unchanged. Requires an upstream that honors the
+     *   param — the widget detects the actual wire mode from the first stream frame
+     *   and falls back to legacy automatically if the param was ignored.
+     */
+    events?: "legacy" | "unified";
     /**
      * Called for every parsed SSE frame (after JSON parse), before native handling.
      * Use for lightweight side effects (e.g. telemetry). Does not replace native

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.35.0",
+  "version": "3.37.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/client.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { AgentWidgetClient, preferFinalStructuredContent } from './client';
 import { AgentWidgetEvent, AgentWidgetMessage } from './types';
 import { createJsonStreamParser } from './utils/formatting';
+import { VERSION } from './version';
 
 describe('AgentWidgetClient - Empty Message Filtering', () => {
   let client: AgentWidgetClient;
@@ -4176,3 +4177,144 @@ describe('AgentWidgetClient - Feedback request builder', () => {
     expect(feedbackBodies[0].rating).toBe(5);
   });
 });
+
+describe('AgentWidgetClient - version header', () => {
+  function captureHeaders() {
+    const headers: Array<Record<string, string>> = [];
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: { headers: Record<string, string> }) => {
+      headers.push(options.headers);
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(c) {
+          c.enqueue(encoder.encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.close();
+        },
+      });
+      return { ok: true, body: stream };
+    });
+    return headers;
+  }
+
+  const msg = () => ({
+    messages: [{ id: 'u1', role: 'user' as const, content: 'hi', createdAt: '2025-01-01T00:00:00.000Z' }],
+  });
+
+  it('broadcasts X-Persona-Version on the dispatch request', async () => {
+    const headers = captureHeaders();
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+
+    await client.dispatch(msg(), () => undefined);
+
+    expect(headers[0]['X-Persona-Version']).toBe(VERSION);
+  });
+
+  it('lets an explicit config header override the version', async () => {
+    const headers = captureHeaders();
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      headers: { 'X-Persona-Version': 'override' },
+    });
+
+    await client.dispatch(msg(), () => undefined);
+
+    expect(headers[0]['X-Persona-Version']).toBe('override');
+  });
+});
+
+describe('AgentWidgetClient - Unified event vocabulary (events: "unified")', () => {
+  const unifiedTextStream = (execId: string) => [
+    sseEvent('execution_start', { kind: 'agent', executionId: execId, agentId: 'virtual', agentName: 'Test', maxTurns: 1, startedAt: new Date().toISOString(), seq: 1 }),
+    sseEvent('turn_start', { executionId: execId, id: 'turn_1', iteration: 1, role: 'assistant', seq: 2 }),
+    sseEvent('text_start', { executionId: execId, id: 'text_1', role: 'assistant', seq: 3 }),
+    sseEvent('text_delta', { executionId: execId, id: 'text_1', delta: 'Hello', seq: 4 }),
+    sseEvent('text_delta', { executionId: execId, id: 'text_1', delta: ' World', seq: 5 }),
+    sseEvent('text_complete', { executionId: execId, id: 'text_1', seq: 6 }),
+    sseEvent('turn_complete', { executionId: execId, id: 'turn_1', iteration: 1, role: 'assistant', completedAt: new Date().toISOString(), seq: 7 }),
+    sseEvent('execution_complete', { kind: 'agent', executionId: execId, success: true, completedAt: new Date().toISOString(), seq: 8 }),
+  ];
+
+  it('appends ?events=unified to the dispatch URL when opted in', async () => {
+    let capturedUrl = '';
+    global.fetch = vi.fn().mockImplementation(async (url: string) => {
+      capturedUrl = url;
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(c) {
+          for (const e of unifiedTextStream('exec_u')) c.enqueue(encoder.encode(e));
+          c.close();
+        },
+      });
+      return { ok: true, body: stream };
+    });
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      events: 'unified',
+      agent: { name: 'Test', model: 'openai:gpt-4o-mini', systemPrompt: 'test' },
+    });
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      () => {}
+    );
+    expect(capturedUrl).toContain('events=unified');
+  });
+
+  it('renders a unified stream by bridging it back to the legacy handlers', async () => {
+    const events: AgentWidgetEvent[] = [];
+    const execId = 'exec_u1';
+    global.fetch = createAgentStreamFetch(unifiedTextStream(execId));
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      events: 'unified',
+      agent: { name: 'Test', model: 'openai:gpt-4o-mini', systemPrompt: 'test' },
+    });
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const messageEvents = events.filter((e) => e.type === 'message');
+    expect(messageEvents.length).toBeGreaterThan(0);
+    const last = messageEvents[messageEvents.length - 1];
+    expect(last.type).toBe('message');
+    if (last.type === 'message') {
+      expect(last.message.content).toBe('Hello World');
+      expect(last.message.streaming).toBe(false);
+      expect(last.message.role).toBe('assistant');
+      expect(last.message.agentMetadata?.executionId).toBe(execId);
+    }
+  });
+
+  it('auto-falls-back to legacy when "unified" was requested but the API streamed legacy frames', async () => {
+    const events: AgentWidgetEvent[] = [];
+    const execId = 'exec_legacy_fallback';
+    // Same content, LEGACY vocabulary — the API ignored ?events=unified.
+    global.fetch = createAgentStreamFetch([
+      sseEvent('agent_start', { executionId: execId, agentId: 'virtual', agentName: 'Test', maxTurns: 1, startedAt: new Date().toISOString(), seq: 1 }),
+      sseEvent('agent_turn_start', { executionId: execId, iteration: 1, turnId: 'turn_1', role: 'assistant', seq: 2 }),
+      sseEvent('agent_turn_delta', { executionId: execId, iteration: 1, delta: 'Hello', contentType: 'text', turnId: 'turn_1', seq: 3 }),
+      sseEvent('agent_turn_delta', { executionId: execId, iteration: 1, delta: ' World', contentType: 'text', turnId: 'turn_1', seq: 4 }),
+      sseEvent('agent_turn_complete', { executionId: execId, iteration: 1, turnId: 'turn_1', completedAt: new Date().toISOString(), seq: 5 }),
+      sseEvent('agent_complete', { executionId: execId, success: true, stopReason: 'max_iterations', completedAt: new Date().toISOString(), seq: 6 }),
+    ]);
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      events: 'unified',
+      agent: { name: 'Test', model: 'openai:gpt-4o-mini', systemPrompt: 'test' },
+    });
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const messageEvents = events.filter((e) => e.type === 'message');
+    const last = messageEvents[messageEvents.length - 1];
+    expect(last.type).toBe('message');
+    if (last.type === 'message') {
+      expect(last.message.content).toBe('Hello World');
+      expect(last.message.streaming).toBe(false);
+    }
+  });
+});

package/src/client.ts

@@ -33,6 +33,8 @@ import {
   createXmlParser
 } from "./utils/formatting";
 import { SequenceReorderBuffer } from "./utils/sequence-buffer";
+import { UnifiedToLegacyBridge, isUnifiedLifecycleStart } from "./utils/unified-event-bridge";
+import { VERSION } from "./version";
 // artifactsSidebarEnabled is used in ui.ts to gate the sidebar pane rendering;
 // artifact events are always processed here regardless of config.
 
@@ -188,6 +190,7 @@ export class AgentWidgetClient {
     this.apiUrl = config.apiUrl ?? DEFAULT_ENDPOINT;
     this.headers = {
       "Content-Type": "application/json",
+      "X-Persona-Version": VERSION,
       ...config.headers
     };
     this.debug = Boolean(config.debug);
@@ -290,6 +293,17 @@ export class AgentWidgetClient {
     return !!this.config.agent;
   }
 
+  /**
+   * Append `?events=unified` when the widget opted into the unified vocabulary,
+   * preserving any existing query string. No-op for the default legacy mode.
+   * The server only switches vocabularies when it sees the param; the widget
+   * still auto-detects the actual wire mode from the first stream frame.
+   */
+  private withEventsParam(url: string): string {
+    if (this.config.events !== "unified") return url;
+    return url + (url.includes("?") ? "&" : "?") + "events=unified";
+  }
+
   /**
    * Get the appropriate API URL based on mode
    */
@@ -355,6 +369,7 @@ export class AgentWidgetClient {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
+        'X-Persona-Version': VERSION,
       },
       body: JSON.stringify(requestBody),
     });
@@ -495,6 +510,7 @@ export class AgentWidgetClient {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
+        'X-Persona-Version': VERSION,
       },
       body: JSON.stringify(requestBody),
     });
@@ -678,10 +694,11 @@ export class AgentWidgetClient {
           console.debug("[AgentWidgetClient] client token dispatch", chatRequest);
         }
 
-        response = await fetch(this.getClientApiUrl('chat'), {
+        response = await fetch(this.withEventsParam(this.getClientApiUrl('chat')), {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
+            'X-Persona-Version': VERSION,
           },
           body: JSON.stringify(chatRequest),
           signal: controller.signal,
@@ -797,7 +814,7 @@ export class AgentWidgetClient {
     if (this.customFetch) {
       try {
         response = await this.customFetch(
-          this.apiUrl,
+          this.withEventsParam(this.apiUrl),
           {
             method: "POST",
             headers,
@@ -812,7 +829,7 @@ export class AgentWidgetClient {
         throw err;
       }
     } else {
-      response = await fetch(this.apiUrl, {
+      response = await fetch(this.withEventsParam(this.apiUrl), {
         method: "POST",
         headers,
         body: JSON.stringify(payload),
@@ -873,7 +890,7 @@ export class AgentWidgetClient {
     if (this.customFetch) {
       try {
         response = await this.customFetch(
-          this.apiUrl,
+          this.withEventsParam(this.apiUrl),
           {
             method: "POST",
             headers,
@@ -888,7 +905,7 @@ export class AgentWidgetClient {
         throw err;
       }
     } else {
-      response = await fetch(this.apiUrl, {
+      response = await fetch(this.withEventsParam(this.apiUrl), {
         method: "POST",
         headers,
         body: JSON.stringify(payload),
@@ -991,9 +1008,11 @@ export class AgentWidgetClient {
     options?: { streamResponse?: boolean; signal?: AbortSignal }
   ): Promise<Response> {
     const isClientToken = this.isClientTokenMode();
-    const url = isClientToken
-      ? this.getClientApiUrl('resume')
-      : `${this.config.apiUrl?.replace(/\/+$/, '') || DEFAULT_CLIENT_API_BASE}/resume`;
+    const url = this.withEventsParam(
+      isClientToken
+        ? this.getClientApiUrl('resume')
+        : `${this.config.apiUrl?.replace(/\/+$/, '') || DEFAULT_CLIENT_API_BASE}/resume`
+    );
 
     // The client-token resume route authenticates the session, not a Bearer
     // key. A WebMCP approval can sit awaiting user input for a long time, so by
@@ -1828,6 +1847,17 @@ export class AgentWidgetClient {
       seqReadyQueue.push({ payloadType, payload });
       scheduleReadyQueueDrain();
     });
+    // Unified-event consumer (opt-in; see utils/unified-event-bridge.ts). When the
+    // API streams the neutral unified vocabulary, each frame is transduced back to
+    // the legacy events the dispatch chain below already renders. Seed the mode from
+    // the requested vocabulary so /resume (whose stream continues mid-run with no
+    // `execution_start`) bridges correctly; a leading lifecycle frame is then
+    // authoritative and can flip it (e.g. an upstream that ignored `?events=unified`
+    // streams `agent_start`). The unified stream is single-connection and in order,
+    // so bridged events bypass the reorder buffer.
+    const unifiedBridge = new UnifiedToLegacyBridge();
+    let unifiedMode = this.config.events === "unified";
+    let wireModeResolved = false;
     // Agent execution state tracking
     let agentExecution: AgentExecutionState | null = null;
     // Track assistant messages per agent iteration for 'separate' mode
@@ -3368,6 +3398,31 @@ export class AgentWidgetClient {
           if (handled) continue; // Skip default handling if custom handler processed it
         }
 
+        // Unified vocabulary (opt-in): resolve the wire mode from the first
+        // lifecycle frame (the flag only requests the param; the frame is
+        // authoritative), then transduce unified → legacy, bypassing the reorder
+        // buffer (the unified stream is single-connection and already in order).
+        if (!wireModeResolved) {
+          if (isUnifiedLifecycleStart(payloadType)) {
+            unifiedMode = true;
+            wireModeResolved = true;
+          } else if (
+            payloadType === "agent_start" ||
+            payloadType === "flow_start" ||
+            payloadType === "step_start"
+          ) {
+            unifiedMode = false;
+            wireModeResolved = true;
+          }
+        }
+        if (unifiedMode) {
+          for (const legacyEvent of unifiedBridge.push(payloadType, payload)) {
+            seqReadyQueue.push(legacyEvent);
+          }
+          drainReadyQueue();
+          continue;
+        }
+
         // Push through the sequence reorder buffer
         seqBuffer.push(payloadType, payload);
         drainReadyQueue();

package/src/generated/runtype-openapi-contract.ts

@@ -1190,6 +1190,7 @@ export type RuntypeClientChatRequest = {
   type: "object";
   [key: string]: unknown;
 };
+  untrustedContentHint?: boolean;
 }>;
   clientToolsFingerprint?: string;
   inputs?: Record<string, unknown>;

package/src/install.ts

@@ -18,6 +18,9 @@ interface SiteAgentInstallConfig {
   clientToken?: string;
   flowId?: string;
   apiUrl?: string;
+  /** Wire vocabulary requested from the dispatch endpoint; 'unified' opts into the
+   *  API's neutral event schema (transparently bridged back to the same rendering). */
+  events?: "legacy" | "unified";
   // Optional query param key that gates widget installation in preview mode
   previewQueryParam?: string;
   // Shadow DOM option (defaults to false for better CSS compatibility)
@@ -377,6 +380,7 @@ declare global {
     if (config.apiUrl && !widgetConfig.apiUrl) widgetConfig.apiUrl = config.apiUrl;
     if (config.clientToken && !widgetConfig.clientToken) widgetConfig.clientToken = config.clientToken;
     if (config.flowId && !widgetConfig.flowId) widgetConfig.flowId = config.flowId;
+    if (config.events && !widgetConfig.events) widgetConfig.events = config.events;
 
     const hasApiConfig = !!(widgetConfig.apiUrl || widgetConfig.clientToken);
     return { target, widgetConfig, hasApiConfig };

package/src/types.ts

@@ -4056,6 +4056,16 @@ export type AgentWidgetConfig = {
    * ```
    */
   parseSSEEvent?: AgentWidgetSSEEventParser;
+  /**
+   * Wire vocabulary requested from the dispatch endpoint.
+   * - `'legacy'` (default): the current `agent_*` / `flow_*` SSE events.
+   * - `'unified'`: opt into the API's neutral unified event vocabulary by sending
+   *   `?events=unified`; incoming frames are transparently bridged back to the same
+   *   handlers, so rendering is unchanged. Requires an upstream that honors the
+   *   param — the widget detects the actual wire mode from the first stream frame
+   *   and falls back to legacy automatically if the param was ignored.
+   */
+  events?: "legacy" | "unified";
   /**
    * Called for every parsed SSE frame (after JSON parse), before native handling.
    * Use for lightweight side effects (e.g. telemetry). Does not replace native