@runtypelabs/persona 4.2.0 → 4.3.0

package/src/client.ts

@@ -24,6 +24,7 @@ import {
   WebMcpConfirmHandler
 } from "./types";
 import { WebMcpBridge, computeClientToolsFingerprint, isWebMcpToolName } from "./webmcp-bridge";
+import { resolveTarget } from "./utils/target";
 import { builtInClientToolsForDispatch } from "./ask-user-question-tool";
 import {
   extractTextFromJson,
@@ -185,6 +186,11 @@ export class AgentWidgetClient {
   private readonly webMcpBridge: WebMcpBridge | null;
 
   constructor(private config: AgentWidgetConfig = {}) {
+    if (config.target && (config.agentId || config.flowId || config.agent)) {
+      throw new Error(
+        "[Persona] `target` is mutually exclusive with `agentId`, `flowId`, and `agent`. Set only one routing field.",
+      );
+    }
     this.apiUrl = config.apiUrl ?? DEFAULT_ENDPOINT;
     this.headers = {
       "Content-Type": "application/json",
@@ -284,11 +290,33 @@ export class AgentWidgetClient {
     return !!this.config.clientToken;
   }
 
+  /**
+   * Resolve the effective backend routing for the current config. Combines the
+   * explicit `agentId`/`flowId` fields with the normalized `target` string
+   * (resolved via `resolveTarget`). Computed on demand so it stays correct
+   * across `update()`; the `target`/explicit-field conflict is rejected in the
+   * constructor, so at most one source is set here.
+   */
+  private routing(): {
+    agentId?: string;
+    flowId?: string;
+    targetPayload?: Record<string, unknown>;
+  } {
+    const { agentId, flowId, target, targetProviders } = this.config;
+    if (!target) {
+      return { agentId, flowId };
+    }
+    const resolved = resolveTarget(target, targetProviders);
+    if (resolved.kind === "agentId") return { agentId: resolved.agentId };
+    if (resolved.kind === "flowId") return { flowId: resolved.flowId };
+    return { targetPayload: resolved.payload };
+  }
+
   /**
    * Check if operating in agent execution mode
    */
   public isAgentMode(): boolean {
-    return !!this.config.agent;
+    return !!(this.config.agent || this.routing().agentId);
   }
 
   /**
@@ -346,9 +374,11 @@ export class AgentWidgetClient {
     // Get stored session_id if available (for session resumption)
     const storedSessionId = this.config.getStoredSessionId?.() || null;
     
+    const routed = this.routing();
+    const sessionTargetId = routed.agentId ?? routed.flowId;
     const requestBody: Record<string, unknown> = {
       token: this.config.clientToken,
-      ...(this.config.flowId && { flowId: this.config.flowId }),
+      ...(sessionTargetId && { flowId: sessionTargetId }),
       ...(storedSessionId && { sessionId: storedSessionId }),
     };
 
@@ -584,12 +614,12 @@ export class AgentWidgetClient {
    * Send a message - handles both proxy and client token modes
    */
   public async dispatch(options: DispatchOptions, onEvent: SSEHandler) {
-    if (this.isAgentMode()) {
-      return this.dispatchAgent(options, onEvent);
-    }
     if (this.isClientTokenMode()) {
       return this.dispatchClientToken(options, onEvent);
     }
+    if (this.isAgentMode()) {
+      return this.dispatchAgent(options, onEvent);
+    }
     return this.dispatchProxy(options, onEvent);
   }
 
@@ -1040,7 +1070,8 @@ export class AgentWidgetClient {
   private async buildAgentPayload(
     messages: AgentWidgetMessage[]
   ): Promise<AgentWidgetAgentRequestPayload> {
-    if (!this.config.agent) {
+    const routedAgentId = this.routing().agentId;
+    if (!this.config.agent && !routedAgentId) {
       throw new Error('Agent configuration required for agent mode');
     }
 
@@ -1062,7 +1093,7 @@ export class AgentWidgetClient {
       }));
 
     const payload: AgentWidgetAgentRequestPayload = {
-      agent: this.config.agent,
+      agent: this.config.agent ?? { agentId: routedAgentId! },
       messages: normalizedMessages,
       options: {
         streamResponse: true,
@@ -1134,11 +1165,27 @@ export class AgentWidgetClient {
         createdAt: message.createdAt
       }));
 
+    const routed = this.routing();
     const payload: AgentWidgetRequestPayload = {
       messages: normalizedMessages,
-      ...(this.config.flowId && { flowId: this.config.flowId })
+      ...(routed.agentId
+        ? { agent: { agentId: routed.agentId } }
+        : routed.flowId
+          ? { flowId: routed.flowId }
+          : {})
     };
 
+    // Custom-provider targets (e.g. `eve:support`) resolve to a payload
+    // fragment that is merged into the dispatch body so a BYO backend can read
+    // whatever routing keys its resolver chose. `messages` is authoritative and
+    // can never be overridden by a resolver.
+    if (routed.targetPayload) {
+      for (const [key, value] of Object.entries(routed.targetPayload)) {
+        if (key === "messages") continue;
+        (payload as Record<string, unknown>)[key] = value;
+      }
+    }
+
     // Client tools: same built-in + WebMCP merge as buildAgentPayload
     // (flow-dispatch path).
     const clientTools = [
@@ -1378,10 +1425,10 @@ export class AgentWidgetClient {
     // Reference to track assistant message for custom event handler
     const assistantMessageRef = { current: null as AgentWidgetMessage | null };
     // Segmentation state for the `parseSSEEvent` extensibility callback (the
-    // consumer's own `partId` field) — independent of the unified wire.
+    // consumer's own `partId` field) — independent of the wire.
     const customParsePartId = { current: null as string | null };
     // Unified text-channel block id (from `text_start`/`text_delta` `id`). Drives
-    // bubble-id segmentation on the unified wire in place of the legacy `partId`:
+    // bubble-id segmentation on the wire in place of the legacy `partId`:
     // a new block id means a new bubble, sealed at `text_complete`/tool boundaries.
     let currentTextBlockId: string | null = null;
     // Raw text accumulated for the open flow block before its bubble is
@@ -1389,7 +1436,7 @@ export class AgentWidgetClient {
     let pendingFlowRaw = "";
     // Nested flow-as-tool attribution (PR #4602): a text/reasoning block whose
     // `parentToolCallId` matches a `tool_start.toolCallId` belongs to a flow
-    // running as that tool. Keyed by the unified block id, these route the block's
+    // running as that tool. Keyed by the wire block id, these route the block's
     // deltas into a message tagged `agentMetadata.parentToolId` (the parent tool's
     // row) instead of the top-level assistant/reasoning channel.
     const nestedBlockParent = new Map<string, string>();
@@ -1769,7 +1816,7 @@ export class AgentWidgetClient {
     // `text_start`/`text_complete`) and can be structured JSON, so each block
     // runs through the per-bubble structured-content parser — agent text stays
     // plain. This is the legacy step_delta parser core, re-keyed from `partId`
-    // to the unified block-id bubble. The caller materializes the bubble lazily
+    // to the wire block-id bubble. The caller materializes the bubble lazily
     // (whitespace-only blocks around tool boundaries never leave a stray bubble)
     // and `step_complete.result.response` reconciles the authoritative final.
     let lastSealedFlowBubble: AgentWidgetMessage | null = null;
@@ -1947,16 +1994,16 @@ export class AgentWidgetClient {
       return message;
     };
 
-    // Ready queue of parsed unified frames awaiting a drain. The API streams the
-    // neutral 33-event unified vocabulary; each frame is parsed in the SSE loop
+    // Ready queue of parsed wire frames awaiting a drain. The API streams the
+    // 33-event wire vocabulary; each frame is parsed in the SSE loop
     // below and rendered directly by the handler (no translation bridge), then
-    // pushed here. The unified stream is a single, in-order SSE connection, so
+    // pushed here. The wire stream is a single, in-order SSE connection, so
     // frames drain straight through with no reordering.
     const seqReadyQueue: Array<{ payloadType: string; payload: any }> = [];
     // Declared here so later closures can reference it; assigned after all
     // handler-scoped variables are initialised (before the SSE loop).
     let drainReadyQueue: () => void;
-    // Per-stream media-block buffer: the unified media triad
+    // Per-stream media-block buffer: the media triad
     // (media_start/media_delta/media_complete) is reassembled here into a single
     // synthetic message at media_complete, keyed by the block id.
     const mediaBuffers = new Map<
@@ -1967,8 +2014,17 @@ export class AgentWidgetClient {
     // `turn_start` advancing the iteration rotates the bubble in 'separate' mode.
     let lastIterationSeen = 0;
     // Execution kind, resolved from the leading `execution_start` frame. Drives
-    // the agent-vs-flow branches that the single unified vocabulary collapses.
+    // the agent-vs-flow branches that the single wire vocabulary collapses.
     let executionKind: "agent" | "flow" = "agent";
+    // Whether `executionKind` was set authoritatively by an `execution_start`
+    // frame. Continuation streams (e.g. a tool-driven `/resume`) do NOT re-emit
+    // `execution_start`, so a fresh `streamResponse` for the continuation starts
+    // with the default `"agent"`. For a flow that mis-routes the final
+    // prompt-step finalization and duplicates the last message (the streamed
+    // text block is sealed, then `step_complete.result.response` re-renders it as
+    // a second bubble). When `execution_start` is absent we recover the flow kind
+    // from the first flow `step_*` frame below.
+    let executionKindResolved = false;
     // Open turn id (from `turn_start`). Unified text/reasoning deltas carry their
     // own block id, not the turn id, so the turn id is threaded onto agentMetadata
     // from here.
@@ -1987,6 +2043,21 @@ export class AgentWidgetClient {
         const payloadType = seqReadyQueue[i].payloadType;
         const payload = seqReadyQueue[i].payload;
 
+        // Recover the execution kind on continuation streams that omit
+        // `execution_start` (e.g. a tool-driven `/resume`). Flow `step_*` frames
+        // carry a `stepType`; agent loops never do (they use `turn_*`). Without
+        // this, the continuation defaults to `"agent"` and a flow's final
+        // prompt-step finalization is duplicated. We only infer when no
+        // `execution_start` resolved the kind, so an explicit `agent` is never
+        // overridden.
+        if (
+          !executionKindResolved &&
+          executionKind !== "flow" &&
+          typeof (payload as { stepType?: unknown }).stepType === "string"
+        ) {
+          executionKind = "flow";
+        }
+
         if (payloadType === "reasoning_start") {
           // Nested flow-as-tool thinking (PR #4602): route to the parent tool's row.
           const rStartBlockId = typeof payload.id === "string" ? payload.id : null;
@@ -2474,7 +2545,7 @@ export class AgentWidgetClient {
           }
 
           // A failed step (`success:false`) — including the legacy `step_error`
-          // event, which the unified encoder folds into a failed `step_complete`
+          // event, which the wire encoder folds into a failed `step_complete`
           // — surfaces as a terminal error and finalizes the stream.
           if (payload.success === false) {
             const e = payload.error;
@@ -2543,6 +2614,7 @@ export class AgentWidgetClient {
         // ================================================================
         } else if (payloadType === "execution_start") {
           executionKind = payload.kind === "flow" ? "flow" : "agent";
+          executionKindResolved = true;
           if (executionKind === "agent") {
             agentExecution = {
               executionId: payload.executionId,
@@ -2595,7 +2667,7 @@ export class AgentWidgetClient {
           // Authoritative args are set at tool_start; nothing to render here.
           continue;
         } else if (payloadType === "turn_complete") {
-          // Reasoning is sealed by its own reasoning_complete in the unified
+          // Reasoning is sealed by its own reasoning_complete on the wire
           // vocabulary; this only attaches the turn-level stopReason to the
           // assistant message produced by this turn. Falls back to
           // lastAssistantInTurn when the bubble was sealed at a tool boundary
@@ -2615,7 +2687,7 @@ export class AgentWidgetClient {
           }
           if (openTurnId === payload.id) openTurnId = null;
         } else if (payloadType === "media_start") {
-          // Open a unified media block; buffer fragments until media_complete.
+          // Open a media block; buffer fragments until media_complete.
           const id = String(payload.id);
           mediaBuffers.set(id, {
             mediaType: typeof payload.mediaType === "string" ? payload.mediaType : undefined,
@@ -2651,7 +2723,7 @@ export class AgentWidgetClient {
           if (completeData) {
             reconstructed = { type: "media", data: completeData, mediaType: completeMediaType };
           } else if (completeUrl) {
-            // The unified wire is mediaType-only; a URL part with no declared MIME
+            // The wire is mediaType-only; a URL part with no declared MIME
             // arrives as the bare bucket hint "image" (per the API encoder). Treat
             // that — and any real `image/*` — as a hosted image so we don't misroute
             // generated images into the file bucket.
@@ -2807,7 +2879,7 @@ export class AgentWidgetClient {
 
           onEvent({ type: "status", status: "idle" });
         } else if (payloadType === "execution_error") {
-          // Terminal failure. The unified non-terminal `error` is handled
+          // Terminal failure. The non-terminal `error` is handled
           // separately (recoverable → warn).
           const errorMessage = typeof payload.error === 'string'
             ? payload.error
@@ -3022,7 +3094,7 @@ export class AgentWidgetClient {
           // retrying" — and the execution continues, so it must NOT surface as a
           // fatal error or finalize the stream. The API routes terminal failures
           // through `execution_error`. Only an explicit `recoverable: false`
-          // promotes a unified `error` to terminal.
+          // promotes an `error` to terminal.
           if (
             payload.recoverable === false &&
             payload.error != null &&
@@ -3140,7 +3212,7 @@ export class AgentWidgetClient {
           if (handled) continue; // Skip default handling if custom handler processed it
         }
 
-        // The wire is the neutral unified vocabulary; the handler consumes it
+        // The wire is the wire vocabulary; the handler consumes it
         // natively. The stream is single-connection and in order, so each frame
         // drains straight through.
         seqReadyQueue.push({ payloadType, payload });

package/src/defaults.ts

@@ -72,6 +72,8 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   apiUrl: "https://api.runtype.com/api/chat/dispatch",
   // Client token mode defaults (optional, only used when clientToken is set)
   clientToken: undefined,
+  agentId: undefined,
+  target: undefined,
   theme: undefined,
   darkTheme: undefined,
   colorScheme: "light",

package/src/index-core.ts

@@ -5,6 +5,8 @@ import {
 
 export type {
   AgentWidgetConfig,
+  TargetResolver,
+  ResolvedTarget,
   AgentWidgetFeatureFlags,
   AgentWidgetArtifactsFeature,
   AgentWidgetArtifactsLayoutConfig,

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/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);
+  });
+});