@runtypelabs/persona 4.32.2 → 4.34.0

package/src/types.ts

@@ -616,7 +616,7 @@ export type AgentWidgetReplayedToolResult = {
  * from its own stored transcript there.
  */
 export type AgentWidgetRequestPayloadMessage = {
-  role: AgentWidgetMessageRole | "tool";
+  role: AgentWidgetModelMessageRole | "tool";
   content: MessageContent;
   createdAt: string;
   /** Optional assistant phase for backend adapters that replay provider history. */
@@ -1123,6 +1123,21 @@ export type AgentMessageMetadata = {
   };
 };
 
+/** Ordinary model context only; the serializer owns tool-call/result pairing. */
+export type AgentWidgetModelMessageProjection = Pick<AgentWidgetRequestPayloadMessage, "content" | "createdAt" | "phase"> & {
+  role: AgentWidgetModelMessageRole;
+};
+
+/** Synchronous, per-message conversion before any dispatch transport serializes history. */
+export type AgentWidgetModelMessageTransform = (context: {
+  /** Full UI transcript entry, including identity and human provenance. */
+  message: Readonly<AgentWidgetMessage>;
+  /** Resolved model content: contentParts > llmContent > rawContent > content. */
+  content: MessageContent;
+  /** Normal model projection; null for operator messages. Return null to omit. */
+  modelMessage: AgentWidgetModelMessageProjection | null;
+}) => AgentWidgetModelMessageProjection | null;
+
 export type AgentWidgetRequestMiddlewareContext = {
   payload: AgentWidgetRequestPayload;
   config: AgentWidgetConfig;
@@ -1391,7 +1406,7 @@ export type AgentWidgetMessageActionsConfig = {
 };
 
 /** Which roles a custom message action appears on. */
-export type AgentWidgetCustomMessageActionRole = "user" | "assistant";
+export type AgentWidgetCustomMessageActionRole = "user" | "assistant" | "operator";
 
 /** One host-contributed message action. */
 export type AgentWidgetCustomMessageAction = {
@@ -2213,10 +2228,13 @@ export type AgentWidgetArtifactsFeature = {
  *
  * - `"anchor-top"` (default): on send, scroll the user's message near the top
  *   of the viewport and hold it there while the response streams in beneath it
- *   (ChatGPT-style). When a turn has no user send to anchor to (a proactive
- *   greeting, an injected assistant message, a resubmit, or first-load
- *   streaming), it falls back to `"follow"` for that turn so content never
- *   streams in off-screen.
+ *   (ChatGPT-style). The anchor holds for the whole reply, even when the
+ *   message is taller than the viewport or tool calls push the answer below
+ *   the fold, until the reader scrolls away, jumps to the latest content with
+ *   the scroll-to-bottom control, or sends again. When a turn has no user send
+ *   to anchor to (a proactive greeting, an injected assistant message, a
+ *   resubmit, or first-load streaming), it falls back to `"follow"` for that
+ *   turn so content never streams in off-screen.
  * - `"follow"`: keep the newest content pinned to the bottom of the viewport,
  *   pausing when the user scrolls up and resuming when they return to the
  *   bottom. This was the default before 4.x.
@@ -2305,7 +2323,8 @@ export type AgentWidgetScrollBehaviorFeature = {
 
 /** Decorative glyph state. Hidden glyphs should pause host-owned animation. */
 export type AgentWidgetScrollToBottomIconState = {
-  activity: "idle" | "generating-below";
+  /** `"approval-below"`: a pending approval is below the fold and the turn waits on it. */
+  activity: "idle" | "generating-below" | "approval-below";
   visible: boolean;
   hovered: boolean;
   focused: boolean;
@@ -2345,6 +2364,15 @@ export type AgentWidgetScrollToBottomFeature = {
    * @default ""
    */
   label?: string;
+  /**
+   * Label shown while a pending approval sits below the fold. The control
+   * widens to a labelled pill with the approval's shield glyph, and the turn
+   * stays put until the reader jumps (anchor-top never scrolls them to it).
+   * Styled by `theme.components.scrollToBottom.approval`. Set to an empty
+   * string to keep the regular control.
+   * @default "Approval needed"
+   */
+  approvalLabel?: string;
   /** Glyph while a live response is arriving below. V4 defaults to arrow; V5 to dots. */
   streamingIndicator?: "dots" | "arrow";
   /** Visibility transition. V4 defaults to none; V5 to fade. Honors reduced motion. */
@@ -2773,6 +2801,31 @@ export type AgentWidgetStreamAnimationFeature = {
   plugins?: Record<string, StreamAnimationPlugin>;
 };
 
+/**
+ * Collapse long user messages behind a "Show more" / "Show less" toggle.
+ * Only the built-in user bubble collapses; `layout.messages.renderUserMessage`
+ * and plugin `renderMessage` output is left untouched.
+ */
+export type AgentWidgetUserMessageCollapseFeature = {
+  /**
+   * Clip a user bubble whose rendered content (text, markdown, code,
+   * attachments) is taller than `maxHeight`, with a bottom fade and a real
+   * toggle button. The full message stays in the DOM, so find-in-page, copy,
+   * selection and screen readers still reach it. Interim voice transcripts
+   * stay expanded and collapse once final. A reader's toggle is remembered
+   * per message for the life of the widget.
+   * @default false (`true` under `future.v5Defaults`)
+   */
+  enabled?: boolean;
+  /**
+   * Collapsed height in px. Content within about two lines (48px) of the
+   * limit is left expanded, so the toggle never hides just a line or two.
+   * The default shows about ten lines of bubble text.
+   * @default 240
+   */
+  maxHeight?: number;
+};
+
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
@@ -2789,6 +2842,8 @@ export type AgentWidgetFeatureFlags = {
   scrollToBottom?: AgentWidgetScrollToBottomFeature;
   /** Transcript scroll behavior during streamed responses. */
   scrollBehavior?: AgentWidgetScrollBehaviorFeature;
+  /** "Show more" collapse for long user messages. Off by default; on under `future.v5Defaults`. */
+  userMessageCollapse?: AgentWidgetUserMessageCollapseFeature;
   /** Collapsed transcript behavior for tool call rows. */
   toolCallDisplay?: AgentWidgetToolCallDisplayFeature;
   /** Collapsed transcript behavior for reasoning rows. */
@@ -7191,6 +7246,11 @@ export type AgentWidgetAvatarConfig = {
   userAvatar?: string;
   /** URL or emoji for assistant avatar */
   assistantAvatar?: string;
+  /**
+   * URL or emoji for operator (human takeover) avatar. Defaults to the letter
+   * "O" on a neutral fill.
+   */
+  operatorAvatar?: string;
 };
 
 /**
@@ -7246,7 +7306,10 @@ export type AgentWidgetMessageLayoutConfig = {
   groupConsecutive?: boolean;
   /** Width behavior for user-authored message rows */
   user?: AgentWidgetMessageRoleLayout;
-  /** Width behavior for assistant-authored message rows and assistant UI variants */
+  /**
+   * Width behavior for assistant-authored message rows and assistant UI
+   * variants. Operator rows sit on the same side and use it too.
+   */
   assistant?: AgentWidgetMessageRoleLayout;
   /**
    * Custom renderer for user messages
@@ -8398,6 +8461,8 @@ export type AgentWidgetConfig = {
    */
   getHeaders?: AgentWidgetHeadersFunction;
   copy?: {
+    /** Visible and accessible label for human operator replies. @default "Human operator" */
+    operatorLabel?: string;
     /** @deprecated Use `welcome.title`. */
     welcomeTitle?: string;
     /** @deprecated Use `welcome.subtitle`. */
@@ -8408,6 +8473,10 @@ export type AgentWidgetConfig = {
     sendButtonLabel?: string;
     /** Button label shown in text mode while a response is streaming. Default: "Stop". */
     stopButtonLabel?: string;
+    /** Toggle label on a collapsed long user message (`features.userMessageCollapse`). @default "Show more" */
+    showMoreLabel?: string;
+    /** Toggle label on an expanded long user message (`features.userMessageCollapse`). @default "Show less" */
+    showLessLabel?: string;
     /**
      * When false, the welcome / intro card is not shown above the message list.
      * @deprecated Use `welcome.variant: "none"`.
@@ -8590,6 +8659,16 @@ export type AgentWidgetConfig = {
    * See `docs/context-mentions-plan.md`.
    */
   contextMentions?: AgentWidgetContextMentionConfig;
+  /**
+   * Synchronous model-context conversion for each nonempty conversation entry.
+   * Runs on proxy, agent and client-token dispatch, after local-only notices and
+   * voice captions are excluded. By default operator messages are omitted;
+   * stateless adapters can explicitly map their historical human contributions
+   * into supported model roles. Do not replay contributions already owned by
+   * server history. This does not authorize steering, takeover or tool approval.
+   * Invalid return values fail dispatch. See docs/MESSAGE-INJECTION.md.
+   */
+  modelMessageTransform?: AgentWidgetModelMessageTransform;
   requestMiddleware?: AgentWidgetRequestMiddleware;
   actionParsers?: AgentWidgetActionParser[];
   actionHandlers?: AgentWidgetActionHandler[];
@@ -9093,7 +9172,25 @@ type ConfigPatch<T> = T extends (...args: never[]) => unknown
       ? { [K in keyof T]?: ConfigPatch<T[K]> }
       : T;
 
-export type AgentWidgetMessageRole = "user" | "assistant" | "system";
+/**
+ * Who authored a message.
+ *
+ * - `user`: the end user.
+ * - `assistant`: the agent (model output).
+ * - `system`: context for the model, rendered like an assistant row.
+ * - `operator`: a human speaking on the agent's side of the conversation, such
+ *   as a support agent who has taken over the thread. It renders on the
+ *   assistant's side with its own bubble style (`theme.components.message.operator`).
+ *   Operator messages are omitted from model requests by default. A stateless
+ *   adapter can explicitly convert them with `modelMessageTransform`.
+ */
+export type AgentWidgetMessageRole = "user" | "assistant" | "system" | "operator";
+
+/**
+ * Roles that reach a model request. Human operator UI entries must be explicitly
+ * converted to a supported model role by an adapter.
+ */
+export type AgentWidgetModelMessageRole = Exclude<AgentWidgetMessageRole, "operator">;
 
 export type AgentWidgetReasoning = {
   id: string;
@@ -9216,11 +9313,18 @@ export type AgentWidgetTurnActivityConfig = {
   }) => HTMLElement | string | null | undefined;
 };
 
+/** Display provenance, supplied by the host; never an authorization credential. */
+export type AgentWidgetMessageAuthor = {
+  id?: string;
+  displayName?: string;
+  kind?: "human" | "ai" | "system";
+};
+
 /**
  * Represents a message in the chat conversation.
  *
  * @property id - Unique message identifier
- * @property role - Message role: "user", "assistant", or "system"
+ * @property role - Message role: "user", "assistant", "system", or "operator"
  * @property content - Message text content (for display)
  * @property contentParts - Original multi-modal content parts (for API requests)
  * @property createdAt - ISO timestamp when message was created
@@ -9234,6 +9338,8 @@ export type AgentWidgetTurnActivityConfig = {
  *                      Useful for implementing voice-specific behaviors like auto-reactivation.
  */
 export type AgentWidgetMessage = {
+  /** Preserved by injection, history and persistence; not sent to models automatically. */
+  author?: AgentWidgetMessageAuthor;
   /** Opt-in whole-turn presentation metadata. Does not change model-visible content. */
   turnActivity?: AgentWidgetTurnActivity;
   id: string;
@@ -9388,10 +9494,13 @@ export type AgentWidgetMessage = {
  * }
  */
 export type InjectMessageOptions = {
+  /** Host-supplied display provenance. Does not grant model or backend authority. */
+  author?: AgentWidgetMessageAuthor;
   /** Mark assistant content as dispatch failure detail for `errorDisplay`. */
   dispatchError?: boolean;
   /**
-   * Message role: "assistant", "user", or "system"
+   * Message role: "assistant", "user", "system", or "operator". Operator
+   * messages are omitted from requests unless modelMessageTransform converts them.
    */
   role: AgentWidgetMessageRole;
 

package/src/ui.ask-user-question-plugin.test.ts

@@ -689,3 +689,157 @@ describe("renderAskUserQuestion plugin hook", () => {
     controller.destroy();
   });
 });
+
+describe("typing indicator while ask_user_question arguments stream", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  // Streaming transcript updates render once per animation frame; queue the
+  // frames so each injection can be rendered synchronously.
+  let frames = new Map<number, (time: number) => void>();
+  let nextFrameId = 1;
+  const renderFrame = () => {
+    const pending = [...frames.values()];
+    frames.clear();
+    pending.forEach((callback) => callback(0));
+  };
+
+  const mountStreaming = async (config: Record<string, unknown> = {}) => {
+    frames = new Map();
+    vi.stubGlobal("requestAnimationFrame", (callback: (time: number) => void) => {
+      const id = nextFrameId++;
+      frames.set(id, callback);
+      return id;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
+    global.fetch = vi.fn().mockImplementation(
+      () => new Promise(() => {})
+    ) as unknown as typeof fetch;
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      ...config,
+    } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+    controller.submitMessage("hello");
+    await Promise.resolve();
+    await Promise.resolve();
+    return { mount, controller };
+  };
+
+  // Stamped in the future so the rows sort after the submitted user message.
+  const sequence = Date.now() + 60_000;
+  const createdAt = new Date(sequence).toISOString();
+  const fullArgs = {
+    questions: [
+      { question: "Which audience?", options: [{ label: "Hobbyists" }, { label: "Pros" }] },
+    ],
+  };
+
+  const injectStreamingAsk = (
+    controller: ReturnType<typeof createAgentExperience>,
+    { chunks = [], args }: { chunks?: string[]; args?: unknown } = {}
+  ) => {
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "ask-1",
+        role: "assistant",
+        content: "",
+        createdAt,
+        sequence,
+        streaming: true,
+        variant: "tool",
+        toolCall: { id: "ask-1", name: "ask_user_question", status: "running", chunks, args },
+      },
+    });
+    renderFrame();
+  };
+
+  const injectAwaitingAsk = (controller: ReturnType<typeof createAgentExperience>) => {
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "ask-1",
+        role: "assistant",
+        content: "",
+        createdAt,
+        sequence,
+        streaming: false,
+        variant: "tool",
+        toolCall: { id: "ask-1", name: "ask_user_question", status: "complete", chunks: [], args: fullArgs },
+        agentMetadata: { executionId: "exec_123", awaitingLocalTool: true },
+      },
+    });
+    renderFrame();
+  };
+
+  const typingIndicator = (mount: HTMLElement) =>
+    mount.querySelector('[data-typing-indicator="true"]');
+  const askSheet = (mount: HTMLElement) => mount.querySelector("[data-persona-ask-sheet-for]");
+
+  it("keeps the dots until the built-in sheet mounts when no plugin renders the question", async () => {
+    const { mount, controller } = await mountStreaming();
+
+    injectStreamingAsk(controller);
+    expect(askSheet(mount)).toBeNull();
+    expect(typingIndicator(mount)).not.toBeNull();
+
+    injectAwaitingAsk(controller);
+    expect(askSheet(mount)).not.toBeNull();
+    expect(typingIndicator(mount)).toBeNull();
+
+    controller.destroy();
+  });
+
+  it("keeps the dots while the plugin returns null for a partial payload", async () => {
+    const plugin: AgentWidgetPlugin = {
+      id: "partial-asker",
+      renderAskUserQuestion: ({ payload }) => {
+        if (!payload?.questions?.[0]?.options?.length) return null;
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "partial-ask");
+        return root;
+      },
+    };
+    const { mount, controller } = await mountStreaming({ plugins: [plugin] });
+
+    injectStreamingAsk(controller, { chunks: ['{"questions":[{"question":"Which'] });
+    expect(mount.querySelector('[data-test-id="partial-ask"]')).toBeNull();
+    expect(askSheet(mount)).toBeNull();
+    expect(typingIndicator(mount)).not.toBeNull();
+
+    injectStreamingAsk(controller, { args: fullArgs });
+    expect(mount.querySelector('[data-test-id="partial-ask"]')).not.toBeNull();
+    expect(typingIndicator(mount)).toBeNull();
+
+    controller.destroy();
+  });
+
+  it.each([true, false])("hides the dots as soon as the plugin renders a bubble (showToolCalls=%s)", async (showToolCalls) => {
+    const plugin: AgentWidgetPlugin = {
+      id: "eager-asker",
+      renderAskUserQuestion: () => {
+        const root = document.createElement("div");
+        root.setAttribute("data-test-id", "eager-ask");
+        return root;
+      },
+    };
+    const { mount, controller } = await mountStreaming({
+      plugins: [plugin],
+      features: { showToolCalls },
+    });
+
+    injectStreamingAsk(controller);
+    expect(mount.querySelector('[data-test-id="eager-ask"]')).not.toBeNull();
+    expect(typingIndicator(mount)).toBeNull();
+
+    controller.destroy();
+  });
+});