@runtypelabs/persona 4.2.1 → 4.3.1

package/src/client.test.ts

@@ -469,12 +469,12 @@ describe('AgentWidgetClient - JSON Streaming', () => {
       'data: {"type":"flow_complete","flowId":"flow_01k9pfnztzfag9tfz4t65c9c5q","success":true,"duration":2968,"completedAt":"2025-11-12T23:47:42.234Z","totalTokensUsed":0}'
     ];
 
-    // Route the legacy step_chunk fixtures through the oracle as the 4.0 unified
-    // wire (step_chunk → step_delta → text_delta), exercising the structured
-    // JSON parser on the unified flow path: incremental text extraction, never
+    // Route the legacy step_chunk fixtures through the oracle as the 4.0 wire
+    // (step_chunk → step_delta → text_delta), exercising the structured
+    // JSON parser on the wire flow path: incremental text extraction, never
     // showing raw JSON, with the assembled response reconciled at step_complete.
     global.fetch = createRawStreamFetch(
-      toUnifiedFrames(
+      legacyToWireFrames(
         sseEvents
           .filter((f) => f.startsWith('data:'))
           .map((f) => f.replace('"type":"step_chunk"', '"type":"step_delta"') + '\n\n')
@@ -581,13 +581,13 @@ function sseEvent(eventType: string, data: Record<string, unknown>): string {
 
 /**
  * Re-encode legacy `agent_*` / `flow_*` / `step_*` / `tool_*` SSE frames into the
- * neutral UNIFIED wire the 4.0 API now emits, using the same encoder the API uses
+ * Persona wire the 4.0 API now emits, using the same encoder the API uses
  * (the vendored `createUnifiedEventWrite` oracle). The 4.0 widget only consumes the
- * unified vocabulary, so these handler tests author the rendering intent in the
+ * wire vocabulary, so these handler tests author the rendering intent in the
  * (more readable) legacy frames and inject exactly what the client sees off the
  * wire — the bridge translates it straight back before the dispatch chain renders.
  */
-function toUnifiedFrames(legacyFrames: string[]): string[] {
+function legacyToWireFrames(legacyFrames: string[]): string[] {
   const out: string[] = [];
   const write = createUnifiedEventWrite((chunk) => out.push(chunk));
   for (const frame of legacyFrames) write(frame);
@@ -595,7 +595,7 @@ function toUnifiedFrames(legacyFrames: string[]): string[] {
 }
 
 /** Stream pre-built SSE frames verbatim (no re-encode) — for fixtures already in
- *  the unified vocabulary. */
+ *  the wire vocabulary. */
 function createRawStreamFetch(frames: string[]) {
   return vi.fn().mockImplementation(async (_url?: string, _options?: any) => {
     const encoder = new TextEncoder();
@@ -610,10 +610,10 @@ function createRawStreamFetch(frames: string[]) {
 }
 
 /**
- * Mock fetch that streams the given legacy events as the 4.0 unified wire.
+ * Mock fetch that streams the given legacy events as the 4.0 wire.
  */
 function createAgentStreamFetch(events: string[]) {
-  return createRawStreamFetch(toUnifiedFrames(events));
+  return createRawStreamFetch(legacyToWireFrames(events));
 }
 
 describe('AgentWidgetClient - Agent Mode Detection', () => {
@@ -638,7 +638,199 @@ describe('AgentWidgetClient - Agent Mode Detection', () => {
   });
 });
 
+describe('AgentWidgetClient - target routing', () => {
+  const userMessage = (): AgentWidgetMessage[] => [
+    { id: 'u1', role: 'user', content: 'hi', createdAt: '2025-01-01T00:00:00.000Z' },
+  ];
+
+  it('routes a Runtype agent TypeID target through agent mode', async () => {
+    let captured: any = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: any) => {
+      captured = JSON.parse(options.body);
+      const encoder = new TextEncoder();
+      return {
+        ok: true,
+        body: new ReadableStream({
+          start(controller) {
+            controller.enqueue(encoder.encode(sseEvent('agent_complete', {
+              executionId: 'exec_1', agentId: 'agent_123', success: true, iterations: 1,
+              completedAt: new Date().toISOString(), seq: 1,
+            })));
+            controller.close();
+          },
+        }),
+      };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000', target: 'agent_123' });
+    expect(client.isAgentMode()).toBe(true);
+    await client.dispatch({ messages: userMessage() }, () => {});
+
+    expect(captured.agent).toEqual({ agentId: 'agent_123' });
+  });
+
+  it('routes a Runtype flow TypeID target through flow dispatch', async () => {
+    let captured: any = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: any) => {
+      captured = JSON.parse(options.body);
+      const encoder = new TextEncoder();
+      return {
+        ok: true,
+        body: new ReadableStream({
+          start(controller) {
+            controller.enqueue(encoder.encode('data: {"type":"flow_complete","success":true}\n\n'));
+            controller.close();
+          },
+        }),
+      };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000', target: 'flow_123' });
+    expect(client.isAgentMode()).toBe(false);
+    await client.dispatch({ messages: userMessage() }, () => {});
+
+    expect(captured.flowId).toBe('flow_123');
+    expect(captured.agent).toBeUndefined();
+  });
+
+  it('spreads a custom provider target payload into the proxy dispatch body', async () => {
+    let captured: any = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: any) => {
+      captured = JSON.parse(options.body);
+      const encoder = new TextEncoder();
+      return {
+        ok: true,
+        body: new ReadableStream({
+          start(controller) {
+            controller.enqueue(encoder.encode('data: {"type":"flow_complete","success":true}\n\n'));
+            controller.close();
+          },
+        }),
+      };
+    });
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      target: 'eve:support',
+      targetProviders: { eve: (id) => ({ payload: { assistant: id } }) },
+    });
+    expect(client.isAgentMode()).toBe(false);
+    await client.dispatch({ messages: userMessage() }, () => {});
+
+    expect(captured.assistant).toBe('support');
+    expect(Array.isArray(captured.messages)).toBe(true);
+  });
+
+  it('throws when target is combined with agentId', () => {
+    expect(
+      () => new AgentWidgetClient({ apiUrl: 'http://localhost:8000', target: 'agent_1', agentId: 'agent_2' }),
+    ).toThrow(/mutually exclusive/i);
+  });
+});
+
 describe('AgentWidgetClient - Agent Payload Building', () => {
+  it('should build a saved agent-id payload from top-level agentId', async () => {
+    let capturedPayload: any = null;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, options: any) => {
+      capturedPayload = JSON.parse(options.body);
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode(sseEvent('agent_complete', {
+            executionId: 'exec_1',
+            agentId: 'agent_123',
+            success: true,
+            iterations: 1,
+            completedAt: new Date().toISOString(),
+            seq: 1,
+          })));
+          controller.close();
+        }
+      });
+      return { ok: true, body: stream };
+    });
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      agentId: 'agent_123',
+    });
+
+    await client.dispatch({
+      messages: [{
+        id: 'usr_1',
+        role: 'user',
+        content: 'Hello saved agent',
+        createdAt: '2025-01-01T00:00:00.000Z',
+      }],
+    }, () => {});
+
+    expect(capturedPayload).toBeDefined();
+    expect(capturedPayload.agent).toEqual({ agentId: 'agent_123' });
+    expect(capturedPayload.flowId).toBeUndefined();
+    expect(capturedPayload.messages).toHaveLength(1);
+    expect(capturedPayload.messages[0].content).toBe('Hello saved agent');
+    expect(capturedPayload.options.streamResponse).toBe(true);
+    expect(capturedPayload.options.recordMode).toBe('virtual');
+  });
+
+  it('uses top-level agentId as the client-token session target', async () => {
+    const requests: Array<{ url: string; body: Record<string, unknown> }> = [];
+    global.fetch = vi.fn().mockImplementation(async (url: string, options: any) => {
+      requests.push({ url, body: JSON.parse(options.body) });
+      if (url.endsWith('/v1/client/init')) {
+        return {
+          ok: true,
+          json: async () => ({
+            sessionId: 'sess_agent',
+            expiresAt: new Date(Date.now() + 5 * 60_000).toISOString(),
+            config: {},
+          }),
+        };
+      }
+      const encoder = new TextEncoder();
+      return {
+        ok: true,
+        body: new ReadableStream({
+          start(controller) {
+            controller.enqueue(encoder.encode(sseEvent('agent_complete', {
+              executionId: 'exec_1',
+              agentId: 'agent_123',
+              success: true,
+              iterations: 1,
+              completedAt: new Date().toISOString(),
+              seq: 1,
+            })));
+            controller.close();
+          },
+        }),
+      };
+    });
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'https://api.runtype.com',
+      clientToken: 'ct_live_demo',
+      agentId: 'agent_123',
+    });
+
+    await client.dispatch({
+      messages: [{
+        id: 'usr_1',
+        role: 'user',
+        content: 'Hello agent token',
+        createdAt: '2025-01-01T00:00:00.000Z',
+      }],
+    }, () => {});
+
+    expect(requests[0]).toMatchObject({
+      url: 'https://api.runtype.com/v1/client/init',
+      body: { token: 'ct_live_demo', flowId: 'agent_123' },
+    });
+    expect(requests[1]).toMatchObject({
+      url: 'https://api.runtype.com/v1/client/chat',
+      body: { sessionId: 'sess_agent' },
+    });
+  });
+
   it('should build agent payload with agent config', async () => {
     let capturedPayload: any = null;
     global.fetch = vi.fn().mockImplementation(async (_url: string, options: any) => {
@@ -1239,7 +1431,7 @@ describe('AgentWidgetClient - Agent Event Streaming', () => {
       }
     }
 
-    // Reflection now folds into a loop-scoped reasoning bubble (unified spec):
+    // Reflection now folds into a loop-scoped reasoning bubble (wire spec):
     // `agent_reflection` → reasoning_start{scope:"loop"} + reasoning_complete{text}.
     const reflectionMessages = Array.from(messagesById.values())
       .filter(m => m.variant === 'reasoning' && m.reasoning?.scope === 'loop');
@@ -1296,7 +1488,7 @@ describe('AgentWidgetClient - Agent Event Streaming', () => {
 });
 
 // ============================================================================
-// Unified Event Name Support (chunk → delta, agent_tool_* → tool_* with agentContext)
+// Wire event name support (chunk → delta, agent_tool_* → tool_* with agentContext)
 // ============================================================================
 
 // ============================================================================
@@ -1590,7 +1782,7 @@ describe('AgentWidgetClient - partId Text/Tool Interleaving', () => {
     expect(assistantTexts.length).toBe(2);
     // First message uses the provided ID
     expect(assistantTexts[0].id).toBe('ast_pre_generated_id');
-    // Second message composes baseId + the unified text block id for traceability
+    // Second message composes baseId + the wire text block id for traceability
     expect(assistantTexts[1].id).toBe('ast_pre_generated_id_text_2');
     // Content is correct per segment
     expect(assistantTexts[0].content).toBe('Before tool.');
@@ -1600,7 +1792,7 @@ describe('AgentWidgetClient - partId Text/Tool Interleaving', () => {
   it('should not overwrite last segment content with the full step response (flow)', async () => {
     const events: AgentWidgetEvent[] = [];
 
-    // Unified wire: two flow text segments split by a tool, each its own block
+    // Wire: two flow text segments split by a tool, each its own block
     // (sealed by text_end → text_complete). The step's full structured response
     // (`step_complete.result.response`) reconciles rawContent without clobbering
     // either sealed bubble's displayed content.
@@ -1715,10 +1907,10 @@ describe('AgentWidgetClient - partId Text/Tool Interleaving', () => {
       };
     };
 
-    // Unified wire (via the oracle): a single flow text block carrying partial
+    // Wire (via the oracle): a single flow text block carrying partial
     // structured JSON, sealed by text_end, then the authoritative final structured
     // response on step_complete. Exercises the async structured-content parser +
-    // sealed-segment reconciliation on the unified flow path.
+    // sealed-segment reconciliation on the wire flow path.
     global.fetch = createAgentStreamFetch([
       sseEvent('flow_start', { flowId: 'f1', flowName: 'Test', totalSteps: 1 }),
       sseEvent('tool_start', { toolId: 'tc_1', name: 'test_tool', toolType: 'custom', startedAt: new Date().toISOString() }),
@@ -1914,7 +2106,7 @@ describe('AgentWidgetClient - flow continuation stream without execution_start',
 
 describe('AgentWidgetClient - nested flow-as-tool (parentToolCallId)', () => {
   // PR #4602: a flow running as a tool enriches its streamed text/reasoning with
-  // toolContext.toolId; the unified wire surfaces it as text_start/reasoning_start
+  // toolContext.toolId; the wire surfaces it as text_start/reasoning_start
   // .parentToolCallId, and the widget routes that block into the parent tool's row.
   it('routes nested flow text into the parent tool row, not the top-level assistant', async () => {
     const events: AgentWidgetEvent[] = [];
@@ -2462,9 +2654,9 @@ describe('AgentWidgetClient - agent_turn text/tool interleaving', () => {
 // ============================================================================
 
 describe('AgentWidgetClient: step_await parsing', () => {
-  // Unified collapses the legacy flow `step_await` (a `local_tool_required` pause)
+  // Wire collapses the legacy flow `step_await` (a `local_tool_required` pause)
   // into the neutral `await` event the native handler consumes.
-  const buildUnifiedAwaitStream = (payload: Record<string, unknown>): ReadableStream<Uint8Array> => {
+  const buildAwaitStream = (payload: Record<string, unknown>): ReadableStream<Uint8Array> => {
     const encoder = new TextEncoder();
     const body = `event: await\ndata: ${JSON.stringify({ type: 'await', ...payload })}\n\n`;
     return new ReadableStream({
@@ -2490,7 +2682,7 @@ describe('AgentWidgetClient: step_await parsing', () => {
   it('emits a complete tool message with awaitingLocalTool=true for local_tool_required', async () => {
     global.fetch = vi.fn().mockResolvedValue({
       ok: true,
-      body: buildUnifiedAwaitStream({
+      body: buildAwaitStream({
         awaitReason: 'local_tool_required',
         id: 'step-1',
         name: 'Test Step',
@@ -2530,7 +2722,7 @@ describe('AgentWidgetClient: step_await parsing', () => {
   it('emits a running tool message for WebMCP local_tool_required until the browser tool resolves', async () => {
     global.fetch = vi.fn().mockResolvedValue({
       ok: true,
-      body: buildUnifiedAwaitStream({
+      body: buildAwaitStream({
         awaitReason: 'local_tool_required',
         id: 'step-1',
         name: 'Test Step',
@@ -2601,7 +2793,7 @@ describe('AgentWidgetClient: step_await parsing', () => {
 // ============================================================================
 
 describe('AgentWidgetClient: agent_await parsing', () => {
-  // Unified collapses the legacy `step_await`/`agent_await` pair into one `await`
+  // Wire collapses the legacy `step_await`/`agent_await` pair into one `await`
   // event; the dispatch origin survives as the `origin` field on the payload.
   const buildAgentAwaitStream = (payload: Record<string, unknown>): ReadableStream<Uint8Array> => {
     const encoder = new TextEncoder();
@@ -3027,7 +3219,7 @@ describe('AgentWidgetClient - agent_media events', () => {
       (e) => events.push(e)
     );
 
-    // Unified streams each media item as its own block (media_start/complete),
+    // Wire streams each media item as its own block (media_start/complete),
     // so each renders as its own synthetic message with a single content part.
     const mediaMessages = collectMediaMessages(events);
     expect(mediaMessages).toHaveLength(3);
@@ -3788,8 +3980,8 @@ describe('AgentWidgetClient - version header', () => {
   });
 });
 
-describe('AgentWidgetClient - Unified event vocabulary (default in 4.0)', () => {
-  const unifiedTextStream = (execId: string) => [
+describe('AgentWidgetClient - Wire event vocabulary (default in 4.0)', () => {
+  const sampleTextStream = (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 }),
@@ -3800,14 +3992,14 @@ describe('AgentWidgetClient - Unified event vocabulary (default in 4.0)', () =>
     sseEvent('execution_complete', { kind: 'agent', executionId: execId, success: true, completedAt: new Date().toISOString(), seq: 8 }),
   ];
 
-  it('does not append an events param to the dispatch URL (unified is the default wire)', async () => {
+  it('does not append an events param to the dispatch URL (the wire is the only format)', 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));
+          for (const e of sampleTextStream('exec_u')) c.enqueue(encoder.encode(e));
           c.close();
         },
       });
@@ -3825,10 +4017,10 @@ describe('AgentWidgetClient - Unified event vocabulary (default in 4.0)', () =>
     expect(capturedUrl).not.toContain('events=');
   });
 
-  it('renders a unified stream through the internal handlers with no config flag', async () => {
+  it('renders a wire stream through the internal handlers with no config flag', async () => {
     const events: AgentWidgetEvent[] = [];
     const execId = 'exec_u1';
-    global.fetch = createRawStreamFetch(unifiedTextStream(execId));
+    global.fetch = createRawStreamFetch(sampleTextStream(execId));
 
     const client = new AgentWidgetClient({
       apiUrl: 'http://localhost:8000',

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,7 +2014,7 @@ 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
@@ -2498,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;
@@ -2620,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
@@ -2640,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,
@@ -2676,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.
@@ -2832,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
@@ -3047,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 &&
@@ -3165,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,