@runtypelabs/persona 4.32.1 → 4.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.32.1",
+  "version": "4.33.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/client-dispatch.ts

@@ -1,7 +1,7 @@
 import { computeClientToolsFingerprint } from "./webmcp-bridge";
 import type { RuntypeClientInitResponse } from "./generated/runtype-openapi-contract";
 import type {
-  AgentWidgetMessage, AgentWidgetRequestPayload, AgentWidgetAgentRequestPayload,
+  AgentWidgetMessage, AgentWidgetModelMessageRole, AgentWidgetRequestPayload, AgentWidgetAgentRequestPayload,
   AgentWidgetContextProvider, AgentWidgetRequestMiddleware, AgentWidgetCustomFetch,
   ClientSession, ClientChatRequest, ComposerOptionsPayload, WidgetHistoryInternals, ClientFeedbackRequest, ClientFeedbackType, ClientToolDefinition,
 } from "./types";
@@ -49,6 +49,13 @@ export interface ClientDispatchHost extends ClientResumeHost {
   streamResponse: (body: ReadableStream<Uint8Array>, onEvent: SSEHandler, assistantMessageId?: string, seedContent?: string, signal?: AbortSignal) => Promise<void>;
 }
 
+/** A message whose role the model accepts. */
+type ModelMessage = AgentWidgetMessage & { role: AgentWidgetModelMessageRole };
+
+/**
+ * Whether a message belongs in a model request. Every payload builder gates on
+ * this before the host conversion hook, so local notices cannot enter context.
+ */
 const hasValidContent = (message: AgentWidgetMessage): boolean => {
   // Display-only voice captions are never conversation.
   if (message.voiceCaption) return false;
@@ -72,20 +79,37 @@ const hasValidContent = (message: AgentWidgetMessage): boolean => {
   return false;
 };
 
+/** Reject malformed JS/CDN hook results before constructing a network request. */
+const isModelContent = (content: unknown): boolean => {
+  if (typeof content === "string") return true;
+  if (!Array.isArray(content)) return false;
+  return content.every(part => {
+    if (!part || typeof part !== "object") return false;
+    switch (part.type) {
+      case "text": return typeof part.text === "string";
+      case "image": return typeof part.image === "string";
+      case "audio": return typeof part.audio === "string";
+      case "video": return typeof part.video === "string";
+      case "file": return typeof part.data === "string" && typeof part.mimeType === "string" && typeof part.filename === "string";
+      default: return false;
+    }
+  });
+};
+
 const sortByCreatedAt = (messages: AgentWidgetMessage[]): AgentWidgetMessage[] =>
   messages
     .slice()
     .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
 
 // Only replay explicit known assistant phase metadata; other widget metadata is private.
-const payloadPhase = (message: AgentWidgetMessage) => {
+const payloadPhase = (message: ModelMessage) => {
   const phase = message.agentMetadata?.providerPhase ?? message.agentMetadata?.phase;
   return message.role === "assistant" && (phase === "commentary" || phase === "partial_answer" || phase === "final_answer")
     ? { phase } : {};
 };
 
 // Priority: contentParts (multi-modal) > llmContent (explicit LLM content) > rawContent (structured parsers) > content (display)
-const toPayloadMessage = (message: AgentWidgetMessage) => ({
+const toPayloadMessage = (message: ModelMessage) => ({
   role: message.role,
   content: message.contentParts ?? message.llmContent ?? message.rawContent ?? message.content,
   createdAt: message.createdAt,
@@ -480,7 +504,10 @@ export class ClientDispatch {
       }
 
       // Build the standard payload to get context/metadata from middleware
-      const basePayload = await this.#buildPayload(options.messages);
+      // Reuse the conversion: the hook runs once per transcript entry even
+      // though client-token dispatch also builds the middleware/context payload.
+      const modelMessages = new Map(sortByCreatedAt(options.messages).map(message => [message, this.#toModelMessage(message)]));
+      const basePayload = await this.#buildPayload(options.messages, undefined, modelMessages);
 
       // Build the chat request payload with message IDs for feedback tracking
       // Filter out sessionId from metadata if present (it's only for local storage)
@@ -495,19 +522,21 @@ export class ClientDispatch {
       const baseChatRequest: Omit<ClientChatRequest, 'clientTools' | 'clientToolsFingerprint'> = {
         sessionId: session.sessionId,
         // Filter out messages with empty content to prevent validation errors
-        messages: options.messages.filter(hasValidContent).map(m => {
+        messages: sortByCreatedAt(options.messages).flatMap(m => {
+          const projected = modelMessages.get(m);
+          if (!projected) return [];
           // The visitor-visible projection rides along only where it diverges
           // from the model channel, and only on the history-capable plane.
           const displayContent = historyCapable
-            ? divergentDisplayProjection(m)
+            ? divergentDisplayProjection(m, projected.content)
             : undefined;
-          return {
-            id: m.id, // Include message ID for tracking
-            role: m.role,
+          return [{
+            id: m.id, // Include original message identity for tracking
+            role: projected.role,
             // Priority: contentParts (multi-modal) > llmContent (explicit LLM content) > rawContent (structured parsers) > content (display)
-            content: m.contentParts ?? m.llmContent ?? m.rawContent ?? m.content,
+            content: projected.content,
             ...(displayContent !== undefined && { displayContent }),
-          };
+          }];
         }),
         // Include pre-generated assistant message ID if provided
         ...(options.assistantMessageId && { assistantMessageId: options.assistantMessageId }),
@@ -888,6 +917,31 @@ export class ClientDispatch {
     return declared ? { ...agent, model: selected } : agent;
   }
 
+  #toModelMessage(message: AgentWidgetMessage): ReturnType<typeof toPayloadMessage> | null {
+    // These entries must never become model context, even through a host hook.
+    if (!hasValidContent(message)) return null;
+    const content = message.contentParts ?? message.llmContent ?? message.rawContent ?? message.content;
+    const modelMessage = message.role === "operator" ? null : toPayloadMessage(message as ModelMessage);
+    const transform = this.host.config.modelMessageTransform;
+    if (!transform) return modelMessage;
+    const result = transform({ message, content, modelMessage });
+    if (result === null) return null;
+    if (!result || typeof result !== "object" ||
+      !["user", "assistant", "system"].includes(result.role) ||
+      !isModelContent(result.content) ||
+      typeof result.createdAt !== "string") {
+      throw new TypeError("modelMessageTransform must return a supported model message or null");
+    }
+    // Only the established payload fields cross the wire. Host display metadata
+    // (including author) must be mapped intentionally into adapter model context.
+    return {
+      role: result.role,
+      content: result.content,
+      createdAt: result.createdAt,
+      ...(result.role === "assistant" && result.phase && { phase: result.phase }),
+    };
+  }
+
   async #buildAgentPayload(
     messages: AgentWidgetMessage[],
     composerOptions?: ComposerOptionsPayload
@@ -902,10 +956,8 @@ export class ClientDispatch {
     const normalizedMessages = serializeWithToolPairs(
       sortByCreatedAt(messages),
       (message) =>
-        hasValidContent(message) &&
-        (message.role === "user" || message.role === "assistant" || message.role === "system") &&
         (!message.variant || message.variant === "assistant")
-          ? toPayloadMessage(message)
+          ? this.#toModelMessage(message)
           : null
     );
 
@@ -947,7 +999,8 @@ export class ClientDispatch {
 
   async #buildPayload(
     messages: AgentWidgetMessage[],
-    composerOptions?: ComposerOptionsPayload
+    composerOptions?: ComposerOptionsPayload,
+    modelMessages?: Map<AgentWidgetMessage, ReturnType<typeof toPayloadMessage> | null>
   ): Promise<AgentWidgetRequestPayload> {
     // Filter out messages with empty content to prevent validation errors;
     // answered client-tool calls replay as paired toolCalls/toolResults
@@ -955,7 +1008,7 @@ export class ClientDispatch {
     // reads these, so the server stays the replay owner there.
     const normalizedMessages = serializeWithToolPairs(
       sortByCreatedAt(messages),
-      (message) => (hasValidContent(message) ? toPayloadMessage(message) : null)
+      (message) => modelMessages ? modelMessages.get(message) ?? null : this.#toModelMessage(message)
     );
 
     const routed = this.host.routing();

package/src/client.operator-role.test.ts

@@ -0,0 +1,217 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AgentWidgetClient } from "./client";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "./types";
+
+/**
+ * Operator messages (a human on the agent's side, e.g. a support takeover)
+ * are omitted by default: a server-backed thread may already own their replay.
+ * Stateless adapters can opt into attributed context using supported model roles.
+ */
+
+const sseComplete = () =>
+  `event: execution_complete\ndata: ${JSON.stringify({
+    type: "execution_complete",
+    executionId: "exec_1",
+    agentId: "agent_1",
+    success: true,
+    iterations: 1,
+    completedAt: "2026-01-01T00:00:10.000Z",
+    seq: 1,
+  })}\n\n`;
+
+const captureFetch = () => {
+  const bodies: Array<{ url: string; body: Record<string, unknown> }> = [];
+  global.fetch = vi.fn().mockImplementation(async (url: string, options: RequestInit) => {
+    bodies.push({ url, body: JSON.parse(String(options.body)) });
+    const encoder = new TextEncoder();
+    return {
+      ok: true,
+      body: new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode(sseComplete()));
+          controller.close();
+        },
+      }),
+    };
+  });
+  return bodies;
+};
+
+const transcript = (): AgentWidgetMessage[] => [
+  { id: "u1", role: "user", content: "Where is my order?", createdAt: "2026-01-01T00:00:00.000Z" },
+  { id: "a1", role: "assistant", content: "Let me check.", createdAt: "2026-01-01T00:00:01.000Z" },
+  {
+    id: "op1",
+    role: "operator",
+    content: "Hi, this is Sam from support. I've refunded it.",
+    llmContent: "operator llm content",
+    createdAt: "2026-01-01T00:00:02.000Z",
+  },
+  { id: "u2", role: "user", content: "Thanks!", createdAt: "2026-01-01T00:00:03.000Z" },
+];
+
+const expectNoOperator = (messages: unknown) => {
+  expect(Array.isArray(messages)).toBe(true);
+  const list = messages as Array<Record<string, unknown>>;
+  expect(list.map((message) => message.role)).toEqual(["user", "assistant", "user"]);
+  expect(JSON.stringify(list)).not.toContain("support");
+  expect(JSON.stringify(list)).not.toContain("operator");
+};
+
+describe("operator role: outgoing request payloads", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("drops operator messages from the proxy payload", async () => {
+    const bodies = captureFetch();
+    const client = new AgentWidgetClient({ apiUrl: "https://api.example.com/chat" });
+
+    await client.dispatch({ messages: transcript() }, () => {});
+
+    expectNoOperator(bodies[0].body.messages);
+  });
+
+  it("drops operator messages from the agent payload", async () => {
+    const bodies = captureFetch();
+    const client = new AgentWidgetClient({
+      apiUrl: "https://api.example.com/agents",
+      agent: { name: "Test", model: "openai:gpt-4o-mini", systemPrompt: "test" },
+    } as AgentWidgetConfig);
+
+    await client.dispatch({ messages: transcript() }, () => {});
+
+    expectNoOperator(bodies[0].body.messages);
+  });
+
+  it("drops operator messages from the client-token chat request", async () => {
+    const bodies = captureFetch();
+    const client = new AgentWidgetClient({
+      apiUrl: "https://api.runtype.com",
+      clientToken: "ct_live_demo",
+      agentId: "agent_1",
+    });
+    (client as unknown as {
+      clientSession: { sessionId: string; expiresAt: Date };
+    }).clientSession = {
+      sessionId: "sess_operator",
+      expiresAt: new Date(Date.now() + 10 * 60_000),
+    };
+
+    await client.dispatch({ messages: transcript() }, () => {});
+
+    const chat = bodies.find((request) => request.url.endsWith("/v1/client/chat"));
+    expect(chat).toBeDefined();
+    expectNoOperator(chat!.body.messages);
+  });
+});
+
+// The adapter owns this conversion; the widget supplies resolved content and
+// keeps its original UI role/identity intact.
+const mapHumanHistory: NonNullable<AgentWidgetConfig["modelMessageTransform"]> = ({ message, content, modelMessage }) =>
+  message.role === "operator"
+    ? { role: "user", content: typeof content === "string" ? `Historical human support reply (${message.id}, ${message.author?.displayName ?? "Human operator"}): ${content}` : content, createdAt: message.createdAt }
+    : modelMessage;
+
+const configFor = (transport: string): AgentWidgetConfig => ({
+  apiUrl: "https://api.example.com/chat",
+  ...(transport === "agent" && { agent: { name: "Test", model: "openai:gpt-4o-mini", systemPrompt: "test" } }),
+  ...(transport === "client-token" && { clientToken: "ct_live_demo", agentId: "agent_1", features: { history: { enabled: true } } }),
+});
+const seedClientSession = (client: AgentWidgetClient) => {
+  (client as unknown as { clientSession: { sessionId: string; expiresAt: Date; history?: { enabled: boolean } } }).clientSession = {
+    sessionId: "sess_operator", expiresAt: new Date(Date.now() + 600_000), history: { enabled: true },
+  };
+};
+
+describe("explicit model context conversion", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it.each(["proxy", "agent", "client-token"])("replays each human contribution once, chronologically, for %s", async transport => {
+    const bodies = captureFetch();
+    const transform = vi.fn(mapHumanHistory);
+    const client = new AgentWidgetClient({ ...configFor(transport), modelMessageTransform: transform });
+    if (transport === "client-token") seedClientSession(client);
+    const messages = transcript();
+    messages[2].author = { id: "sam", displayName: "Sam", kind: "human" };
+    await client.dispatch({ messages: [...messages].reverse() }, () => {});
+    const request = bodies.find(entry => transport !== "client-token" || entry.url.endsWith("/v1/client/chat"))!;
+    const sent = request.body.messages as Array<{ id?: string; role: string; content: string; displayContent?: string }>;
+    expect(sent.map(message => message.role)).toEqual(["user", "assistant", "user", "user"]);
+    expect(sent.map(message => message.content)).toEqual([
+      "Where is my order?", "Let me check.", "Historical human support reply (op1, Sam): operator llm content", "Thanks!",
+    ]);
+    expect(transform).toHaveBeenCalledTimes(4);
+    expect(transform.mock.calls.map(([context]) => context.message.id)).toEqual(["u1", "a1", "op1", "u2"]);
+    expect(messages[2].role).toBe("operator");
+    if (transport === "client-token") {
+      expect(sent[2].id).toBe("op1");
+      expect(sent[2].displayContent).toBe(messages[2].content);
+    }
+  });
+
+  it.each(["proxy", "agent", "client-token"])("resolves content priority and preserves attachments for %s", async transport => {
+    const bodies = captureFetch();
+    const transform = vi.fn(mapHumanHistory);
+    const client = new AgentWidgetClient({ ...configFor(transport), modelMessageTransform: transform });
+    if (transport === "client-token") seedClientSession(client);
+    const human = transcript()[2];
+    const image = { type: "image" as const, image: "https://example.com/photo.png" };
+    const messages: AgentWidgetMessage[] = [
+      { ...human, id: "image", content: "", contentParts: [image] },
+      { ...human, id: "llm", rawContent: "raw" },
+      { ...human, id: "raw", llmContent: undefined, rawContent: "raw" },
+      { ...human, id: "visible", llmContent: undefined },
+      { ...human, id: "local", localOnly: true },
+      { ...human, id: "caption", voiceCaption: true },
+    ];
+    await client.dispatch({ messages }, () => {});
+    expect(transform).toHaveBeenCalledTimes(4);
+    expect(transform.mock.calls.map(([context]) => context.content)).toEqual([[image], "operator llm content", "raw", human.content]);
+    expect(transform.mock.calls.every(([context]) => context.modelMessage === null)).toBe(true);
+    const request = bodies.find(entry => transport !== "client-token" || entry.url.endsWith("/v1/client/chat"))!;
+    expect((request.body.messages as Array<{content: unknown}>)[0].content).toEqual([image]);
+    expect(JSON.stringify(request.body.messages)).not.toContain('"author"');
+  });
+
+  it("preserves an empty human display projection when client-token conversion adds attribution", async () => {
+    const bodies = captureFetch();
+    const client = new AgentWidgetClient({ ...configFor("client-token"), modelMessageTransform: ({ message, content, modelMessage }) =>
+      message.role === "operator" ? { role: "user", content: [{ type: "text", text: "Historical human support reply" }, ...(Array.isArray(content) ? content : [])], createdAt: message.createdAt } : modelMessage,
+    });
+    seedClientSession(client);
+    await client.dispatch({ messages: [{ ...transcript()[2], content: "", llmContent: undefined, contentParts: [{ type: "image", image: "https://example.com/photo.png" }] }] }, () => {});
+    const chat = bodies.find(entry => entry.url.endsWith("/v1/client/chat"))!;
+    expect((chat.body.messages as Array<{ displayContent?: string }>)[0].displayContent).toBe("");
+  });
+
+  it("does not hide attachments when a conversion only clones the model content", async () => {
+    const bodies = captureFetch();
+    const client = new AgentWidgetClient({
+      ...configFor("client-token"),
+      modelMessageTransform: ({ modelMessage }) => modelMessage
+        ? { ...modelMessage, content: structuredClone(modelMessage.content) }
+        : null,
+    });
+    seedClientSession(client);
+    await client.dispatch({ messages: [{ ...transcript()[0], content: "", contentParts: [{ type: "image", image: "https://example.com/photo.png" }] }] }, () => {});
+    const chat = bodies.find(entry => entry.url.endsWith("/v1/client/chat"))!;
+    expect((chat.body.messages as Array<{ displayContent?: string }>)[0].displayContent).toBeUndefined();
+  });
+
+  it.each([
+    { role: "operator", content: "unsupported", createdAt: "now" },
+    { role: "user", content: { text: "invalid" }, createdAt: "now" },
+    { role: "user", content: [{ type: "image", image: 42 }], createdAt: "now" },
+    Promise.resolve(null),
+    undefined,
+  ])("fails explicitly for a malformed JavaScript hook result", async result => {
+    const bodies = captureFetch();
+    const client = new AgentWidgetClient({
+      apiUrl: "https://api.example.com/chat",
+      modelMessageTransform: (() => result) as unknown as AgentWidgetConfig["modelMessageTransform"],
+    });
+    await expect(client.dispatch({ messages: transcript() }, () => {})).rejects.toThrow("modelMessageTransform");
+    expect(bodies).toHaveLength(0);
+  });
+});

package/src/components/message-bubble.test.ts

@@ -3,6 +3,7 @@ import { describe, it, expect } from "vitest";
 import {
   createStandardBubble,
   createMessageActions,
+  getBubbleClasses,
   createMessageInlineMentions,
   isSafeImageSrc,
   isSafeMediaSrc,
@@ -986,3 +987,171 @@ describe("createMessageActions: chromeless action buttons", () => {
     expect(buttons[0].className).toBe("persona-message-action-btn");
   });
 });
+
+describe("createStandardBubble: operator role", () => {
+  const actions = {
+    enabled: true,
+    showCopy: true,
+    showUpvote: true,
+    showDownvote: true,
+    showReadAloud: true,
+    showRegenerate: true,
+    visibility: "hover",
+    align: "right",
+    layout: "pill-inside",
+  } as const;
+
+  it.each(["bubble", "minimal", "flat"] as const)(
+    "gets its own bubble class, never the assistant's, in the %s layout",
+    (layout) => {
+      const classes = getBubbleClasses("operator", layout);
+      expect(classes).toContain("persona-message-operator-bubble");
+      expect(classes).not.toContain("persona-message-assistant-bubble");
+      expect(classes).not.toContain("persona-message-user-bubble");
+      // Same side as the assistant: never pushed to the user's edge.
+      expect(classes).not.toContain("persona-ml-auto");
+    }
+  );
+
+  it("paints from the operator tokens and marks its own theme zone", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ id: "op-1", role: "operator", content: "Hi, Sam here." }),
+      ({ text }) => text
+    );
+    expect(bubble.style.backgroundColor).toBe(
+      "var(--persona-components-message-operator-background, var(--persona-container))"
+    );
+    expect(bubble.style.color).toBe(
+      "var(--persona-components-message-operator-text, var(--persona-text))"
+    );
+    expect(bubble.getAttribute("data-persona-theme-zone")).toBe("operator-message");
+  });
+
+  it("keeps the existing roles' bubbles unchanged", () => {
+    const assistant = createStandardBubble(makeMessage({ id: "a", content: "Answer" }), ({ text }) => text);
+    const user = createStandardBubble(makeMessage({ id: "u", role: "user", content: "Q" }), ({ text }) => text);
+    expect(assistant.getAttribute("data-persona-theme-zone")).toBe("assistant-message");
+    expect(assistant.style.backgroundColor).toBe(
+      "var(--persona-message-assistant-bg, var(--persona-container))"
+    );
+    expect(user.getAttribute("data-persona-theme-zone")).toBe("user-message");
+    expect(user.style.backgroundColor).toBe("var(--persona-message-user-bg, var(--persona-accent))");
+  });
+
+  it("keeps the operator background in the flat layout, where assistant prose stays transparent", () => {
+    const operator = createStandardBubble(
+      makeMessage({ id: "flat-op", role: "operator", content: "Sam here." }),
+      ({ text }) => text,
+      { layout: "flat" }
+    );
+    const assistant = createStandardBubble(
+      makeMessage({ id: "flat-a", content: "Answer" }),
+      ({ text }) => text,
+      { layout: "flat" }
+    );
+    expect(operator.style.backgroundColor).toBe(
+      "var(--persona-components-message-operator-background, var(--persona-container))"
+    );
+    expect(operator.style.color).toBe(
+      "var(--persona-components-message-operator-text, var(--persona-text))"
+    );
+    // The fill needs side padding; flat assistant prose has none.
+    expect(operator.classList.contains("persona-px-3")).toBe(true);
+    expect(assistant.style.backgroundColor).toBe("transparent");
+    expect(assistant.classList.contains("persona-px-3")).toBe(false);
+  });
+
+  it("uses operator geometry tokens with the v5 defaults, not the flat assistant's", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ id: "op-geo", role: "operator", content: "Hi" }),
+      ({ text }) => text, undefined, undefined, undefined,
+      { widgetConfig: { future: { v5Defaults: true } } as AgentWidgetConfig }
+    );
+    expect(bubble.style.padding).toBe("var(--persona-message-operator-padding, 0.75rem 1.25rem)");
+    expect(bubble.style.padding).not.toContain("assistant");
+  });
+
+  it("offers copy but no model feedback, read-aloud or regenerate controls", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ id: "op-actions", role: "operator", content: "I refunded it." }),
+      ({ text }) => text,
+      undefined,
+      actions,
+      undefined,
+      { actionEligibility: { canRegenerate: true } }
+    );
+    const rendered = Array.from(bubble.querySelectorAll("[data-action]")).map((button) =>
+      button.getAttribute("data-action")
+    );
+    expect(rendered).toEqual(["copy"]);
+  });
+
+  it("shows a custom action only when it opts into the operator role", () => {
+    const custom = [
+      { id: "assistant-only", label: "Assistant only", onSelect: () => {} },
+      { id: "flag", label: "Flag", roles: ["operator" as const], onSelect: () => {} },
+    ];
+    const bubble = createStandardBubble(
+      makeMessage({ id: "op-custom", role: "operator", content: "Hello" }),
+      ({ text }) => text,
+      undefined,
+      { ...actions, showCopy: false, custom }
+    );
+    const rendered = Array.from(bubble.querySelectorAll("[data-action]")).map((button) =>
+      button.getAttribute("data-action")
+    );
+    expect(rendered).toEqual(["custom:flag"]);
+  });
+
+  it("keeps opted-in actions on media-only human replies without an empty copy control", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ id: "media-human", role: "operator", content: "", contentParts: [{ type: "image", image: "https://example.com/photo.png" }] }),
+      ({ text }) => text,
+      undefined,
+      { ...actions, custom: [{ id: "flag", label: "Flag", roles: ["operator"], onSelect: () => {} }] }
+    );
+    expect(Array.from(bubble.querySelectorAll("[data-action]")).map(button => button.getAttribute("data-action"))).toEqual(["custom:flag"]);
+  });
+
+  it("supports a localized visible and accessible human label", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ role: "operator", content: "Bonjour", author: { displayName: "Sam", kind: "human" } }),
+      ({ text }) => text, undefined, undefined, undefined,
+      { widgetConfig: { copy: { operatorLabel: "Conseiller humain" } } }
+    );
+    expect(bubble.getAttribute("aria-label")).toBe("Sam · Conseiller humain");
+    expect(bubble.querySelector(".persona-message-author")?.textContent).toBe("Sam · Conseiller humain");
+  });
+
+  it("keeps a human label when JavaScript supplies malformed provenance or an empty label", () => {
+    const bubble = createStandardBubble(
+      makeMessage({ role: "operator", content: "Hello", author: { displayName: 42 } as unknown as AgentWidgetMessage["author"] }),
+      ({ text }) => text, undefined, undefined, undefined,
+      { widgetConfig: { copy: { operatorLabel: "  " } } }
+    );
+    expect(bubble.getAttribute("aria-label")).toBe("Human operator");
+  });
+
+  it("renders an operator avatar on the assistant side", () => {
+    const wrapper = createStandardBubble(
+      makeMessage({ id: "op-avatar", role: "operator", content: "Hello" }),
+      ({ text }) => text,
+      { avatar: { show: true, position: "left" } }
+    );
+    expect(wrapper.classList.contains("persona-message-with-avatar")).toBe(true);
+    expect(wrapper.classList.contains("persona-flex-row-reverse")).toBe(false);
+    const avatar = wrapper.firstElementChild as HTMLElement;
+    expect(avatar.textContent).toBe("O");
+    expect(avatar.classList.contains("persona-bg-persona-container")).toBe(true);
+    expect(avatar.classList.contains("persona-bg-persona-primary")).toBe(false);
+
+    const custom = createStandardBubble(
+      makeMessage({ id: "op-avatar-url", role: "operator", content: "Hello" }),
+      ({ text }) => text,
+      { avatar: { show: true, operatorAvatar: "https://example.com/sam.png" } }
+    );
+    const img = custom.querySelector("img");
+    expect(img?.getAttribute("src")).toBe("https://example.com/sam.png");
+    expect(img?.getAttribute("alt")).toBe("Operator");
+  });
+});