@runtypelabs/persona 4.32.2 → 4.33.0

package/src/components/message-bubble.ts

@@ -2,6 +2,7 @@ import { getLoadingLabelRuntimeSync } from "../loading-label-runtime-loader";
 import { createElement, createNode } from "../utils/dom";
 import {
   AgentWidgetMessage,
+  AgentWidgetMessageRole,
   AgentWidgetMessageLayoutConfig,
   AgentWidgetAvatarConfig,
   AgentWidgetTimestampConfig,
@@ -577,40 +578,47 @@ export const renderLoadingIndicatorWithFallback = (
  */
 const createAvatar = (
   avatarConfig: AgentWidgetAvatarConfig,
-  role: "user" | "assistant"
+  role: AgentWidgetMessageRole
 ): HTMLElement => {
   const avatar = createElement(
     "div",
     "persona-flex-shrink-0 persona-w-8 persona-h-8 persona-rounded-full persona-flex persona-items-center persona-justify-center persona-text-sm"
   );
 
-  const avatarContent = role === "user" 
-    ? avatarConfig.userAvatar 
-    : avatarConfig.assistantAvatar;
+  const isOperator = role === "operator";
+  const avatarContent = role === "user"
+    ? avatarConfig.userAvatar
+    : isOperator
+      ? avatarConfig.operatorAvatar
+      : avatarConfig.assistantAvatar;
+
+  // The operator avatar is a neutral outlined chip, apart from the solid
+  // user and assistant fills.
+  const applyFill = () => {
+    avatar.classList.add(
+      ...(isOperator
+        ? ["persona-bg-persona-container", "persona-text-persona-text", "persona-border"]
+        : [role === "user" ? "persona-bg-persona-accent" : "persona-bg-persona-primary", "persona-text-white"])
+    );
+  };
 
   if (avatarContent) {
     // Check if it's a URL or emoji/text
     if (avatarContent.startsWith("http") || avatarContent.startsWith("/") || avatarContent.startsWith("data:")) {
       const img = createElement("img") as HTMLImageElement;
       img.src = avatarContent;
-      img.alt = role === "user" ? "User" : "Assistant";
+      img.alt = role === "user" ? "User" : isOperator ? "Operator" : "Assistant";
       img.className = "persona-w-full persona-h-full persona-rounded-full persona-object-cover";
       avatar.appendChild(img);
     } else {
       // Emoji or text
       avatar.textContent = avatarContent;
-      avatar.classList.add(
-        role === "user" ? "persona-bg-persona-accent" : "persona-bg-persona-primary",
-        "persona-text-white"
-      );
+      applyFill();
     }
   } else {
     // Default avatar
-    avatar.textContent = role === "user" ? "U" : "A";
-    avatar.classList.add(
-      role === "user" ? "persona-bg-persona-accent" : "persona-bg-persona-primary",
-      "persona-text-white"
-    );
+    avatar.textContent = role === "user" ? "U" : isOperator ? "O" : "A";
+    applyFill();
   }
 
   return avatar;
@@ -644,13 +652,32 @@ const createTimestamp = (
   return timestamp;
 };
 
+/** Assistant color utilities an operator bubble replaces with its own tokens. */
+const OPERATOR_DROPPED_CLASSES = new Set([
+  "persona-bg-persona-container",
+  "persona-text-persona-text",
+  "persona-border-persona-message-border",
+]);
+
 /**
  * Get bubble classes based on layout preset
  */
 export const getBubbleClasses = (
-  role: "user" | "assistant" | "system",
+  role: AgentWidgetMessageRole,
   layout: AgentWidgetMessageLayoutConfig["layout"] = "bubble"
 ): string[] => {
+  // Operator bubbles share the assistant's geometry per layout; only the role
+  // class changes, and the colors come from the operator tokens instead.
+  if (role === "operator") {
+    const classes = getBubbleClasses("assistant", layout).flatMap((name) =>
+      name === "persona-message-assistant-bubble"
+        ? ["persona-message-operator-bubble"]
+        : OPERATOR_DROPPED_CLASSES.has(name) ? [] : [name]
+    );
+    // Flat drops the assistant's fill, not the operator's: the operator keeps
+    // its background, so it needs the minimal layout's side padding.
+    return layout === "flat" ? [...classes, "persona-px-3"] : classes;
+  }
   const baseClasses = ["persona-message-bubble"];
 
   switch (layout) {
@@ -763,7 +790,7 @@ export const applyBubbleGeometry = (
   tokens?: MessageGeometryTokens
 ): void => {
   if (!tokens) return;
-  const key = role === "user" ? "user" : "assistant";
+  const key = role === "user" || role === "operator" ? role : "assistant";
   const preset = BUBBLE_GEOMETRY_DEFAULTS[layout ?? "bubble"] ?? BUBBLE_GEOMETRY_DEFAULTS.bubble;
   if (tokens.padding) {
     bubble.style.padding = `var(--persona-message-${key}-padding, ${preset.padding})`;
@@ -787,13 +814,14 @@ export const customMessageActionDataAction = (id: string): string =>
 
 /**
  * Host-contributed actions this message's role qualifies for. Assistant-only by
- * default, matching every built-in except edit and quote.
+ * default, matching every built-in except edit and quote; an action reaches
+ * operator messages only when its `roles` lists `"operator"`.
  */
 export const customMessageActionsForRole = (
   actionsConfig: AgentWidgetMessageActionsConfig | undefined,
   role: AgentWidgetMessage["role"]
 ): AgentWidgetCustomMessageAction[] => {
-  if (role !== "user" && role !== "assistant") return [];
+  if (role !== "user" && role !== "assistant" && role !== "operator") return [];
   return (actionsConfig?.custom ?? []).filter((action) =>
     (action.roles ?? ["assistant"]).includes(role)
   );
@@ -1000,21 +1028,33 @@ export const createStandardBubble = (
   bubble.id = `bubble-${message.id}`;
   bubble.setAttribute("data-message-id", message.id);
 
-  bubble.setAttribute("data-persona-theme-zone", message.role === "user" ? "user-message" : "assistant-message");
+  const isOperator = message.role === "operator";
+  // The V5 operator is outlined, not filled, so every layout needs the border
+  // style that only the bubble layout's classes carry.
+  if (isOperator && options?.widgetConfig?.future?.v5Defaults === true) bubble.classList.add("persona-border");
+  bubble.setAttribute(
+    "data-persona-theme-zone",
+    message.role === "user" ? "user-message" : isOperator ? "operator-message" : "assistant-message"
+  );
 
   const defaultMessageTokens = resolveThemeDefaults(options?.widgetConfig?.future).components.message;
   const messageTokens = options?.widgetConfig?.theme?.components?.message;
+  const darkMessageTokens = options?.widgetConfig?.darkTheme?.components?.message;
   applyBubbleGeometry(
     bubble,
     message.role,
     layout,
     message.role === "user"
-      ? { ...defaultMessageTokens.user, ...messageTokens?.user, ...options?.widgetConfig?.darkTheme?.components?.message?.user }
-      : { ...defaultMessageTokens.assistant, ...messageTokens?.assistant, ...options?.widgetConfig?.darkTheme?.components?.message?.assistant }
+      ? { ...defaultMessageTokens.user, ...messageTokens?.user, ...darkMessageTokens?.user }
+      : isOperator
+        ? { ...defaultMessageTokens.operator, ...messageTokens?.operator, ...darkMessageTokens?.operator }
+        : { ...defaultMessageTokens.assistant, ...messageTokens?.assistant, ...darkMessageTokens?.assistant }
   );
 
-  // Apply component-level color overrides via CSS variables
-  if (layout === "flat") {
+  // Apply component-level color overrides via CSS variables. Flat clears the
+  // user and assistant fills; an operator keeps its own background token so it
+  // stays apart from the assistant prose on the same side.
+  if (layout === "flat" && !isOperator) {
     bubble.style.backgroundColor = "transparent";
     bubble.style.color =
       message.role === "user"
@@ -1026,6 +1066,23 @@ export const createStandardBubble = (
   } else if (message.role === "assistant") {
     bubble.style.backgroundColor = 'var(--persona-message-assistant-bg, var(--persona-container))';
     bubble.style.color = 'var(--persona-message-assistant-text, var(--persona-text))';
+  } else if (isOperator) {
+    bubble.style.backgroundColor = 'var(--persona-components-message-operator-background, var(--persona-container))';
+    bubble.style.color = 'var(--persona-components-message-operator-text, var(--persona-text))';
+  }
+
+  if (isOperator) {
+    const authorLabel = createElement("div", "persona-message-author persona-text-xs persona-font-medium persona-mb-1");
+    const configuredLabel = options?.widgetConfig?.copy?.operatorLabel;
+    const operatorLabel = typeof configuredLabel === "string" && configuredLabel.trim()
+      ? configuredLabel.trim() : "Human operator";
+    const displayName = typeof message.author?.displayName === "string"
+      ? message.author.displayName.trim() : "";
+    authorLabel.textContent = displayName ? `${displayName} · ${operatorLabel}` : operatorLabel;
+    // A visible name is also the accessible name for the human-authored group.
+    bubble.setAttribute("role", "group");
+    bubble.setAttribute("aria-label", authorLabel.textContent);
+    bubble.appendChild(authorLabel);
   }
 
   const imageParts = getMessageImageParts(message);
@@ -1293,14 +1350,15 @@ export const createStandardBubble = (
     bubble.appendChild(createStopReasonNotice(message.stopReason, stopReasonNoticeText));
   }
 
-  // Add message actions for assistant messages (only when not streaming and has content)
+  // Add message actions for assistant and operator messages (only when not
+  // streaming and has content). Operator rows get copy and opted-in custom
+  // actions only: feedback, read-aloud and regenerate are about model output.
   const shouldShowActions =
-    message.role === "assistant" &&
+    (message.role === "assistant" || isOperator) &&
     !message.streaming &&
     // A voice caption (the voice model's own speech) is display-only.
     !message.voiceCaption &&
-    message.content &&
-    message.content.trim() &&
+    (messageContentText.length > 0 || (isOperator && customMessageActionsForRole(actionsConfig, "operator").length > 0)) &&
     actionsConfig?.enabled !== false;
 
   // User bubbles carry actions only when this message is edit- or quote-eligible;
@@ -1321,7 +1379,18 @@ export const createStandardBubble = (
       shouldShowUserActions
         ? // A user bubble never hosts the assistant-only controls.
           { ...actionsConfig, showCopy: false, showUpvote: false, showDownvote: false, showReadAloud: false }
-        : actionsConfig,
+        : isOperator
+          ? {
+              ...actionsConfig,
+              showCopy: messageContentText.length > 0 && actionsConfig.showCopy !== false,
+              showUpvote: false,
+              showDownvote: false,
+              showReadAloud: false,
+              showRegenerate: false,
+              showEdit: false,
+              showQuote: false,
+            }
+          : actionsConfig,
       actionCallbacks,
       eligibility,
       options?.widgetConfig?.future?.v5Defaults === true && actionsConfig.visibility === undefined

package/src/defaults-parity.test.ts

@@ -160,6 +160,20 @@ describe("4.22.0 defaults parity (flag off)", () => {
       expect(actual.themeCssVariables[key], key).toBe(value);
       delete resolvedActual.themeCssVariables[key];
     }
+    // Operator bubbles only render for messages that use the operator role,
+    // so every token they emit is additive and none may exist in the baseline.
+    const additivePrefixes = [
+      "--persona-components-message-operator-",
+      "--persona-message-operator-",
+    ];
+    expect(actual.themeCssVariables["--persona-components-message-operator-background"]).toBe(
+      "color-mix(in srgb, var(--persona-primary) 6%, var(--persona-container))"
+    );
+    for (const key of Object.keys(resolvedActual.themeCssVariables)) {
+      if (!additivePrefixes.some((prefix) => key.startsWith(prefix))) continue;
+      expect(baseline.themeCssVariables).not.toHaveProperty(key);
+      delete resolvedActual.themeCssVariables[key];
+    }
     // Deliberately lengthen hover timing in both V4 and V5 without rewriting
     // the historical fixture. Keyboard focus and the scan window are unchanged.
     expect(baseline.mergedDefaultConfig.tooltip.delayMs).toBe(200);

package/src/index-core.ts

@@ -5,6 +5,9 @@ import {
 } from "./runtime/init";
 
 export type {
+  AgentWidgetMessageAuthor,
+  AgentWidgetModelMessageTransform,
+  AgentWidgetModelMessageProjection,
   AgentWidgetDictationConfig,
   DictationProviderConfig,
   DictationPhase,
@@ -46,6 +49,8 @@ export type {
   ArtifactConfigPayload,
   AgentWidgetInitOptions,
   AgentWidgetMessage,
+  AgentWidgetMessageRole,
+  AgentWidgetModelMessageRole,
   AgentWidgetTurnActivity,
   AgentWidgetTurnActivityConfig,
   AgentWidgetLauncherConfig,
@@ -594,6 +599,8 @@ export type {
   SemanticSpacing,
   SemanticTypography,
   ComponentTokens,
+  MessageTokens,
+  MessageGeometryTokens,
   ComposerOverflowMenuTokens,
   TextStyleTokens,
   AttachmentTokens,

package/src/session.resubmit-from.test.ts

@@ -327,3 +327,30 @@ describe("resubmitFrom retry payload fidelity per transport", () => {
     expect(bodies[0].submitMode).toBeUndefined();
   });
 });
+
+describe("human operator resubmission boundary", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    global.fetch = vi.fn(async () => streamResponse()) as unknown as typeof fetch;
+  });
+  it.each(["retry", "edit"] as const)("refuses %s before a human contribution without cancelling or truncating", reason => {
+    const { session, emits } = makeSession();
+    seedTurn(session);
+    session.injectMessage({ id: "human", role: "operator", content: "Refund confirmed", author: { id: "sam", displayName: "Sam", kind: "human" } });
+    const snapshot = session.getMessages();
+    const cancel = vi.spyOn(session, "cancel");
+    emits.length = 0;
+    expect(session.resubmitFrom("u1", { reason, ...(reason === "edit" && { replacement: { text: "Changed", mentionRefs: [], options: {} } }) })).toBe(false);
+    expect(session.getMessages()).toEqual(snapshot);
+    expect(cancel).not.toHaveBeenCalled();
+    expect(emits).toHaveLength(0);
+  });
+
+  it("allows a fresh user turn after the human contribution", () => {
+    const { session } = makeSession();
+    session.injectMessage({ id: "human", role: "operator", content: "Refund confirmed" });
+    session.injectUserMessage({ id: "after", content: "When will it arrive?" });
+    expect(session.resubmitFrom("after", { reason: "retry" })).toBe(true);
+    expect(session.getMessages().some(message => message.id === "human")).toBe(true);
+  });
+});

package/src/session.test.ts

@@ -182,6 +182,16 @@ describe('AgentWidgetSession - Message Injection', () => {
     });
   });
 
+  describe('operator role', () => {
+    it('injects an operator message with its own id prefix', () => {
+      const result = session.injectMessage({ role: 'operator', content: 'Sam from support here.' });
+
+      expect(result.role).toBe('operator');
+      expect(result.id).toMatch(/^operator-/);
+      expect(messages.map((message) => message.role)).toEqual(['operator']);
+    });
+  });
+
   describe('message ordering', () => {
     it('should maintain chronological order', () => {
       session.injectMessage({

package/src/session.ts

@@ -68,7 +68,7 @@ import type {
   ComposerResubmitOptions
 } from "./types";
 import { applyQuoteToContent } from "./utils/composer-quote";
-import { findUserTurnBoundary } from "./utils/resubmit-turn";
+import { canResubmitUserMessage, findUserTurnBoundary } from "./utils/resubmit-turn";
 import { extractComponentDirectiveFromMessage } from "./utils/component-middleware";
 import type { MentionSubmitBundle } from "./utils/context-mention-manager";
 import type { VisitorStore, VisitorStoreChange } from "./utils/visitor-store";
@@ -156,6 +156,7 @@ const CONNECTION_CONFIG_KEYS = [
   "parserType",
   "contextProviders",
   "requestMiddleware",
+  "modelMessageTransform",
   "customFetch",
   "backgroundConversations",
   "parseSSEEvent",
@@ -2500,7 +2501,7 @@ export class AgentWidgetSession {
         ? generateUserMessageId()
         : role === "assistant"
           ? generateAssistantMessageId()
-          : `system-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+          : `${role === "operator" ? "operator" : "system"}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
 
     return {
       id: messageId,
@@ -2515,7 +2516,8 @@ export class AgentWidgetSession {
       ...(voiceProcessing !== undefined && { voiceProcessing }),
       ...(voiceCaption && { voiceCaption }),
       ...(rawContent !== undefined && { rawContent }),
-      ...(options.dispatchError !== undefined && { dispatchError: options.dispatchError })
+      ...(options.dispatchError !== undefined && { dispatchError: options.dispatchError }),
+      ...(options.author !== undefined && { author: { ...options.author } })
     };
 
   }
@@ -3015,14 +3017,15 @@ export class AgentWidgetSession {
    * the new attempt gets fresh message ids.
    *
    * Returns false when the id is unknown, is not a user message, or the rebuilt
-   * turn would carry no content; nothing is truncated in that case.
+   * turn would carry no content, or truncation would remove an operator reply;
+   * nothing is truncated in those cases.
    */
   public resubmitFrom(
     messageId: string,
     options: ComposerResubmitOptions
   ): boolean {
     const boundary = findUserTurnBoundary(this.messages, messageId);
-    if (!boundary) return false;
+    if (!boundary || !canResubmitUserMessage(this.messages, messageId)) return false;
 
     // Operate on the STORED message, never a caller-held object: appendMessage
     // keeps a copy (see `ensureSequence`), so the array entry is the only ref

package/src/styles/widget.css

@@ -2171,6 +2171,13 @@
   );
 }
 
+.persona-message-row[data-message-role="operator"] > * {
+  max-width: var(
+    --persona-message-row-max-width,
+    var(--persona-message-operator-max-width, var(--persona-message-assistant-max-width, 85%))
+  );
+}
+
 .persona-message-row[data-message-width="content"] > * {
   flex: 0 1 auto;
 }
@@ -3086,6 +3093,18 @@
   box-shadow: var(--persona-message-assistant-shadow, 0 1px 2px 0 rgb(0 0 0 / 0.05));
 }
 
+/* Operator bubble: a human on the agent's side (role "operator"). Renders on
+   the assistant's side; V4 tints the container with the primary, V5 outlines it. */
+.persona-message-operator-bubble {
+  border-radius: var(--persona-components-message-operator-borderRadius, var(--persona-radius-lg, 0.5rem));
+  border-color: var(--persona-components-message-operator-border, var(--persona-border, #e5e7eb));
+  border-width: var(--persona-components-message-operator-borderWidth, 1px);
+}
+
+[data-persona-root] .persona-message-operator-bubble.persona-shadow-sm {
+  box-shadow: var(--persona-components-message-operator-shadow, 0 1px 2px 0 rgb(0 0 0 / 0.05));
+}
+
 [data-persona-root] .persona-message-user-bubble.persona-shadow-sm {
   box-shadow: var(--persona-message-user-shadow);
 }
@@ -3244,7 +3263,8 @@
   text-decoration: underline;
 }
 
-[data-persona-root] .persona-message-assistant-bubble a {
+[data-persona-root] .persona-message-assistant-bubble a,
+[data-persona-root] .persona-message-operator-bubble a {
   color: var(--persona-md-link-color, var(--persona-accent, #0f0f0f));
 }
 
@@ -3329,6 +3349,8 @@
 
 .persona-message-assistant-bubble p,
 .persona-message-assistant-bubble li,
+.persona-message-operator-bubble p,
+.persona-message-operator-bubble li,
 .persona-error-detail p,
 .persona-error-detail li {
   color: inherit;

package/src/theme-reference.ts

@@ -144,6 +144,8 @@ export const THEME_TOKEN_DOCS = {
         user: 'background, text, borderRadius, shadow.',
         assistant:
           'background, text, borderRadius, border (optional), shadow (optional).',
+        operator:
+          'Human operator bubble (role "operator", e.g. a support takeover), on the assistant side. background (default: container tinted 6% with the primary), text (semantic.colors.text), borderRadius, border (container tinted 20% with the primary), borderWidth (1px), shadow, plus padding, maxWidth, fontSize, fontFamily, lineHeight. V5 outlines it instead: transparent background, semantic.colors.border border.',
       },
       markdown: {
         description: 'Markdown rendering in messages and artifact pane.',
@@ -325,7 +327,7 @@ export const THEME_TOKEN_DOCS = {
       header:
         '"default" | "minimal". Options: showIcon, showTitle, showSubtitle, showCloseButton, showClearChat.',
       messages:
-        '"bubble" | "flat" | "minimal". Options: groupConsecutive, avatar (show, position, userAvatar, assistantAvatar), timestamp (show, position).',
+        '"bubble" | "flat" | "minimal". Options: groupConsecutive, avatar (show, position, userAvatar, assistantAvatar, operatorAvatar), timestamp (show, position, format).',
     },
     statusIndicator: {
       description: 'Status text shown below the composer.',

package/src/types/theme.ts

@@ -580,6 +580,27 @@ export interface MessageTokens {
     /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
     shadow?: string;
   };
+  /**
+   * Operator bubble: a human speaking on the agent's side (`role: "operator"`).
+   * Renders on the assistant's side. Defaults tint the container with the
+   * theme primary (`--persona-primary`), so `brand` themes follow without
+   * extra config. Geometry keys fall back to the layout preset, not to the
+   * assistant's geometry.
+   */
+  operator?: MessageGeometryTokens & {
+    /** @default "color-mix(in srgb, var(--persona-primary) 6%, var(--persona-container))" */
+    background?: TokenReference<'color'>;
+    /** @default semantic.colors.text */
+    text?: TokenReference<'color'>;
+    /** @default palette.radius.lg */
+    borderRadius?: TokenReference<'radius'>;
+    /** @default "color-mix(in srgb, var(--persona-primary) 20%, var(--persona-container))" */
+    border?: TokenReference<'color'>;
+    /** Border width; set to 0px to drop it. @default "1px" */
+    borderWidth?: string;
+    /** Operator bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+    shadow?: string;
+  };
   /** Border color between messages in the thread. */
   border?: TokenReference<'color'>;
 }

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 = {
@@ -7191,6 +7206,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 +7266,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 +8421,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`. */
@@ -8590,6 +8615,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 +9128,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 +9269,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 +9294,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 +9450,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;