@runtypelabs/persona 4.2.0 → 4.3.0

package/dist/theme-editor.d.cts

@@ -1385,6 +1385,32 @@ type RuntypeTurnCompleteEvent = RuntypeStreamEventOf<RuntypeExecutionStreamEvent
 type RuntypeStepCompleteEvent = RuntypeStreamEventOf<RuntypeFlowSSEEvent, "step_complete">;
 type RuntypeStopReasonKind = NonNullable<RuntypeTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]>;
 
+/**
+ * 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. */
+type TargetResolver = (id: string) => {
+    payload: Record<string, unknown>;
+};
+
 /**
  * Text content part for multi-modal messages
  */
@@ -1451,6 +1477,9 @@ type AgentWidgetRequestPayloadMessage = {
 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). */
@@ -4482,6 +4511,52 @@ type AgentWidgetLoadingIndicatorConfig = {
 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
@@ -5167,7 +5242,7 @@ 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/dist/theme-editor.d.ts

@@ -1385,6 +1385,32 @@ type RuntypeTurnCompleteEvent = RuntypeStreamEventOf<RuntypeExecutionStreamEvent
 type RuntypeStepCompleteEvent = RuntypeStreamEventOf<RuntypeFlowSSEEvent, "step_complete">;
 type RuntypeStopReasonKind = NonNullable<RuntypeTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]>;
 
+/**
+ * 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. */
+type TargetResolver = (id: string) => {
+    payload: Record<string, unknown>;
+};
+
 /**
  * Text content part for multi-modal messages
  */
@@ -1451,6 +1477,9 @@ type AgentWidgetRequestPayloadMessage = {
 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). */
@@ -4482,6 +4511,52 @@ type AgentWidgetLoadingIndicatorConfig = {
 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
@@ -5167,7 +5242,7 @@ 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.
      */