@runtypelabs/persona 3.16.0 → 3.17.0

package/src/client.test.ts

@@ -2576,3 +2576,144 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
   });
 });
 
+// ============================================================================
+// stopReason wiring (agent_turn_complete / step_complete)
+// ============================================================================
+
+describe('AgentWidgetClient - stopReason propagation', () => {
+  const dispatchModeStream = (stopReason?: string) => {
+    const data: Record<string, unknown> = {
+      type: 'step_complete',
+      id: 'step_1',
+      stepType: 'prompt',
+      result: { response: 'Hello there.' },
+    };
+    if (stopReason) data.stopReason = stopReason;
+    return [
+      `data: ${JSON.stringify(data)}\n\n`,
+      `data: ${JSON.stringify({ type: 'flow_complete', success: true })}\n\n`,
+    ];
+  };
+
+  const collectFinalAssistant = (events: AgentWidgetEvent[]): AgentWidgetMessage | null => {
+    const messageEvents = events.filter(e => e.type === 'message');
+    for (let i = messageEvents.length - 1; i >= 0; i--) {
+      const ev = messageEvents[i];
+      if (ev.type === 'message' && ev.message.role === 'assistant' && !ev.message.streaming) {
+        return ev.message;
+      }
+    }
+    return null;
+  };
+
+  const runDispatch = async (chunks: string[]): Promise<AgentWidgetEvent[]> => {
+    global.fetch = vi.fn().mockImplementation(async (_url: string, _options: any) => {
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+          controller.close();
+        }
+      });
+      return { ok: true, body: stream };
+    });
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'usr_1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+    return events;
+  };
+
+  it.each(['end_turn', 'max_tool_calls', 'length', 'content_filter', 'error', 'unknown'] as const)(
+    'attaches stopReason=%s from step_complete (dispatch / flow path)',
+    async (stopReason) => {
+      const events = await runDispatch(dispatchModeStream(stopReason));
+      const final = collectFinalAssistant(events);
+      expect(final).not.toBeNull();
+      expect(final!.stopReason).toBe(stopReason);
+    }
+  );
+
+  it('leaves stopReason undefined when step_complete omits it (backcompat)', async () => {
+    const events = await runDispatch(dispatchModeStream(undefined));
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.stopReason).toBeUndefined();
+  });
+
+  it('captures the empty-content + max_tool_calls regression case', async () => {
+    // Symptom the upstream fix targets: model emits a tool call then gets cut
+    // off before producing follow-up text. Persona must record stopReason so
+    // the UI can render an affordance instead of an empty bubble.
+    const events = await runDispatch([
+      `data: ${JSON.stringify({
+        type: 'step_complete',
+        id: 'step_1',
+        stepType: 'prompt',
+        result: { response: '' },
+        stopReason: 'max_tool_calls',
+      })}\n\n`,
+      `data: ${JSON.stringify({ type: 'flow_complete', success: true })}\n\n`,
+    ]);
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.content).toBe('');
+    expect(final!.stopReason).toBe('max_tool_calls');
+  });
+
+  it('agent_turn_complete.stopReason overrides any earlier step_complete value (agent-loop path)', async () => {
+    // Build an agent-mode stream that emits both events. agent_turn_complete
+    // arrives last; its stopReason should win.
+    const execId = 'exec_stopreason';
+    global.fetch = createAgentStreamFetch([
+      sseEvent('agent_start', {
+        executionId: execId, agentId: 'virtual', agentName: 'Test',
+        maxTurns: 1, startedAt: new Date().toISOString(), seq: 1,
+      }),
+      sseEvent('agent_iteration_start', {
+        executionId: execId, iteration: 1, maxTurns: 1,
+        startedAt: new Date().toISOString(), seq: 2,
+      }),
+      sseEvent('agent_turn_start', {
+        executionId: execId, iteration: 1, turnIndex: 0,
+        role: 'assistant', turnId: 'turn_1', seq: 3,
+      }),
+      sseEvent('agent_turn_delta', {
+        executionId: execId, iteration: 1, delta: 'partial answer',
+        contentType: 'text', turnId: 'turn_1', seq: 4,
+      }),
+      sseEvent('agent_turn_complete', {
+        executionId: execId, iteration: 1, role: 'assistant',
+        turnId: 'turn_1', completedAt: new Date().toISOString(),
+        stopReason: 'max_tool_calls', seq: 5,
+      }),
+      sseEvent('agent_iteration_complete', {
+        executionId: execId, iteration: 1, toolCallsMade: 0,
+        stopConditionMet: true, completedAt: new Date().toISOString(), seq: 6,
+      }),
+      sseEvent('agent_complete', {
+        executionId: execId, agentId: 'virtual', success: true,
+        iterations: 1, stopReason: 'max_iterations',
+        completedAt: new Date().toISOString(), seq: 7,
+      }),
+    ]);
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      agent: { name: 'Test', model: 'openai:gpt-4o-mini', systemPrompt: 'test' },
+    });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'usr_1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.stopReason).toBe('max_tool_calls');
+    expect(final!.agentMetadata?.turnId).toBe('turn_1');
+  });
+});
+

package/src/client.ts

@@ -13,6 +13,7 @@ import {
   AgentWidgetHeadersFunction,
   AgentWidgetSSEEventResult as _AgentWidgetSSEEventResult,
   AgentExecutionState,
+  StopReasonKind,
   ClientSession,
   ClientInitResponse,
   ClientChatRequest,
@@ -2094,11 +2095,20 @@ export class AgentWidgetClient {
             continue;
           }
 
+          // Capture optional per-step stopReason emitted by the runtime
+          // (e.g. `'max_tool_calls'`, `'length'`). This is the dispatch-mode
+          // fallback — `agent_turn_complete` will overwrite it later in
+          // agent-loop streams.
+          const stepStopReason = (payload as any).stopReason as
+            | StopReasonKind
+            | undefined;
+
           if (didSplitByPartId) {
             // Sealed segment(s) — do not create a second bubble from step_complete.
             // Merge authoritative final response into the last sealed segment (fixes async lag).
             if (assistantMessage !== null) {
               const msg: AgentWidgetMessage = assistantMessage;
+              if (stepStopReason) msg.stopReason = stepStopReason;
               streamParsers.delete(msg.id);
               rawContentBuffers.delete(msg.id);
               if (msg.streaming !== false) {
@@ -2109,6 +2119,7 @@ export class AgentWidgetClient {
             const splitFinalContent = payload.result?.response;
             const sealedForReconcile = lastSealedTextSegment;
             if (sealedForReconcile) {
+              if (stepStopReason) sealedForReconcile.stopReason = stepStopReason;
               if (splitFinalContent !== undefined && splitFinalContent !== null) {
                 reconcileSealedAssistantWithFinalResponse(sealedForReconcile, splitFinalContent);
               } else {
@@ -2121,6 +2132,7 @@ export class AgentWidgetClient {
           }
           const finalContent = payload.result?.response;
           const assistant = ensureAssistantMessage();
+          if (stepStopReason) assistant.stopReason = stepStopReason;
           if (finalContent !== undefined && finalContent !== null) {
             // Check if we already have extracted text from streaming
             const parser = streamParsers.get(assistant.id);
@@ -2408,6 +2420,22 @@ export class AgentWidgetClient {
               emitMessage(reasoningMessage);
             }
           }
+
+          // Attach the turn-level stopReason to the assistant message
+          // produced by this turn. Only overwrite the current message —
+          // prior turns already sealed their own stopReason via step_complete.
+          const turnStopReason = (payload as any).stopReason as
+            | StopReasonKind
+            | undefined;
+          if (turnStopReason && assistantMessage !== null) {
+            const turnId = payload.turnId;
+            const matchesTurn =
+              !turnId || assistantMessage.agentMetadata?.turnId === turnId;
+            if (matchesTurn) {
+              assistantMessage.stopReason = turnStopReason;
+              emitMessage(assistantMessage);
+            }
+          }
         } else if (payloadType === "agent_tool_start") {
           const toolId = payload.toolCallId ?? `agent-tool-${nextSequence()}`;
           trackToolId(getToolCallKey(payload), toolId);

package/src/components/composer-builder.ts

@@ -22,6 +22,13 @@ export interface ComposerElements {
   actionsRow: HTMLElement;
   leftActions: HTMLElement;
   rightActions: HTMLElement;
+  /**
+   * Swap the send button between its idle ("send") appearance and its
+   * streaming ("stop") appearance. In icon mode this swaps the SVG; in text
+   * mode it swaps the button label. Tooltip text is updated when a tooltip
+   * element is present.
+   */
+  setSendButtonMode: (mode: "send" | "stop") => void;
 }
 
 /**
@@ -122,7 +129,11 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   const useIcon = sendButtonConfig.useIcon ?? false;
   const iconText = sendButtonConfig.iconText ?? "↑";
   const iconName = sendButtonConfig.iconName;
+  const stopIconName = sendButtonConfig.stopIconName ?? "square";
   const tooltipText = sendButtonConfig.tooltipText ?? "Send message";
+  const stopTooltipText = sendButtonConfig.stopTooltipText ?? "Stop generating";
+  const sendLabel = config?.copy?.sendButtonLabel ?? "Send";
+  const stopLabel = config?.copy?.stopButtonLabel ?? "Stop";
   const showTooltip = sendButtonConfig.showTooltip ?? false;
   const buttonSize = sendButtonConfig.size ?? "40px";
   const backgroundColor = sendButtonConfig.backgroundColor;
@@ -141,6 +152,11 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   sendButton.type = "submit";
   sendButton.setAttribute("data-persona-composer-submit", "");
 
+  // Icons for both modes are pre-rendered so setSendButtonMode can swap them
+  // without having to re-render on every streaming state change.
+  let sendIcon: SVGElement | null = null;
+  let stopIcon: SVGElement | null = null;
+
   if (useIcon) {
     // Icon mode: circular button
     sendButton.style.width = buttonSize;
@@ -160,13 +176,14 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
       sendButton.style.color = "var(--persona-button-primary-fg, #ffffff)";
     }
 
+    const iconSize = parseFloat(buttonSize) || 24;
+    const iconColor = textColor?.trim() || "currentColor";
+
     // Use Lucide icon if iconName is provided, otherwise fall back to iconText
     if (iconName) {
-      const iconSize = parseFloat(buttonSize) || 24;
-      const iconColor = textColor?.trim() || "currentColor";
-      const iconSvg = renderLucideIcon(iconName, iconSize, iconColor, 2);
-      if (iconSvg) {
-        sendButton.appendChild(iconSvg);
+      sendIcon = renderLucideIcon(iconName, iconSize, iconColor, 2);
+      if (sendIcon) {
+        sendButton.appendChild(sendIcon);
       } else {
         sendButton.textContent = iconText;
       }
@@ -174,6 +191,9 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
       sendButton.textContent = iconText;
     }
 
+    // Pre-render the stop icon so mode swaps are cheap; it starts detached.
+    stopIcon = renderLucideIcon(stopIconName, iconSize, iconColor, 2);
+
     if (backgroundColor) {
       sendButton.style.backgroundColor = backgroundColor;
     } else {
@@ -181,7 +201,7 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     }
   } else {
     // Text mode: existing behavior
-    sendButton.textContent = config?.copy?.sendButtonLabel ?? "Send";
+    sendButton.textContent = sendLabel;
     if (textColor) {
       sendButton.style.color = textColor;
     } else {
@@ -215,14 +235,44 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   }
 
   // Add tooltip if enabled
+  let sendTooltip: HTMLElement | null = null;
   if (showTooltip && tooltipText) {
-    const tooltip = createElement("div", "persona-send-button-tooltip");
-    tooltip.textContent = tooltipText;
-    sendButtonWrapper.appendChild(tooltip);
+    sendTooltip = createElement("div", "persona-send-button-tooltip");
+    sendTooltip.textContent = tooltipText;
+    sendButtonWrapper.appendChild(sendTooltip);
   }
 
+  sendButton.setAttribute("aria-label", tooltipText);
+
   sendButtonWrapper.appendChild(sendButton);
 
+  let currentMode: "send" | "stop" = "send";
+  const setSendButtonMode = (mode: "send" | "stop") => {
+    if (mode === currentMode) return;
+    currentMode = mode;
+    const label = mode === "stop" ? stopTooltipText : tooltipText;
+    sendButton.setAttribute("aria-label", label);
+    if (sendTooltip) {
+      sendTooltip.textContent = label;
+    }
+
+    if (useIcon) {
+      // Only swap icons if both were rendered successfully; otherwise the
+      // button is using textContent fallback and there's nothing to swap.
+      if (sendIcon && stopIcon) {
+        const next = mode === "stop" ? stopIcon : sendIcon;
+        const prev = mode === "stop" ? sendIcon : stopIcon;
+        if (prev.parentNode === sendButton) {
+          sendButton.replaceChild(next, prev);
+        } else {
+          sendButton.appendChild(next);
+        }
+      }
+    } else {
+      sendButton.textContent = mode === "stop" ? stopLabel : sendLabel;
+    }
+  };
+
   // Voice recognition mic button
   const voiceRecognitionConfig = config?.voiceRecognition ?? {};
   const voiceRecognitionEnabled = voiceRecognitionConfig.enabled === true;
@@ -515,7 +565,8 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     // Actions row layout elements
     actionsRow,
     leftActions,
-    rightActions
+    rightActions,
+    setSendButtonMode
   };
 };
 

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

@@ -1,7 +1,12 @@
 // @vitest-environment jsdom
 import { describe, it, expect } from "vitest";
-import { createStandardBubble, isSafeImageSrc } from "./message-bubble";
-import type { AgentWidgetMessage } from "../types";
+import {
+  createStandardBubble,
+  isSafeImageSrc,
+  resolveStopReasonNoticeText,
+  getDefaultStopReasonNoticeCopy,
+} from "./message-bubble";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "../types";
 
 const makeMessage = (overrides: Partial<AgentWidgetMessage> = {}): AgentWidgetMessage => ({
   id: "msg-1",
@@ -95,3 +100,177 @@ describe("createStandardBubble", () => {
     expect(previewImages[0]?.getAttribute("alt")).toBe("Safe image");
   });
 });
+
+describe("resolveStopReasonNoticeText", () => {
+  it("returns null for natural completions", () => {
+    expect(resolveStopReasonNoticeText("end_turn")).toBeNull();
+  });
+
+  it("returns null for unknown reasons", () => {
+    expect(resolveStopReasonNoticeText("unknown")).toBeNull();
+  });
+
+  it("returns null when stopReason is undefined", () => {
+    expect(resolveStopReasonNoticeText(undefined)).toBeNull();
+  });
+
+  it("returns the default copy for actionable reasons", () => {
+    expect(resolveStopReasonNoticeText("max_tool_calls")).toBe(
+      getDefaultStopReasonNoticeCopy("max_tool_calls")
+    );
+    expect(resolveStopReasonNoticeText("length")).toBe(
+      getDefaultStopReasonNoticeCopy("length")
+    );
+    expect(resolveStopReasonNoticeText("content_filter")).toBe(
+      getDefaultStopReasonNoticeCopy("content_filter")
+    );
+    expect(resolveStopReasonNoticeText("error")).toBe(
+      getDefaultStopReasonNoticeCopy("error")
+    );
+  });
+
+  it("applies overrides on a per-key basis", () => {
+    expect(
+      resolveStopReasonNoticeText("max_tool_calls", {
+        ["max_tool_calls" as const]: "Custom override.",
+      })
+    ).toBe("Custom override.");
+  });
+
+  it("falls back to defaults for keys not overridden", () => {
+    expect(
+      resolveStopReasonNoticeText("length", {
+        ["max_tool_calls" as const]: "Custom.",
+      })
+    ).toBe(getDefaultStopReasonNoticeCopy("length"));
+  });
+
+  it("suppresses the notice when override is an empty string", () => {
+    expect(
+      resolveStopReasonNoticeText("max_tool_calls", {
+        ["max_tool_calls" as const]: "",
+      })
+    ).toBeNull();
+  });
+});
+
+describe("createStandardBubble — stopReason notice", () => {
+  const renderWithStopReason = (
+    overrides: Partial<AgentWidgetMessage>,
+    widgetConfig?: Partial<AgentWidgetConfig>
+  ) =>
+    createStandardBubble(
+      makeMessage(overrides),
+      ({ text }) => text,
+      undefined,
+      undefined,
+      undefined,
+      { widgetConfig: widgetConfig as AgentWidgetConfig | undefined }
+    );
+
+  it("renders no notice for end_turn (natural completion)", () => {
+    const bubble = renderWithStopReason({
+      content: "All done.",
+      stopReason: "end_turn",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders no notice when stopReason is absent (backcompat)", () => {
+    const bubble = renderWithStopReason({ content: "Hello." });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders no notice for unknown reasons", () => {
+    const bubble = renderWithStopReason({
+      content: "Hello.",
+      stopReason: "unknown",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders the default notice for max_tool_calls", () => {
+    const bubble = renderWithStopReason({
+      content: "Used a tool.",
+      stopReason: "max_tool_calls",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice).not.toBeNull();
+    expect(notice?.getAttribute("data-stop-reason")).toBe("max_tool_calls");
+    expect(notice?.textContent).toBe(getDefaultStopReasonNoticeCopy("max_tool_calls"));
+  });
+
+  it("renders the default notice for length", () => {
+    const bubble = renderWithStopReason({
+      content: "Long answer cut off.",
+      stopReason: "length",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("length");
+    expect(notice?.textContent).toBe(getDefaultStopReasonNoticeCopy("length"));
+  });
+
+  it("renders the default notice for content_filter", () => {
+    const bubble = renderWithStopReason({
+      content: "Filtered.",
+      stopReason: "content_filter",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("content_filter");
+  });
+
+  it("renders the default notice for error", () => {
+    const bubble = renderWithStopReason({
+      content: "Provider blew up.",
+      stopReason: "error",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("error");
+  });
+
+  it("applies copy overrides from widgetConfig.copy.stopReasonNotice", () => {
+    const bubble = renderWithStopReason(
+      { content: "x", stopReason: "max_tool_calls" },
+      { copy: { stopReasonNotice: { ["max_tool_calls" as const]: "Custom copy." } } }
+    );
+    expect(bubble.querySelector(".persona-message-stop-reason")?.textContent).toBe(
+      "Custom copy."
+    );
+  });
+
+  it("hides the empty content div when content is empty + max_tool_calls", () => {
+    // Regression: the empty-bubble symptom the upstream Runtype fix targets.
+    // With no content and max_tool_calls, the notice carries the bubble alone;
+    // the empty content div must be hidden so we don't render whitespace
+    // above the notice.
+    const bubble = renderWithStopReason({
+      content: "",
+      stopReason: "max_tool_calls",
+    });
+    const contentDiv = bubble.querySelector(".persona-message-content") as HTMLElement | null;
+    expect(contentDiv).not.toBeNull();
+    expect(contentDiv!.style.display).toBe("none");
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice).not.toBeNull();
+    expect(notice?.getAttribute("data-stop-reason")).toBe("max_tool_calls");
+  });
+
+  it("does not render notice while message is still streaming", () => {
+    const bubble = renderWithStopReason({
+      content: "partial",
+      stopReason: "max_tool_calls",
+      streaming: true,
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("does not render notice on user messages", () => {
+    const bubble = renderWithStopReason({
+      role: "user",
+      content: "user msg",
+      // stopReason on a user message is nonsense, but guard against it
+      stopReason: "max_tool_calls",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+});