@runtypelabs/persona 3.19.0 → 3.20.0

package/src/session.ts

@@ -11,6 +11,7 @@ import {
   InjectAssistantMessageOptions,
   InjectUserMessageOptions,
   InjectSystemMessageOptions,
+  InjectComponentDirectiveOptions,
   PersonaArtifactRecord,
   PersonaArtifactManualUpsert
 } from "./types";
@@ -572,7 +573,8 @@ export class AgentWidgetSession {
       createdAt,
       sequence,
       streaming = false,
-      voiceProcessing
+      voiceProcessing,
+      rawContent
     } = options;
 
     // Generate appropriate ID based on role
@@ -594,7 +596,8 @@ export class AgentWidgetSession {
       // Only include optional fields if provided
       ...(llmContent !== undefined && { llmContent }),
       ...(contentParts !== undefined && { contentParts }),
-      ...(voiceProcessing !== undefined && { voiceProcessing })
+      ...(voiceProcessing !== undefined && { voiceProcessing }),
+      ...(rawContent !== undefined && { rawContent })
     };
 
     // Use upsert to handle both new messages and updates (streaming)
@@ -673,7 +676,9 @@ export class AgentWidgetSession {
         id,
         createdAt,
         sequence,
-        streaming = false
+        streaming = false,
+        voiceProcessing,
+        rawContent
       } = options;
 
       const messageId =
@@ -692,7 +697,9 @@ export class AgentWidgetSession {
         sequence: sequence ?? this.nextSequence(),
         streaming,
         ...(llmContent !== undefined && { llmContent }),
-        ...(contentParts !== undefined && { contentParts })
+        ...(contentParts !== undefined && { contentParts }),
+        ...(voiceProcessing !== undefined && { voiceProcessing }),
+        ...(rawContent !== undefined && { rawContent })
       };
 
       results.push(message);
@@ -705,6 +712,53 @@ export class AgentWidgetSession {
     return results;
   }
 
+  /**
+   * Convenience method for injecting a registered component directive as
+   * an assistant message — the same shape Persona produces from a streamed
+   * `{ "text": "...", "component": "...", "props": {...} }` payload.
+   *
+   * Sets `content` to `text`, `rawContent` to the JSON directive (so
+   * `extractComponentDirectiveFromMessage` can find it), and forwards
+   * `llmContent` / `id` / `createdAt` / `sequence`.
+   *
+   * @example
+   * session.injectComponentDirective({
+   *   component: "DynamicForm",
+   *   props: { title: "Book a demo", fields: [...] },
+   *   text: "Share your details to book a demo.",
+   *   llmContent: "[Showed booking form]"
+   * });
+   */
+  public injectComponentDirective(
+    options: InjectComponentDirectiveOptions
+  ): AgentWidgetMessage {
+    const {
+      component,
+      props = {},
+      text = "",
+      llmContent,
+      id,
+      createdAt,
+      sequence
+    } = options;
+
+    const directive: { text: string; component: string; props: Record<string, unknown> } = {
+      text,
+      component,
+      props
+    };
+
+    return this.injectMessage({
+      role: "assistant",
+      content: text,
+      rawContent: JSON.stringify(directive),
+      ...(llmContent !== undefined && { llmContent }),
+      ...(id !== undefined && { id }),
+      ...(createdAt !== undefined && { createdAt }),
+      ...(sequence !== undefined && { sequence })
+    });
+  }
+
   public async sendMessage(
     rawInput: string,
     options?: {

package/src/types.ts

@@ -3768,6 +3768,23 @@ export type InjectMessageOptions = {
    * Consumers can detect this in `messageTransform` to render custom UI.
    */
   voiceProcessing?: boolean;
+
+  /**
+   * Raw structured payload (typically a JSON string) representing the
+   * full directive that produced this message — e.g. `{ "text": "...",
+   * "component": "Foo", "props": {...} }`.
+   *
+   * Mirrors the field populated by stream parsers during normal LLM
+   * responses. Set this when injecting a message that should render as a
+   * component directive (`hasComponentDirective` /
+   * `extractComponentDirectiveFromMessage` look at `rawContent` first).
+   *
+   * Priority for the API payload remains:
+   * `contentParts > llmContent > rawContent > content`. Pass `llmContent`
+   * alongside `rawContent` if the LLM should see something other than the
+   * raw directive.
+   */
+  rawContent?: string;
 };
 
 /**
@@ -3788,6 +3805,64 @@ export type InjectUserMessageOptions = Omit<InjectMessageOptions, "role">;
  */
 export type InjectSystemMessageOptions = Omit<InjectMessageOptions, "role">;
 
+/**
+ * Options for injecting an assistant message that renders as a component
+ * directive — sugar over `injectAssistantMessage` for the common case of
+ * "render this registered component, same as if the LLM had emitted it".
+ *
+ * Equivalent to calling `injectAssistantMessage({ content: text, rawContent:
+ * JSON.stringify({ text, component, props }), llmContent })`.
+ *
+ * @example
+ * widget.injectComponentDirective({
+ *   component: "DynamicForm",
+ *   props: { title: "Book a demo", fields: [...] },
+ *   text: "Share your details to book a demo.",
+ *   llmContent: "[Showed booking form]"
+ * });
+ */
+export type InjectComponentDirectiveOptions = {
+  /**
+   * Name of a renderer registered via `componentRegistry.register(...)`.
+   */
+  component: string;
+
+  /**
+   * Props passed to the component renderer.
+   */
+  props?: Record<string, unknown>;
+
+  /**
+   * Bubble copy displayed above (or with) the rendered component.
+   * Mirrors the `text` field in a streamed JSON directive.
+   * @default ""
+   */
+  text?: string;
+
+  /**
+   * Content sent to the LLM in API requests. When omitted, the raw
+   * directive JSON is what the LLM would see (per the standard
+   * priority chain). Provide a redacted/short version to avoid sending
+   * the full directive in subsequent turns.
+   */
+  llmContent?: string;
+
+  /**
+   * Optional message ID. If omitted, an assistant id is auto-generated.
+   */
+  id?: string;
+
+  /**
+   * Optional creation timestamp (ISO string). If omitted, uses current time.
+   */
+  createdAt?: string;
+
+  /**
+   * Optional sequence number for ordering.
+   */
+  sequence?: number;
+};
+
 export type PersonaArtifactRecord = {
   id: string;
   artifactType: PersonaArtifactKind;

package/src/ui.ts

@@ -19,6 +19,7 @@ import {
   InjectAssistantMessageOptions,
   InjectUserMessageOptions,
   InjectSystemMessageOptions,
+  InjectComponentDirectiveOptions,
   LoadingIndicatorRenderContext,
   IdleIndicatorRenderContext,
   VoiceStatus,
@@ -296,6 +297,14 @@ type Controller = {
    * Inject multiple messages in a single batch with one sort and one render pass.
    */
   injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
+  /**
+   * Convenience method for injecting an assistant message that renders as a
+   * registered component — same shape Persona produces from a streamed
+   * `{ "text": "...", "component": "...", "props": {...} }` payload.
+   */
+  injectComponentDirective: (
+    options: InjectComponentDirectiveOptions
+  ) => AgentWidgetMessage;
   /**
    * @deprecated Use injectMessage() instead.
    */
@@ -7030,6 +7039,15 @@ export const createAgentExperience = (
       }
       return session.injectMessageBatch(optionsList);
     },
+    injectComponentDirective(
+      options: InjectComponentDirectiveOptions
+    ): AgentWidgetMessage {
+      // Auto-open widget if closed and the panel is toggleable
+      if (!open && isPanelToggleable()) {
+        setOpenState(true, "system");
+      }
+      return session.injectComponentDirective(options);
+    },
     /** @deprecated Use injectMessage() instead */
     injectTestMessage(event: AgentWidgetEvent) {
       // Auto-open widget if closed and the panel is toggleable

package/src/utils/component-middleware.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  extractComponentDirectiveFromMessage,
+  hasComponentDirective
+} from "./component-middleware";
+import type { AgentWidgetMessage } from "../types";
+
+const baseMessage = (overrides: Partial<AgentWidgetMessage>): AgentWidgetMessage => ({
+  id: "msg-1",
+  role: "assistant",
+  content: "",
+  createdAt: "2026-01-01T00:00:00.000Z",
+  ...overrides
+});
+
+describe("extractComponentDirectiveFromMessage", () => {
+  it("extracts directive from rawContent (streamed path)", () => {
+    const directive = {
+      text: "Booking form",
+      component: "DynamicForm",
+      props: { title: "Book a demo" }
+    };
+    const message = baseMessage({
+      content: "Booking form",
+      rawContent: JSON.stringify(directive)
+    });
+
+    const result = extractComponentDirectiveFromMessage(message);
+
+    expect(result).not.toBeNull();
+    expect(result?.component).toBe("DynamicForm");
+    expect(result?.props).toEqual({ title: "Book a demo" });
+    expect(result?.raw).toBe(JSON.stringify(directive));
+  });
+
+  it("falls back to content when rawContent is missing and content looks like JSON", () => {
+    const directive = {
+      text: "Booking form",
+      component: "DynamicForm",
+      props: { title: "Book a demo" }
+    };
+    const message = baseMessage({
+      content: JSON.stringify(directive)
+    });
+
+    const result = extractComponentDirectiveFromMessage(message);
+
+    expect(result).not.toBeNull();
+    expect(result?.component).toBe("DynamicForm");
+    expect(result?.props).toEqual({ title: "Book a demo" });
+  });
+
+  it("prefers rawContent over content when both are present", () => {
+    const message = baseMessage({
+      rawContent: JSON.stringify({
+        text: "Raw form",
+        component: "RawComponent",
+        props: { source: "raw" }
+      }),
+      content: JSON.stringify({
+        text: "Content form",
+        component: "ContentComponent",
+        props: { source: "content" }
+      })
+    });
+
+    const result = extractComponentDirectiveFromMessage(message);
+
+    expect(result?.component).toBe("RawComponent");
+    expect(result?.props).toEqual({ source: "raw" });
+  });
+
+  it("returns null for plain-text content", () => {
+    const message = baseMessage({ content: "Hello, how can I help?" });
+    expect(extractComponentDirectiveFromMessage(message)).toBeNull();
+  });
+
+  it("returns null when content is JSON without a component field", () => {
+    const message = baseMessage({
+      content: JSON.stringify({ text: "Just text", foo: "bar" })
+    });
+    expect(extractComponentDirectiveFromMessage(message)).toBeNull();
+  });
+
+  it("returns null for empty rawContent and empty content", () => {
+    const message = baseMessage({ rawContent: "", content: "" });
+    expect(extractComponentDirectiveFromMessage(message)).toBeNull();
+  });
+
+  it("returns null when JSON is malformed", () => {
+    const message = baseMessage({ rawContent: '{"component": "Foo"' });
+    expect(extractComponentDirectiveFromMessage(message)).toBeNull();
+  });
+
+  it("defaults props to {} when the directive omits or nulls them", () => {
+    const message = baseMessage({
+      rawContent: JSON.stringify({ text: "x", component: "Foo" })
+    });
+    const result = extractComponentDirectiveFromMessage(message);
+    expect(result?.props).toEqual({});
+
+    const messageNullProps = baseMessage({
+      rawContent: JSON.stringify({ text: "x", component: "Foo", props: null })
+    });
+    expect(extractComponentDirectiveFromMessage(messageNullProps)?.props).toEqual({});
+  });
+});
+
+describe("hasComponentDirective", () => {
+  it("returns true when rawContent carries a directive", () => {
+    const message = baseMessage({
+      rawContent: JSON.stringify({ text: "x", component: "Foo", props: {} })
+    });
+    expect(hasComponentDirective(message)).toBe(true);
+  });
+
+  it("returns true when only content carries a directive", () => {
+    const message = baseMessage({
+      content: JSON.stringify({ text: "x", component: "Foo", props: {} })
+    });
+    expect(hasComponentDirective(message)).toBe(true);
+  });
+
+  it("returns false for plain content", () => {
+    const message = baseMessage({ content: "Hello!" });
+    expect(hasComponentDirective(message)).toBe(false);
+  });
+
+  it("returns false for malformed JSON", () => {
+    const message = baseMessage({ rawContent: "{not json" });
+    expect(hasComponentDirective(message)).toBe(false);
+  });
+});

package/src/utils/component-middleware.ts

@@ -87,18 +87,42 @@ export function createComponentMiddleware() {
 }
 
 /**
- * Checks if a message contains a component directive in its raw content
+ * Picks the field that may carry a JSON directive payload. Streamed messages
+ * populate `rawContent`; manually injected messages may pass the JSON via
+ * `content` directly. We try `rawContent` first, then fall back to `content`
+ * when it looks like JSON, so both code paths render the same way.
+ */
+function selectDirectiveSource(message: AgentWidgetMessage): string | null {
+  if (typeof message.rawContent === "string" && message.rawContent.length > 0) {
+    return message.rawContent;
+  }
+  if (typeof message.content === "string") {
+    const trimmed = message.content.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      return message.content;
+    }
+  }
+  return null;
+}
+
+/**
+ * Checks if a message contains a component directive.
+ *
+ * Looks at `rawContent` first (the field set by stream parsers); falls back
+ * to `content` when it looks like JSON, so injected messages that pass the
+ * directive via `content` (or have no `rawContent`) are still recognized.
  */
 export function hasComponentDirective(message: AgentWidgetMessage): boolean {
-  if (!message.rawContent) return false;
-  
+  const source = selectDirectiveSource(message);
+  if (!source) return false;
+
   try {
-    const parsed = JSON.parse(message.rawContent);
+    const parsed = JSON.parse(source);
     return (
       typeof parsed === "object" &&
       parsed !== null &&
       "component" in parsed &&
-      typeof parsed.component === "string"
+      typeof (parsed as { component: unknown }).component === "string"
     );
   } catch {
     return false;
@@ -106,27 +130,34 @@ export function hasComponentDirective(message: AgentWidgetMessage): boolean {
 }
 
 /**
- * Extracts component directive from a complete message
+ * Extracts component directive from a complete message.
+ *
+ * Looks at `rawContent` first (the field set by stream parsers); falls back
+ * to `content` when it looks like JSON, so injected messages that pass the
+ * directive via `content` (or have no `rawContent`) render the same as
+ * streamed ones.
  */
 export function extractComponentDirectiveFromMessage(
   message: AgentWidgetMessage
 ): ComponentDirective | null {
-  if (!message.rawContent) return null;
+  const source = selectDirectiveSource(message);
+  if (!source) return null;
 
   try {
-    const parsed = JSON.parse(message.rawContent);
+    const parsed = JSON.parse(source);
     if (
       typeof parsed === "object" &&
       parsed !== null &&
       "component" in parsed &&
-      typeof parsed.component === "string"
+      typeof (parsed as { component: unknown }).component === "string"
     ) {
+      const directive = parsed as { component: string; props?: unknown };
       return {
-        component: parsed.component,
-        props: (parsed.props && typeof parsed.props === "object" && parsed.props !== null
-          ? parsed.props
+        component: directive.component,
+        props: (directive.props && typeof directive.props === "object" && directive.props !== null
+          ? directive.props
           : {}) as Record<string, unknown>,
-        raw: message.rawContent
+        raw: source
       };
     }
   } catch {