@runtypelabs/persona 4.23.1 → 4.24.0

package/src/generated/runtype-openapi-contract.ts

@@ -78,6 +78,7 @@ export type RuntypeExecutionStreamEvent = ({
   turnIndex?: number;
   type: "turn_start";
 }) | ({
+  attributes?: Record<string, string | number | boolean>;
   completedAt?: string;
   content?: string;
   cost?: number;
@@ -136,7 +137,8 @@ export type RuntypeExecutionStreamEvent = ({
 };
   turnId?: string;
   type: "model_call_start";
-} | {
+} | ({
+  attributes?: Record<string, string | number | boolean>;
   completedAt?: string;
   cost?: number;
   durationMs?: number;
@@ -160,10 +162,11 @@ export type RuntypeExecutionStreamEvent = ({
   cacheWrite?: number;
   input: number;
   output: number;
+  reasoning?: number;
 };
   turnId?: string;
   type: "model_call_complete";
-} | {
+}) | {
   executionId: string;
   id: string;
   index?: number;
@@ -558,38 +561,50 @@ export type RuntypeStopReasonKind = NonNullable<
   RuntypeTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]
 >;
 
-export type RuntypeClientInitRequest = {
+export type RuntypeClientInitRequest = ({
   durableRecovery?: boolean;
   flowId?: string;
-  identityProof?: string;
+  identityProof?: string | {
+  provider: string;
+  token: string;
+};
   token: string;
   visitorHistory?: boolean;
   visitorToken?: string;
-} | {
+}) | ({
   durableRecovery?: boolean;
   flowId?: string;
-  identityProof?: string;
+  identityProof?: string | {
+  provider: string;
+  token: string;
+};
   sessionId: string;
   token: string;
   visitorHistory?: boolean;
   visitorToken?: string;
-} | {
+}) | ({
   conversationId: string;
   durableRecovery?: boolean;
   flowId?: string;
-  identityProof?: string;
+  identityProof?: string | {
+  provider: string;
+  token: string;
+};
   token: string;
   visitorHistory?: boolean;
   visitorToken: string;
-} | {
+}) | ({
   conversationId: string;
   durableRecovery?: boolean;
   flowId?: string;
-  identityProof: string;
+  identityProof: string | {
+  provider: string;
+  token: string;
+};
   token: string;
   visitorHistory?: boolean;
   visitorToken?: string;
-};
+});
 
 export type RuntypeClientInitResponse = {
   app?: {
@@ -604,7 +619,7 @@ export type RuntypeClientInitResponse = {
   conversationRevision: string;
   durableRecovery?: {
   enabled: boolean;
-  join?: boolean;
+  steer?: boolean;
 };
   expiresAt: string;
   flow?: {
@@ -666,7 +681,7 @@ export type RuntypeClientChatRequest = {
 }>;
   metadata?: Record<string, unknown>;
   sessionId: string;
-  submitMode?: "normal" | "interrupt" | "join";
+  submitMode?: "normal" | "interrupt" | "steer";
   turnId?: string;
 };
 

package/src/index-core.ts

@@ -9,6 +9,8 @@ export type {
   AgentWidgetStorageAdapter,
   AgentWidgetStoredState,
   AgentWidgetConfigPatch,
+  AgentWidgetSessionInitTrigger,
+  AgentWidgetSessionInitHook,
   TargetResolver,
   ResolvedTarget,
   AgentWidgetFeatureFlags,

package/src/install.test.ts

@@ -226,6 +226,30 @@ describe("install.ts: deferred launcher path", () => {
 
     expect(initAgentWidget).toHaveBeenCalledTimes(1);
   });
+
+  it.each([false, true])("passes future.v5Defaults=%s through the deferred launcher handoff", async (v5Defaults) => {
+    markCssLoaded();
+    provideFullBundle();
+    provideLauncherBundle();
+
+    const variant = v5Defaults ? "pill" : "circle";
+    await install({
+      config: { apiUrl: "/api", launcher: { variant } },
+      future: { v5Defaults },
+    });
+    await flush();
+
+    expect(launcherMount).toHaveBeenCalledWith(expect.objectContaining({
+      config: expect.objectContaining({ future: { v5Defaults }, launcher: expect.objectContaining({ variant }) }),
+    }));
+
+    capturedOnOpen!();
+    await flush();
+
+    expect(initAgentWidget).toHaveBeenCalledWith(expect.objectContaining({
+      config: expect.objectContaining({ future: { v5Defaults }, launcher: expect.objectContaining({ variant }) }),
+    }));
+  });
 });
 
 describe("install.ts: eager path", () => {

package/src/install.ts

@@ -19,6 +19,8 @@ interface SiteAgentInstallConfig {
   jsUrl?: string;
   target?: string | HTMLElement;
   config?: any;
+  /** Opt in to the staged v5 defaults when using top-level installer options. */
+  future?: { v5Defaults?: boolean };
   autoInit?: boolean;
   // Client token mode options (can also be set via data attributes)
   clientToken?: string;
@@ -447,6 +449,7 @@ declare global {
     if (config.clientToken && !widgetConfig.clientToken) widgetConfig.clientToken = config.clientToken;
     if (config.flowId && !widgetConfig.flowId) widgetConfig.flowId = config.flowId;
     if (config.agentId && !widgetConfig.agentId) widgetConfig.agentId = config.agentId;
+    if (config.future && !widgetConfig.future) widgetConfig.future = config.future;
 
     const hasApiConfig = !!(widgetConfig.apiUrl || widgetConfig.clientToken);
     return { target, widgetConfig, hasApiConfig };
@@ -631,4 +634,3 @@ declare global {
   // This prevents Next.js/Nuxt/etc. from removing dynamically added CSS
   waitForHydration(install);
 })();
-

package/src/launcher-global.ts

@@ -22,7 +22,7 @@
  */
 import { createLauncherSurface } from "./components/launcher";
 import { applyThemeVariables } from "./utils/theme";
-import { DEFAULT_LAUNCHER_CONFIG } from "./defaults";
+import { DEFAULT_LAUNCHER_CONFIG, DEFAULT_LAUNCHER_V5 } from "./defaults";
 import { setIconsExtraLoader } from "./icons-extra-loader";
 import type { AgentWidgetConfig } from "./types";
 
@@ -94,6 +94,7 @@ const mergeCriticalLauncherConfig = (
   ...config,
   launcher: {
     ...DEFAULT_LAUNCHER_CONFIG,
+    ...(config?.future?.v5Defaults === true ? DEFAULT_LAUNCHER_V5 : {}),
     ...config?.launcher,
     dock: {
       ...DEFAULT_LAUNCHER_CONFIG.dock,

package/src/launcher-variants.test.ts

@@ -0,0 +1,52 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createAgentExperience } from "./ui";
+import { mount as mountCritical } from "./launcher-global";
+import { getActiveTheme, themeToCssVariables } from "./utils/theme";
+import type { AgentWidgetConfig } from "./types";
+
+afterEach(() => { document.body.replaceChildren(); vi.restoreAllMocks(); });
+
+describe.each([false, true])("launcher variants (v5=%s)", (v5Defaults) => {
+  it.each([undefined, "pill", "circle"] as const)("matches deferred and full rendering for %s", (variant) => {
+    window.scrollTo = vi.fn();
+    const config: AgentWidgetConfig = {
+      apiUrl: "/dispatch", persistState: false, future: { v5Defaults },
+      launcher: { ...(variant ? { variant } : {}), title: "Open support", teaser: { text: "Need help?" } },
+    };
+    const host = document.body.appendChild(document.createElement("div"));
+    const target = document.body.appendChild(document.createElement("div"));
+    const full = createAgentExperience(host, config);
+    const critical = mountCritical({ target, config, onOpen: vi.fn() });
+    const button = host.querySelector<HTMLButtonElement>(".persona-launcher-surface > button")!;
+    try {
+      const circle = variant ? variant === "circle" : v5Defaults;
+      expect(button.dataset.personaLauncherVariant).toBe(circle ? "circle" : undefined);
+      expect(button.innerHTML).toBe(critical.element.innerHTML);
+      expect(button.getAttribute("style")).toBe(critical.element.getAttribute("style"));
+      expect(host.style.getPropertyValue("--persona-launcher-bg"))
+        .toBe(critical.root.style.getPropertyValue("--persona-launcher-bg"));
+      if (circle) expect(button.getAttribute("aria-label")).toBe("Open support");
+      full.update({ launcher: { variant: circle ? "pill" : "circle" } });
+      critical.update({ ...config, launcher: { ...config.launcher, variant: circle ? "pill" : "circle" } });
+      expect(button.dataset.personaLauncherVariant).toBe(circle ? undefined : "circle");
+      expect(button.innerHTML).toBe(critical.element.innerHTML);
+    } finally { full.destroy(); critical.destroy(); }
+  });
+
+  it.each(["light", "dark"] as const)("resolves circle geometry and explicit tokens in %s", colorScheme => {
+    const config: AgentWidgetConfig = { future: { v5Defaults }, colorScheme, launcher: { variant: "circle" } };
+    const css = themeToCssVariables(getActiveTheme(config));
+    expect(css["--persona-components-launcher-size"]).toBe("48px");
+    expect(css["--persona-components-launcher-offset"]).toBe("20px");
+    expect(css["--persona-launcher-shadow"]).toBe("0 8px 24px rgba(0,0,0,.16)");
+    expect(css["--persona-launcher-bg"]).not.toBe(css["--persona-launcher-fg"]);
+    const custom = themeToCssVariables(getActiveTheme({ ...config, theme: { components: { launcher: {
+      size: "56px", iconSize: "20px", offset: "32px", background: "#123456", foreground: "#ffffff", shadow: "none",
+    } } } }));
+    expect(custom["--persona-components-launcher-size"]).toBe("56px");
+    expect(custom["--persona-components-launcher-offset"]).toBe("32px");
+    expect(custom["--persona-launcher-bg"]).toBe("#123456");
+    expect(custom["--persona-launcher-shadow"]).toBe("none");
+  });
+});

package/src/runtime/init-update-reset.test.ts

@@ -78,4 +78,25 @@ describe("handle.update explicit-undefined reset reaches the controller", () =>
 
     handle.destroy();
   });
+
+  it("updates the root defaults-version attribute", () => {
+    window.scrollTo = vi.fn();
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const handle = initAgentWidget({
+      target: "#target",
+      config: {
+        apiUrl: "https://api.example.com/chat",
+        launcher: { enabled: false },
+        future: { v5Defaults: false },
+      },
+    });
+    const root = () => document.querySelector<HTMLElement>("[data-persona-root]")!;
+
+    expect(root().getAttribute("data-persona-defaults")).toBe("v4");
+    handle.update({ future: { v5Defaults: true } });
+    expect(root().getAttribute("data-persona-defaults")).toBe("v5");
+
+    handle.destroy();
+  });
 });

package/src/session.ts

@@ -144,6 +144,7 @@ const CONNECTION_CONFIG_KEYS = [
   "getStoredSessionId",
   "setStoredSessionId",
   "getIdentityProof",
+  "identityProvider",
   "getStoredConversationId",
   "setStoredConversationId",
   "clearStoredConversationId",
@@ -1033,12 +1034,29 @@ export class AgentWidgetSession {
     }
   }
 
+  /**
+   * Early, fire-and-forget client-token init (`sessionInit` trigger or
+   * `controller.initSession()`). Failures stay silent here: no `onError`, no
+   * UI. The send re-runs `initSession()` and reports them as it always has.
+   */
+  public warmClientSession(): void {
+    // The visitor may send before this resolves; the server welcome still
+    // belongs ahead of that first turn when the transcript started empty.
+    const pristine = !this.messages.length;
+    void this.client.warmSession().then((session) => {
+      // A start-new or credential re-init may have replaced it meanwhile.
+      if (session && this.client.getClientSession() === session) {
+        this.setClientSession(session, pristine);
+      }
+    });
+  }
+
   /**
    * Set the client session after initialization
    */
-  public setClientSession(session: ClientSession): void {
+  public setClientSession(session: ClientSession, pristine?: boolean): void {
     this.clientSession = session;
-    this.injectWelcomeMessage(session);
+    this.injectWelcomeMessage(session, pristine);
   }
 
   /**
@@ -1046,15 +1064,20 @@ export class AgentWidgetSession {
    * reopening a stored conversation is not a new thread, and the hydrated
    * transcript would otherwise race a welcome bubble.
    */
-  private injectWelcomeMessage(session: ClientSession): void {
+  private injectWelcomeMessage(
+    session: ClientSession,
+    pristine = !this.messages.length
+  ): void {
     if (this.suppressWelcomeInjection) return;
-    if (!session.config.welcomeMessage || this.messages.length !== 0) return;
+    if (!session.config.welcomeMessage || !pristine) return;
+    // A late welcome (the first send raced the init) sorts ahead of that turn.
+    const first = this.messages[0];
     const welcomeMessage: AgentWidgetMessage = {
       id: `welcome-${Date.now()}`,
       role: "assistant",
       content: session.config.welcomeMessage,
-      createdAt: new Date().toISOString(),
-      sequence: this.nextSequence()
+      createdAt: first?.createdAt ?? new Date().toISOString(),
+      sequence: first ? (first.sequence ?? 0) - 1 : this.nextSequence()
     };
     this.appendMessage(welcomeMessage);
   }
@@ -3816,16 +3839,34 @@ export class AgentWidgetSession {
       // re-emits don't re-execute the page tool, then complete each bubble.
       // Do this only after /resume HTTP success; if /resume fails, the server
       // may still be paused and the retry path must not show a final result.
+      const batch = ready[0]!.dedupeKey;
       for (const r of ready) {
         this.webMcpResolvedKeys.add(r.dedupeKey);
+        const toolName = r.toolMessage.toolCall?.name;
+        const toolCallId = r.toolMessage.agentMetadata?.webMcpToolCallId;
         this.markWebMcpToolComplete(
           r.toolMessage,
           r.output,
           r.startedAt,
           r.completedAt,
-          r.toolMessage.toolCall?.name === SUGGEST_REPLIES_TOOL_NAME
-            ? { suggestRepliesResolved: true }
-            : undefined,
+          {
+            ...(toolName === SUGGEST_REPLIES_TOOL_NAME
+              ? { suggestRepliesResolved: true }
+              : {}),
+            // Only a provider call id can be replayed: a legacy name-keyed
+            // resume has nothing the model's transcript can reference.
+            ...(toolName && toolCallId
+              ? {
+                  clientToolAnswer: {
+                    toolCallId,
+                    toolName,
+                    args: r.toolMessage.toolCall?.args,
+                    result: r.output,
+                    batch,
+                  },
+                }
+              : {}),
+          },
         );
       }
       if (response.body) {
@@ -4928,6 +4969,17 @@ export class AgentWidgetSession {
           awaitingLocalTool: false,
         };
       }
+      // The accepted client-tool answer is what later proxy/agent turns
+      // replay; a post-resume `tool_complete` re-emit carries a fresh
+      // metadata skeleton and must not drop it.
+      const clientToolAnswer = existing.agentMetadata?.clientToolAnswer;
+      if (
+        clientToolAnswer &&
+        merged.agentMetadata &&
+        !merged.agentMetadata.clientToolAnswer
+      ) {
+        merged.agentMetadata = { ...merged.agentMetadata, clientToolAnswer };
+      }
       // Approval equivalent: `approval_complete` carries only the
       // resolution (approvalId, decision, resolvedBy): the runtime does not
       // re-send toolName/description/toolType/reason/parameters, so client.ts

package/src/styles/widget-styles.test.ts

@@ -189,6 +189,25 @@ describe("suggestion interaction styles", () => {
   });
 });
 
+describe("collapsible widget chrome styles", () => {
+  it("uses prefixed aliases while retaining each legacy alias and literal fallback", () => {
+    const expectedDeclarations: Array<[string, number]> = [
+      ["var(--persona-cw-border, var(--cw-border, #e5e7eb))", 2],
+      ["var(--persona-cw-container, var(--cw-container, #f9fafb))", 1],
+      ["var(--persona-cw-surface, var(--cw-surface, #ffffff))", 2],
+      ["var(--persona-cw-border, var(--cw-border, #f1f5f9))", 1],
+      ["var(--persona-cw-container, var(--cw-container, #f8fafc))", 1],
+      ["var(--persona-cw-border, var(--cw-border, #d1d5db))", 1],
+      ["var(--persona-cw-surface, var(--cw-surface, #fff))", 2],
+    ];
+
+    for (const [declaration, count] of expectedDeclarations) {
+      expect(widgetCss).toContain(declaration);
+      expect(widgetCss.split(declaration).length - 1).toBe(count);
+    }
+  });
+});
+
 describe("composer spacing styles", () => {
   it("themes the composer form padding and gap with utility-matching fallbacks", () => {
     const selector =