@runtypelabs/persona 4.2.1 → 4.3.1

package/src/install.ts

@@ -17,6 +17,7 @@ interface SiteAgentInstallConfig {
   // Client token mode options (can also be set via data attributes)
   clientToken?: string;
   flowId?: string;
+  agentId?: string;
   apiUrl?: string;
   // Optional query param key that gates widget installation in preview mode
   previewQueryParam?: string;
@@ -69,7 +70,7 @@ declare global {
 
   /**
    * Read configuration from data attributes on the current script tag.
-   * Supports: data-config (JSON), data-runtype-token, data-flow-id, data-api-url
+   * Supports: data-config (JSON), data-runtype-token, data-flow-id, data-agent-id, data-api-url
    */
   const getConfigFromScript = (): Partial<SiteAgentInstallConfig> => {
     // Try to get the current script element
@@ -112,6 +113,12 @@ declare global {
       scriptConfig.flowId = flowId;
     }
 
+    // Optional agent ID
+    const agentId = script.getAttribute('data-agent-id');
+    if (agentId) {
+      scriptConfig.agentId = agentId;
+    }
+
     // Optional API URL override
     const apiUrl = script.getAttribute('data-api-url');
     if (apiUrl) {
@@ -357,6 +364,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.agentId && !widgetConfig.agentId) widgetConfig.agentId = config.agentId;
 
     const hasApiConfig = !!(widgetConfig.apiUrl || widgetConfig.clientToken);
     return { target, widgetConfig, hasApiConfig };

package/src/session.ts

@@ -70,6 +70,9 @@ const CONNECTION_CONFIG_KEYS = [
   "apiUrl",
   "clientToken",
   "flowId",
+  "agentId",
+  "target",
+  "targetProviders",
   "agent",
   "agentOptions",
   "headers",
@@ -286,7 +289,7 @@ export class AgentWidgetSession {
     // clientToken) falls back to the browser voice, so the fetch would be wasted.
     const host = tts.host ?? this.config.apiUrl;
     const agentId =
-      tts.agentId ?? this.config.voiceRecognition?.provider?.runtype?.agentId;
+      tts.agentId ?? this.config.voiceRecognition?.provider?.runtype?.agentId ?? this.config.agentId;
     if (!host || !agentId || !this.config.clientToken) return;
     void loadRuntypeTts().catch(() => {});
   }
@@ -415,7 +418,7 @@ export class AgentWidgetSession {
     if (tts?.provider === "runtype") {
       const host = tts.host ?? this.config.apiUrl;
       const agentId =
-        tts.agentId ?? this.config.voiceRecognition?.provider?.runtype?.agentId;
+        tts.agentId ?? this.config.voiceRecognition?.provider?.runtype?.agentId ?? this.config.agentId;
       const clientToken = this.config.clientToken;
       const wantFallback = tts.browserFallback !== false;
 
@@ -659,7 +662,7 @@ export class AgentWidgetSession {
         return {
           type: 'runtype',
           runtype: {
-            agentId: providerConfig.runtype?.agentId || '',
+            agentId: providerConfig.runtype?.agentId ?? this.config.agentId ?? '',
             // Default credentials/endpoint from the widget config so the minimum
             // voice config collapses to just `agentId`.
             clientToken: providerConfig.runtype?.clientToken ?? this.config.clientToken,

package/src/session.voice.test.ts

@@ -49,6 +49,7 @@ vi.mock('./voice', async (importOriginal) => {
 });
 
 import { AgentWidgetSession } from './session';
+import { setRuntypeTtsLoader } from './voice/runtype-tts-loader';
 
 describe('AgentWidgetSession - realtime voice onTranscript (Option B)', () => {
   let session: AgentWidgetSession;
@@ -144,3 +145,67 @@ describe('AgentWidgetSession - realtime voice onTranscript (Option B)', () => {
     expect(metricsSeen).toEqual([{ llmMs: 100, totalMs: 250 }]);
   });
 });
+
+describe('AgentWidgetSession - Runtype TTS config', () => {
+  it('uses top-level agentId as the default Runtype TTS agent', async () => {
+    let capturedOptions: { agentId?: string; clientToken?: string; host?: string } | null = null;
+
+    class FakeRuntypeSpeechEngine {
+      readonly id = 'runtype';
+      readonly supportsPause = false;
+
+      constructor(options: { agentId?: string; clientToken?: string; host?: string }) {
+        capturedOptions = options;
+      }
+
+      speak() {}
+      pause() {}
+      resume() {}
+      stop() {}
+    }
+
+    class FakeFallbackSpeechEngine {}
+
+    setRuntypeTtsLoader(async () => ({
+      RuntypeSpeechEngine: FakeRuntypeSpeechEngine as any,
+      FallbackSpeechEngine: FakeFallbackSpeechEngine as any,
+    }));
+
+    try {
+      const session = new AgentWidgetSession(
+        {
+          apiUrl: 'https://api.runtype.com',
+          clientToken: 'ct_live_demo',
+          agentId: 'agent_top_level',
+          textToSpeech: { enabled: true, provider: 'runtype', browserFallback: false },
+          initialMessages: [
+            {
+              id: 'assistant-1',
+              role: 'assistant',
+              content: 'Read this',
+              createdAt: new Date().toISOString(),
+            },
+          ],
+        },
+        {
+          onMessagesChanged: () => {},
+          onStatusChanged: () => {},
+          onStreamingChanged: () => {},
+          onError: () => {},
+        },
+      );
+
+      session.toggleReadAloud('assistant-1');
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(capturedOptions).toMatchObject({
+        agentId: 'agent_top_level',
+        clientToken: 'ct_live_demo',
+        host: 'https://api.runtype.com',
+      });
+    } finally {
+      setRuntypeTtsLoader(null);
+    }
+  });
+});

package/src/styles/widget.css

@@ -1745,6 +1745,9 @@
 /* Make message bubble position relative for overlay positioning */
 .persona-message-bubble {
   position: relative;
+  /* Break long unbreakable tokens (e.g. URLs, package names) so they wrap
+     inside the bubble's max-width instead of overflowing horizontally. */
+  overflow-wrap: break-word;
 }
 
 /* Fade-in animation for action buttons */

package/src/types.ts

@@ -5,6 +5,9 @@ import type {
   RuntypeClientFeedbackRequest,
   RuntypeStopReasonKind,
 } from "./generated/runtype-openapi-contract";
+import type { TargetResolver } from "./utils/target";
+
+export type { TargetResolver, ResolvedTarget } from "./utils/target";
 
 // ============================================================================
 // Multi-Modal Content Types
@@ -100,6 +103,7 @@ export type AgentWidgetRequestPayloadMessage = {
 export type AgentWidgetRequestPayload = {
   messages: AgentWidgetRequestPayloadMessage[];
   flowId?: string;
+  agent?: { agentId: string };
   context?: Record<string, unknown>;
   metadata?: Record<string, unknown>;
   /** Per-turn template variables for /v1/client/chat (merged as root-level {{var}} in Runtype). */
@@ -212,6 +216,11 @@ export type AgentConfig = {
   loopConfig?: AgentLoopConfig;
 };
 
+export type SavedAgentConfig = {
+  /** Persisted Runtype agent ID to execute. */
+  agentId: string;
+};
+
 /**
  * Options for agent execution requests.
  */
@@ -230,7 +239,7 @@ export type AgentRequestOptions = {
  * Request payload for agent execution mode.
  */
 export type AgentWidgetAgentRequestPayload = {
-  agent: AgentConfig;
+  agent: AgentConfig | SavedAgentConfig;
   messages: AgentWidgetRequestPayloadMessage[];
   options: AgentRequestOptions;
   context?: Record<string, unknown>;
@@ -3573,6 +3582,52 @@ export type AgentWidgetLoadingIndicatorConfig = {
 export type AgentWidgetConfig = {
   apiUrl?: string;
   flowId?: string;
+  /**
+   * Persisted Runtype agent ID to execute.
+   *
+   * This is the primary Runtype entry point for simple agent-backed widgets.
+   * It is mutually exclusive with `flowId` and with inline `agent` configs.
+   * Voice and Runtype TTS providers inherit this value unless they specify their
+   * own feature-scoped agent ID.
+   */
+  agentId?: string;
+  /**
+   * Normalized, backend-neutral routing target. A single string that selects
+   * the backend resource to talk to, optimized for portability across
+   * frameworks (it is always serializable: no live objects).
+   *
+   * Shapes:
+   * - Runtype TypeID (no prefix): `"agent_…"` / `"flow_…"` route to the
+   *   Runtype agent/flow paths (the prefix is self-describing).
+   * - Provider-prefixed: `"<provider>:<id>"` is resolved by
+   *   `targetProviders[provider]` (e.g. `"eve:support"`). `"runtype:…"` is a
+   *   built-in that re-detects a TypeID.
+   * - Bare name: `"support"` requires a `targetProviders.default` resolver.
+   *
+   * Mutually exclusive with `agentId`, `flowId`, and inline `agent`. Prefer
+   * `target` for backend-agnostic apps; use `agentId`/`flowId` for the explicit
+   * Runtype path.
+   *
+   * @example
+   * ```typescript
+   * config: { target: "agent_01k..." }            // Runtype agent
+   * config: { target: "flow_01k..." }             // Runtype flow
+   * config: {                                       // custom backend
+   *   apiUrl: "/api/chat",
+   *   target: "eve:support",
+   *   targetProviders: { eve: (id) => ({ payload: { assistant: id } }) },
+   * }
+   * ```
+   */
+  target?: string;
+  /**
+   * Prefix-keyed resolvers for `target` strings of the form
+   * `"<provider>:<id>"`. Each resolver maps the id to the dispatch-payload
+   * fragment its backend expects. Register a `default` resolver to also accept
+   * bare (unprefixed, non-TypeID) target names. The built-in `runtype` provider
+   * is always available and does not need to be registered.
+   */
+  targetProviders?: Record<string, TargetResolver>;
   /**
    * Override the assistant-bubble copy shown when a dispatch fails before any
    * response streams back (connection refused, CORS, 4xx/5xx, malformed
@@ -4265,7 +4320,7 @@ export type AgentWidgetReasoning = {
   status: "pending" | "streaming" | "complete";
   chunks: string[];
   /**
-   * Reasoning channel scope (unified spec). `"turn"` is ordinary per-turn
+   * Reasoning channel scope (wire spec). `"turn"` is ordinary per-turn
    * thinking; `"loop"` is a cross-iteration agent reflection (the fold that
    * replaced the legacy `agent_reflection` event). Absent for legacy streams.
    */

package/src/utils/__fixtures__/unified-translator.oracle.ts

@@ -1,9 +1,9 @@
 /**
  * TEST ORACLE — vendored copy of the runtype-core `createUnifiedEventWrite`
- * translator (the api-side legacy → unified 33-event encoder).
+ * translator (the api-side legacy → wire 33-event encoder).
  *
- * NOT shipped. Used only by `unified-event-bridge.test.ts` as the inverse
- * reference: `legacy frames → THIS oracle → unified frames → UnifiedToLegacyBridge
+ * NOT shipped. Used only by legacy-wire handler tests as the inverse
+ * reference: `legacy frames → THIS oracle → wire frames → client handlers
  * → legacy frames'` must be semantically equal to the original. Keeping a real
  * copy here means the round-trip test fails loudly if the api mapping and the
  * widget bridge ever drift.

package/src/utils/code-generators.ts

@@ -605,6 +605,8 @@ function generateESMCode(config: any, options?: CodeGeneratorOptions): string {
 
   if (config.apiUrl) lines.push(`    apiUrl: "${config.apiUrl}",`);
   if (config.clientToken) lines.push(`    clientToken: "${config.clientToken}",`);
+  if (config.agentId) lines.push(`    agentId: "${config.agentId}",`);
+  if (config.target) lines.push(`    target: "${config.target}",`);
   if (config.flowId) lines.push(`    flowId: "${config.flowId}",`);
   if (shouldEmitParserType) lines.push(`    parserType: "${parserType}",`);
 
@@ -751,6 +753,8 @@ function generateReactComponentCode(config: any, options?: CodeGeneratorOptions)
 
   if (config.apiUrl) lines.push(`        apiUrl: "${config.apiUrl}",`);
   if (config.clientToken) lines.push(`        clientToken: "${config.clientToken}",`);
+  if (config.agentId) lines.push(`        agentId: "${config.agentId}",`);
+  if (config.target) lines.push(`        target: "${config.target}",`);
   if (config.flowId) lines.push(`        flowId: "${config.flowId}",`);
   if (shouldEmitParserType) lines.push(`        parserType: "${parserType}",`);
 
@@ -1015,6 +1019,8 @@ function generateReactAdvancedCode(config: any, options?: CodeGeneratorOptions):
 
   if (config.apiUrl) lines.push(`        apiUrl: "${config.apiUrl}",`);
   if (config.clientToken) lines.push(`        clientToken: "${config.clientToken}",`);
+  if (config.agentId) lines.push(`        agentId: "${config.agentId}",`);
+  if (config.target) lines.push(`        target: "${config.target}",`);
   if (config.flowId) lines.push(`        flowId: "${config.flowId}",`);
 
   if (config.theme && typeof config.theme === "object" && Object.keys(config.theme).length > 0) {
@@ -1270,6 +1276,8 @@ function buildSerializableConfig(config: any): Record<string, any> {
   
   if (config.apiUrl) serializableConfig.apiUrl = config.apiUrl;
   if (config.clientToken) serializableConfig.clientToken = config.clientToken;
+  if (config.agentId) serializableConfig.agentId = config.agentId;
+  if (config.target) serializableConfig.target = config.target;
   if (config.flowId) serializableConfig.flowId = config.flowId;
   if (shouldEmitParserType) serializableConfig.parserType = parserType;
   if (config.theme) serializableConfig.theme = config.theme;
@@ -1419,6 +1427,8 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
 
   if (config.apiUrl) lines.push(`      apiUrl: "${config.apiUrl}",`);
   if (config.clientToken) lines.push(`      clientToken: "${config.clientToken}",`);
+  if (config.agentId) lines.push(`      agentId: "${config.agentId}",`);
+  if (config.target) lines.push(`      target: "${config.target}",`);
   if (config.flowId) lines.push(`      flowId: "${config.flowId}",`);
   if (shouldEmitParserType) lines.push(`      parserType: "${parserType}",`);
 

package/src/utils/target.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { resolveTarget } from "./target";
+
+describe("resolveTarget", () => {
+  it("resolves a Runtype agent TypeID to agentId routing", () => {
+    expect(resolveTarget("agent_01k")).toEqual({
+      kind: "agentId",
+      agentId: "agent_01k",
+    });
+  });
+
+  it("resolves a Runtype flow TypeID to flowId routing", () => {
+    expect(resolveTarget("flow_01k")).toEqual({
+      kind: "flowId",
+      flowId: "flow_01k",
+    });
+  });
+
+  it("accepts an explicit runtype: prefix on a TypeID", () => {
+    expect(resolveTarget("runtype:agent_01k")).toEqual({
+      kind: "agentId",
+      agentId: "agent_01k",
+    });
+  });
+
+  it("routes a provider-prefixed target through its registered resolver", () => {
+    const resolved = resolveTarget("eve:support", {
+      eve: (id) => ({ payload: { assistant: id } }),
+    });
+    expect(resolved).toEqual({ kind: "payload", payload: { assistant: "support" } });
+  });
+
+  it("uses a default resolver for a bare name when registered", () => {
+    const resolved = resolveTarget("support", {
+      default: (id) => ({ payload: { target: id } }),
+    });
+    expect(resolved).toEqual({ kind: "payload", payload: { target: "support" } });
+  });
+
+  it("throws for an unknown provider prefix", () => {
+    expect(() => resolveTarget("eve:support")).toThrow(/no target provider/i);
+  });
+
+  it("throws for a bare name with no TypeID and no default resolver", () => {
+    expect(() => resolveTarget("support")).toThrow(/support/);
+  });
+
+  it("throws for an empty target", () => {
+    expect(() => resolveTarget("   ")).toThrow(/empty/i);
+  });
+});

package/src/utils/target.ts

@@ -0,0 +1,90 @@
+/**
+ * Target resolution for the normalized, backend-neutral `target` field.
+ *
+ * `target` is a single string that selects which backend resource a widget
+ * talks to, optimized for a browser widget (always serializable, no live
+ * objects). Three shapes are supported:
+ *
+ *   - Runtype TypeID (no prefix): `"agent_…"` / `"flow_…"` route to the
+ *     Runtype agent/flow paths. The TypeID prefix is self-describing, so no
+ *     wrapper is needed for the common case.
+ *   - Provider-prefixed: `"<provider>:<id>"` is handed to the matching
+ *     `targetProviders[provider]` resolver, which returns the dispatch payload
+ *     fragment for that backend (e.g. `eve`, `langgraph`). `"runtype:…"` is a
+ *     built-in that re-detects a TypeID.
+ *   - Bare name: `"support"` requires a `targetProviders.default` resolver,
+ *     otherwise it throws (a bare name is ambiguous without one).
+ *
+ * Resolvers are registered, not passed as the value, which keeps `target`
+ * itself a plain string that survives script-tag installs, `data-config`,
+ * persisted state, and codegen.
+ */
+
+/** Resolver for a provider-prefixed (or default) target id. */
+export type TargetResolver = (id: string) => { payload: Record<string, unknown> };
+
+/** Normalized routing produced from a `target` string. */
+export type ResolvedTarget =
+  | { kind: "agentId"; agentId: string }
+  | { kind: "flowId"; flowId: string }
+  | { kind: "payload"; payload: Record<string, unknown> };
+
+const RUNTYPE_AGENT_PREFIX = "agent_";
+const RUNTYPE_FLOW_PREFIX = "flow_";
+
+function detectRuntypeTypeId(id: string): ResolvedTarget | null {
+  if (id.startsWith(RUNTYPE_AGENT_PREFIX)) return { kind: "agentId", agentId: id };
+  if (id.startsWith(RUNTYPE_FLOW_PREFIX)) return { kind: "flowId", flowId: id };
+  return null;
+}
+
+/**
+ * Resolve a `target` string into normalized routing. Pure and synchronous so
+ * it can run on the dispatch hot path and be unit-tested in isolation.
+ */
+export function resolveTarget(
+  target: string,
+  targetProviders?: Record<string, TargetResolver>,
+): ResolvedTarget {
+  const trimmed = target.trim();
+  if (!trimmed) {
+    throw new Error("[Persona] `target` is empty.");
+  }
+
+  const colon = trimmed.indexOf(":");
+  if (colon > 0) {
+    const prefix = trimmed.slice(0, colon);
+    const rest = trimmed.slice(colon + 1);
+
+    // Built-in: an explicit `runtype:` prefix wrapping a TypeID.
+    if (prefix === "runtype") {
+      const detected = detectRuntypeTypeId(rest);
+      if (detected) return detected;
+      throw new Error(
+        `[Persona] target "runtype:${rest}" is not a valid Runtype agent_/flow_ id.`,
+      );
+    }
+
+    const resolver = targetProviders?.[prefix];
+    if (!resolver) {
+      throw new Error(
+        `[Persona] No target provider registered for "${prefix}". ` +
+          `Add a \`targetProviders.${prefix}\` resolver, or use a Runtype agent_/flow_ id.`,
+      );
+    }
+    return { kind: "payload", payload: resolver(rest).payload };
+  }
+
+  // No prefix: a bare Runtype TypeID is self-describing.
+  const detected = detectRuntypeTypeId(trimmed);
+  if (detected) return detected;
+
+  // Bare, non-TypeID name: only resolvable via an explicit default resolver.
+  const fallback = targetProviders?.default;
+  if (fallback) return { kind: "payload", payload: fallback(trimmed).payload };
+
+  throw new Error(
+    `[Persona] target "${trimmed}" has no provider prefix and is not a Runtype agent_/flow_ id. ` +
+      `Use "<provider>:${trimmed}", a Runtype TypeID, or register a \`targetProviders.default\` resolver.`,
+  );
+}