@runtypelabs/persona 4.32.1 → 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/index-global.ts

@@ -37,12 +37,13 @@ export type { StreamAnimationPlugin, StreamAnimationContext } from "./types";
 // ---------------------------------------------------------------------------
 
 import { setWebMcpPolyfillLoader } from "./webmcp-bridge";
+import { pinCdnRelease } from "./utils/cdn-release";
 
 // Capture at module-evaluation time: `document.currentScript` is null once
 // execution leaves the script's initial synchronous run.
 const widgetScriptSrc: string | null =
   typeof document !== "undefined"
-    ? ((document.currentScript as HTMLScriptElement | null)?.src ?? null)
+    ? pinCdnRelease((document.currentScript as HTMLScriptElement | null)?.src ?? "") || null
     : null;
 
 /**

package/src/install.test.ts

@@ -10,6 +10,7 @@
 // `vi.runAllTimersAsync()` to drive it forward deterministically.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { version } from "../package.json";
 
 const PERSONA_EVENTS = [
   "persona:script-load",
@@ -464,11 +465,11 @@ describe("install.ts: CDN base derivation", () => {
     return { cssHref: css?.href ?? null, scripts };
   }
 
-  it("derives asset URLs from the installer's own script directory (first-party CDN)", async () => {
+  it("pins first-party latest installer assets to the embedded release", async () => {
     setCurrentScript("https://cdn.runtype.com/persona/latest/install.global.js");
     const { cssHref, scripts } = await installedUrls({});
-    expect(cssHref).toBe("https://cdn.runtype.com/persona/latest/widget.css");
-    expect(scripts).toContain("https://cdn.runtype.com/persona/latest/launcher.global.js");
+    expect(cssHref).toBe(`https://cdn.runtype.com/persona/${version}/widget.css`);
+    expect(scripts).toContain(`https://cdn.runtype.com/persona/${version}/launcher.global.js`);
   });
 
   it("keeps npm-CDN siblings on the installer's own pinned range (no @latest skew)", async () => {
@@ -478,13 +479,13 @@ describe("install.ts: CDN base derivation", () => {
     expect(scripts).toContain("https://cdn.jsdelivr.net/npm/@runtypelabs/persona@4/dist/launcher.global.js");
   });
 
-  it("the full bundle URL follows the installer directory on the eager path", async () => {
+  it("pins the full bundle on the eager first-party latest path", async () => {
     setCurrentScript("https://cdn.runtype.com/persona/latest/install.global.js");
     markCssLoaded();
     await install({ config: { apiUrl: "/api", launcher: { enabled: false } } });
     await flush();
     const scripts = Array.from(document.head.querySelectorAll("script")).map((s) => s.src);
-    expect(scripts).toContain("https://cdn.runtype.com/persona/latest/index.global.js");
+    expect(scripts).toContain(`https://cdn.runtype.com/persona/${version}/index.global.js`);
   });
 
   it("falls back to jsDelivr@latest when currentScript is unavailable", async () => {

package/src/install.ts

@@ -4,7 +4,7 @@
  * if configuration is provided via window.siteAgentConfig
  */
 
-export {};
+import { pinCdnRelease } from "./utils/cdn-release";
 
 import type { BrandConfig } from "./types/theme";
 import { delayInstallLoading } from "./utils/install-loading";
@@ -201,7 +201,7 @@ declare global {
   const getInstallerBase = (): string | null => {
     if (!installerSrc) return null;
     try {
-      const url = new URL(installerSrc, document.baseURI);
+      const url = new URL(pinCdnRelease(installerSrc), document.baseURI);
       if (url.protocol !== "http:" && url.protocol !== "https:") return null;
       return url.origin + url.pathname.slice(0, url.pathname.lastIndexOf("/"));
     } catch {

package/src/launcher-global.ts

@@ -24,6 +24,7 @@ import { createLauncherSurface } from "./components/launcher";
 import { applyLauncherThemeVariables } from "./utils/theme";
 import { DEFAULT_LAUNCHER_CONFIG, DEFAULT_LAUNCHER_V5 } from "./defaults";
 import { setIconsExtraLoader } from "./icons-extra-loader";
+import { pinCdnRelease } from "./utils/cdn-release";
 import type { AgentWidgetConfig } from "./types";
 
 // ---------------------------------------------------------------------------
@@ -33,7 +34,7 @@ import type { AgentWidgetConfig } from "./types";
 // ---------------------------------------------------------------------------
 const launcherScriptSrc: string | null =
   typeof document !== "undefined"
-    ? ((document.currentScript as HTMLScriptElement | null)?.src ?? null)
+    ? pinCdnRelease((document.currentScript as HTMLScriptElement | null)?.src ?? "") || null
     : null;
 
 setIconsExtraLoader(() => {

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({
@@ -1070,6 +1080,47 @@ describe('AgentWidgetSession - dispatch error fallback', () => {
     expect(session.getStatus()).toBe('idle');
   });
 
+  it('does not blame the backend for an internal stream TypeError after a successful response', async () => {
+    const response = new Response('data: {}\n\n', { headers: { 'Content-Type': 'text/event-stream' } });
+    const fault = new TypeError('t.streamGeneration is not a function');
+    vi.spyOn(response.body!, 'getReader').mockImplementation(() => { throw fault; });
+    global.fetch = vi.fn().mockResolvedValue(response);
+    const errors: Error[] = [];
+    const session = new AgentWidgetSession({ apiUrl: 'http://example.invalid/chat' }, {
+      onMessagesChanged: () => {}, onStatusChanged: () => {}, onStreamingChanged: () => {},
+      onError: error => errors.push(error),
+    });
+    await session.sendMessage('Hello');
+    const content = lastAssistantMessage(session)?.content;
+    expect(content).toContain('the chat encountered an unexpected error');
+    expect(content).toContain('t.streamGeneration is not a function');
+    expect(content).not.toContain('backend');
+    expect(content).not.toContain("couldn't reach");
+    expect(errors).toContain(fault);
+    expect(session.isStreaming()).toBe(false);
+  });
+
+  it.each(['Failed to fetch', 'Load failed', 'NetworkError when attempting to fetch resource.', 'fetch failed'])(
+    'recognizes the browser fetch TypeError: %s', async (message) => {
+      failFetchWith(new TypeError(message));
+      const session = new AgentWidgetSession({ apiUrl: 'http://example.invalid/chat' }, {
+        onMessagesChanged: () => {}, onStatusChanged: () => {}, onStreamingChanged: () => {},
+      });
+      await session.sendMessage('Hello');
+      expect(lastAssistantMessage(session)?.content).toContain("I couldn't reach the assistant");
+    },
+  );
+
+  it('describes a server rejection without claiming the server was unreachable', async () => {
+    global.fetch = vi.fn().mockResolvedValue(new Response('unavailable', { status: 503 }));
+    const session = new AgentWidgetSession({ apiUrl: 'http://example.invalid/chat' }, {
+      onMessagesChanged: () => {}, onStatusChanged: () => {}, onStreamingChanged: () => {},
+    });
+    await session.sendMessage('Hello');
+    expect(lastAssistantMessage(session)?.content).toContain("chat service couldn't complete the request");
+    expect(lastAssistantMessage(session)?.content).toContain('_Details: Chat backend request failed: 503_');
+  });
+
   it('uses a static errorMessage override verbatim', async () => {
     failFetchWith(new Error('boom'));
     const session = new AgentWidgetSession(

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",
@@ -265,10 +266,9 @@ export class SessionHistoryError extends Error {
 }
 
 /**
- * Build the user-facing detail shown when a dispatch fails. This fires on real network/server errors
- * (connection refused, CORS, 4xx/5xx, malformed stream): not just an
- * un-wired proxy, so the copy stays honest about the failure and surfaces the
- * underlying reason to help with debugging.
+ * Dispatch can fail in transport, stream parsing, lazy modules or application
+ * callbacks. Only recognized fetch failures should suggest connectivity;
+ * unknown/internal failures must not send users to debug a healthy backend.
  *
  * Callers can override the copy via `config.errorMessage` (a static string or
  * a function of the error). An override that returns an empty string yields ""
@@ -283,9 +283,17 @@ function buildDispatchErrorContent(
   if (typeof override === "string") return override;
   if (typeof override === "function") return override(err);
 
-  const base =
-    "Sorry: I couldn't reach the assistant. The chat service didn't respond. Please check that your proxy or backend is running and reachable, then try again.";
-  return err.message ? `${base}\n\n_Details: ${err.message}_` : base;
+  // Fetch rejects with TypeError too, so the error class cannot distinguish
+  // an offline browser from an internal fault such as a missing function.
+  const detail = err.message.trim();
+  const networkFailure = /^(Failed to fetch|fetch failed|Load failed|NetworkError when attempting to fetch resource\.?)$/i.test(detail);
+  const backendFailure = /^(Chat backend|Agent execution) request failed: \d{3}\b/.test(detail);
+  const base = networkFailure
+    ? "Sorry: I couldn't reach the assistant. Please check your connection and try again."
+    : backendFailure
+      ? "Sorry: the chat service couldn't complete the request. Please try again."
+      : "Sorry: the chat encountered an unexpected error. Please reload the page and try again.";
+  return detail ? `${base}\n\n_Details: ${detail}_` : base;
 }
 
 /**
@@ -2493,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,
@@ -2508,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 } })
     };
 
   }
@@ -3008,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.',