@runtypelabs/persona 4.22.1 → 4.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.22.1",
+  "version": "4.23.1",
   "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-session-renewal.test.ts

@@ -0,0 +1,268 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AgentWidgetClient } from "./client";
+import type { AgentWidgetEvent, ClientSession } from "./types";
+import { createVisitorStore } from "./utils/visitor-store";
+
+const message = {
+  id: "user-1",
+  role: "user" as const,
+  content: "continue",
+  createdAt: "2026-09-22T00:00:00Z",
+};
+const options = { messages: [message], assistantMessageId: "assistant-1" };
+const session = (milliseconds = 600_000): ClientSession => ({
+  sessionId: "session-old",
+  conversationId: "conversation-owned",
+  expiresAt: new Date(Date.now() + milliseconds),
+  durableRecovery: { enabled: true },
+  flow: { id: "agent-1", name: "Agent", description: null },
+  config: { welcomeMessage: null, placeholder: "Ask...", theme: null },
+});
+const expired = () =>
+  Response.json({ error: "Session not found or expired" }, { status: 401 });
+const success = () =>
+  new Response('data: {"type":"done"}\n\n', {
+    headers: { "Content-Type": "text/event-stream" },
+  });
+
+async function setup(milliseconds = 600_000) {
+  const onSessionInit = vi.fn();
+  const onSessionExpired = vi.fn();
+  const setStoredSessionId = vi.fn();
+  const store = createVisitorStore("ct_test_renewal", "renewal-", true);
+  await store.set("cvt_owned");
+  const client = new AgentWidgetClient({
+    clientToken: "ct_test_renewal",
+    apiUrl: "https://example.com",
+    onSessionInit,
+    onSessionExpired,
+    setStoredSessionId,
+  });
+  client.setHistoryInternals({ visitorStore: store });
+  (client as unknown as { clientSession: ClientSession }).clientSession =
+    session(milliseconds);
+  const requests: Array<{
+    url: string;
+    body: Record<string, unknown>;
+    headers: Headers;
+  }> = [];
+  const chat = vi
+    .fn<() => Response | Promise<Response>>()
+    .mockImplementation(success);
+  const initialize = vi
+    .fn<() => Response | Promise<Response>>()
+    .mockImplementation(() =>
+      Response.json({ ...session(), sessionId: "session-new" }),
+    );
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init: RequestInit) => {
+      requests.push({
+        url,
+        body: JSON.parse(String(init.body)),
+        headers: new Headers(init.headers),
+      });
+      return url.endsWith("/init") ? initialize() : chat();
+    }),
+  );
+  const events: AgentWidgetEvent[] = [];
+  const run = (signal?: AbortSignal) =>
+    client.dispatch({ ...options, signal }, (event) => events.push(event));
+  return {
+    client,
+    store,
+    requests,
+    chat,
+    initialize,
+    onSessionInit,
+    onSessionExpired,
+    setStoredSessionId,
+    events,
+    run,
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("client token session renewal", () => {
+  it("renews a legacy session through its session ID without enabling shared history", async () => {
+    const h = await setup(30_000);
+    (h.client as unknown as { clientSession: ClientSession }).clientSession = {
+      ...session(30_000),
+      durableRecovery: { enabled: false },
+    };
+    h.initialize.mockImplementation(() =>
+      Response.json({
+        ...session(),
+        sessionId: "session-new",
+        durableRecovery: { enabled: false },
+      }),
+    );
+    await h.run();
+    expect(h.requests[0].body).toMatchObject({ sessionId: "session-old" });
+    expect(h.requests[0].body).not.toHaveProperty("conversationId");
+    expect(h.requests[0].body).not.toHaveProperty("visitorHistory");
+    expect(h.requests[1].body.sessionId).toBe("session-new");
+    expect(h.onSessionExpired).not.toHaveBeenCalled();
+  });
+
+  it("resends the full tool registry after renewal rather than reusing the old fingerprint alone", async () => {
+    const h = await setup();
+    const tools = [{ name: "search", description: "Search", origin: "webmcp" }];
+    (h.client as unknown as { webMcpBridge: unknown }).webMcpBridge = {
+      snapshotForDispatch: () => tools,
+    };
+    await h.run();
+    h.chat.mockImplementationOnce(expired);
+    await h.run();
+    const bodies = h.requests
+      .filter((r) => r.url.endsWith("/chat"))
+      .map((r) => r.body);
+    expect(bodies[0].clientTools).toEqual(tools);
+    expect(bodies[1].clientTools).toBeUndefined();
+    expect(bodies[2].clientTools).toEqual(tools);
+    expect(bodies[2].clientToolsFingerprint).toBe(
+      bodies[1].clientToolsFingerprint,
+    );
+  });
+
+  it.each([30_000, -1])(
+    "renews a session with %i ms left and preserves visitor-owned conversation without history UI",
+    async (milliseconds) => {
+      const h = await setup(milliseconds);
+      await h.run();
+      expect(h.requests.map((r) => r.url)).toEqual([
+        "https://example.com/v1/client/init",
+        "https://example.com/v1/client/chat",
+      ]);
+      expect(h.requests[0].body).toMatchObject({
+        conversationId: "conversation-owned",
+        visitorToken: "cvt_owned",
+        durableRecovery: true,
+      });
+      expect(h.requests[0].body).not.toHaveProperty("sessionId");
+      expect(h.requests[1].body).toMatchObject({
+        sessionId: "session-new",
+        assistantMessageId: "assistant-1",
+        messages: [{ id: "user-1", content: "continue" }],
+      });
+      expect(h.requests[1].headers.get("X-Visitor-Token")).toBe("cvt_owned");
+      expect(h.onSessionInit).toHaveBeenCalledTimes(1);
+      expect(h.onSessionExpired).not.toHaveBeenCalled();
+      expect(h.setStoredSessionId).toHaveBeenCalledWith("session-new");
+    },
+  );
+
+  it("retries only an explicit expired-session rejection with the same payload and turn identity", async () => {
+    const h = await setup();
+    h.chat.mockImplementationOnce(expired);
+    await h.run();
+    const bodies = h.requests
+      .filter((r) => r.url.endsWith("/chat"))
+      .map((r) => r.body);
+    expect(bodies).toHaveLength(2);
+    expect(bodies[1]).toEqual({ ...bodies[0], sessionId: "session-new" });
+    expect(h.onSessionExpired).not.toHaveBeenCalled();
+  });
+
+  it("stops after a second expired-session rejection", async () => {
+    const h = await setup();
+    h.chat.mockImplementation(expired);
+    await expect(h.run()).rejects.toThrow("Session expired");
+    expect(h.chat).toHaveBeenCalledTimes(2);
+    expect(h.initialize).toHaveBeenCalledTimes(1);
+    expect(h.onSessionExpired).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not retry an unrelated unauthorized response", async () => {
+    const h = await setup();
+    h.chat.mockImplementation(() =>
+      Response.json({ error: "Unauthorized" }, { status: 401 }),
+    );
+    await expect(h.run()).rejects.toThrow("Session expired");
+    expect(h.chat).toHaveBeenCalledTimes(1);
+    expect(h.initialize).not.toHaveBeenCalled();
+  });
+
+  it("does not renew or replay after cancellation during the rejected request", async () => {
+    const h = await setup();
+    const abort = new AbortController();
+    h.chat.mockImplementation(() => {
+      abort.abort();
+      return expired();
+    });
+    await expect(h.run(abort.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(h.initialize).not.toHaveBeenCalled();
+    expect(h.chat).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not install a renewal or post a message after cancellation during init", async () => {
+    const h = await setup(30_000);
+    const abort = new AbortController();
+    h.initialize.mockImplementation(() => {
+      abort.abort();
+      return Response.json({ ...session(), sessionId: "session-new" });
+    });
+    await expect(h.run(abort.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(h.chat).not.toHaveBeenCalled();
+    expect(h.onSessionInit).not.toHaveBeenCalled();
+    expect(h.setStoredSessionId).not.toHaveBeenCalled();
+  });
+
+  it("does not fork a conversation when renewal cannot reopen it", async () => {
+    const h = await setup(30_000);
+    h.initialize.mockImplementation(() =>
+      Response.json({ error: "not_found" }, { status: 404 }),
+    );
+    await expect(h.run()).rejects.toThrow("Conversation not found");
+    expect(h.initialize).toHaveBeenCalledTimes(1);
+    expect(h.chat).not.toHaveBeenCalled();
+  });
+
+  it("rejects a server response that switches conversations", async () => {
+    const h = await setup(30_000);
+    h.initialize.mockImplementation(() =>
+      Response.json({ ...session(), conversationId: "different" }),
+    );
+    await expect(h.run()).rejects.toThrow("did not preserve");
+    expect(h.chat).not.toHaveBeenCalled();
+    expect(h.onSessionInit).not.toHaveBeenCalled();
+  });
+
+  it("does not renew a durable conversation without visitor proof", async () => {
+    const h = await setup(30_000);
+    await h.store.clear();
+    await expect(h.run()).rejects.toThrow("visitor credential");
+    expect(h.initialize).not.toHaveBeenCalled();
+    expect(h.chat).not.toHaveBeenCalled();
+  });
+
+  it("suppresses a superseded turn while its expired-session response is pending", async () => {
+    const h = await setup();
+    let rejectOld!: (response: Response) => void;
+    let started!: () => void;
+    const firstStarted = new Promise<void>((resolve) => {
+      started = resolve;
+    });
+    h.chat.mockImplementationOnce(() => {
+      started();
+      return new Promise((resolve) => {
+        rejectOld = resolve;
+      });
+    });
+    const first = h.run();
+    await firstStarted;
+    await h.run();
+    rejectOld(expired());
+    await expect(first).rejects.toMatchObject({ name: "AbortError" });
+    expect(h.initialize).not.toHaveBeenCalled();
+    expect(h.chat).toHaveBeenCalledTimes(2);
+  });
+});

package/src/client-visitor-history.test.ts

@@ -1080,3 +1080,89 @@ describe('client visitor history - dedupe', () => {
     expect(h.sessionInits).toHaveLength(1);
   });
 });
+
+describe('voice integration visitor credential access', () => {
+  const controllers: ReturnType<typeof createAgentExperience>[] = [];
+  const mountWidget = (config: Partial<AgentWidgetConfig> = {}) => {
+    const mount = document.createElement('div');
+    document.body.appendChild(mount);
+    const controller = createAgentExperience(mount, {
+      apiUrl: API_URL,
+      clientToken: CLIENT_TOKEN,
+      launcher: { enabled: false },
+      ...config,
+    });
+    controllers.push(controller);
+    return controller;
+  };
+
+  afterEach(() => {
+    controllers.forEach((controller) => controller.destroy());
+    controllers.length = 0;
+    document.body.innerHTML = '';
+  });
+
+  it('reads minted proof after the claim response omits it without enriching the callback', async () => {
+    const minted = { id: 'vis_1', token: 'cvt_minted', expiresAt: futureIso(), endUserId: null };
+    installFetch([
+      ok({ sessionId: 'sess_first', visitor: minted }),
+      ok({ sessionId: 'sess_claimed', visitor: { ...minted, token: undefined } }),
+    ]);
+    const onSessionInit = vi.fn();
+    const controller = mountWidget({ persistState: false, onSessionInit });
+    await vi.waitFor(() => expect(onSessionInit).toHaveBeenCalledOnce());
+    expect(onSessionInit.mock.calls[0][0].visitor.token).toBeUndefined();
+    await expect(controller.getVisitorToken()).resolves.toBe('cvt_minted');
+    expect(JSON.stringify(controller.getState())).not.toContain('cvt_minted');
+    expect(window.localStorage.getItem(await storageKeyFor())).toBeNull();
+  });
+
+  it('reads the current persisted credential after reload and after rotation or removal', async () => {
+    await seedToken('cvt_stored');
+    installFetch([ok()]);
+    const controller = mountWidget();
+    await expect(controller.getVisitorToken()).resolves.toBe('cvt_stored');
+    await seedToken('cvt_rotated');
+    await expect(controller.getVisitorToken()).resolves.toBe('cvt_rotated');
+    window.localStorage.removeItem(await storageKeyFor());
+    await expect(controller.getVisitorToken()).resolves.toBeNull();
+  });
+
+  it('does not return credentials from a replaced client-token scope', async () => {
+    await seedToken('cvt_stored');
+    installFetch([ok(), ok()]);
+    const controller = mountWidget();
+    await vi.waitFor(() => expect(requests).toHaveLength(1));
+    const pending = controller.getVisitorToken();
+    controller.update({ clientToken: 'ct_other' });
+    await expect(pending).resolves.toBeNull();
+    await expect(controller.getVisitorToken()).resolves.toBeNull();
+  });
+
+  it('returns null after teardown, including a read already in flight', async () => {
+    await seedToken('cvt_stored');
+    installFetch([ok()]);
+    const controller = mountWidget();
+    await vi.waitFor(() => expect(requests).toHaveLength(1));
+    const pending = controller.getVisitorToken();
+    controller.destroy();
+    controllers.length = 0;
+    await expect(pending).resolves.toBeNull();
+    await expect(controller.getVisitorToken()).resolves.toBeNull();
+  });
+
+  it('returns null when no credential has been minted', async () => {
+    installFetch([ok()]);
+    const controller = mountWidget({ persistState: false });
+    await expect(controller.getVisitorToken()).resolves.toBeNull();
+  });
+
+  it('does not fetch or mint a visitor outside client-token mode', async () => {
+    const fetch = vi.fn();
+    vi.stubGlobal('fetch', fetch);
+    const controller = mountWidget({ clientToken: undefined });
+    await expect(controller.getVisitorToken()).resolves.toBeNull();
+    expect(fetch).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+});

package/src/client.interrupt.test.ts

@@ -111,7 +111,7 @@ describe("client-token turn identity", () => {
     );
     // Let the first dispatch claim the turn and start streaming.
     await vi.waitFor(() =>
-      expect(firstEvents.some((e) => e.type === "status")).toBe(true)
+      expect(firstEvents.some((e) => e.type === "status" && e.status === "connected")).toBe(true)
     );
 
     const secondDispatch = client.dispatch({ messages, interrupt: true }, (event) =>

package/src/client.ts

@@ -755,6 +755,7 @@ export class AgentWidgetClient {
     identityProof?: string | null;
     storedSessionId?: string | null;
     omitVisitorFields?: boolean;
+    signal?: AbortSignal;
   }): Promise<ClientSession> {
     const historyCapable = this.isHistoryCapable() && !opts.omitVisitorFields;
     // Recovery is negotiated independently from the history UI. New servers
@@ -792,6 +793,7 @@ export class AgentWidgetClient {
           : {}),
     };
 
+    opts.signal?.throwIfAborted();
     const response = await fetch(this.getClientApiUrl('init'), {
       method: 'POST',
       headers: {
@@ -799,6 +801,7 @@ export class AgentWidgetClient {
         'X-Persona-Version': VERSION,
       },
       body: JSON.stringify(requestBody),
+      signal: opts.signal,
     });
 
     if (!response.ok) {
@@ -1805,25 +1808,44 @@ export class AgentWidgetClient {
     onEvent({ type: "status", status: "connecting" });
 
     try {
-      // Ensure session is initialized
-      const session = await this.initSession();
-
-      // Check if session is about to expire (within 1 minute)
-      if (new Date() >= new Date(session.expiresAt.getTime() - 60000)) {
-        // Session expired or expiring soon
-        this.clearClientSession();
-        this.config.onSessionExpired?.();
-        const error = new Error('Session expired. Please refresh to continue.');
-        forward({ type: "error", error });
-        throw error;
+      const assertCurrentTurn = () => {
+        options.signal?.throwIfAborted();
+        if (!isCurrentTurn()) throw new DOMException('Turn superseded', 'AbortError');
+      };
+      let session = this.clientSession ?? (await this.initSession());
+      assertCurrentTurn();
+      const renewSession = async () => {
+        assertCurrentTurn();
+        const previous = session;
+        const durable = previous.durableRecovery?.enabled === true;
+        if (durable && (!previous.conversationId || !(await this.readVisitorToken()))) {
+          throw new Error('Renewing this conversation requires its visitor credential.');
+        }
+        assertCurrentTurn();
+        const renewed = await this.createClientSession({
+          ...(durable || this.isHistoryCapable()
+            ? { conversationId: previous.conversationId, durableResume: durable }
+            : { storedSessionId: previous.sessionId }),
+          signal: options.signal,
+        });
+        assertCurrentTurn();
+        if (
+          (previous.conversationId && renewed.conversationId !== previous.conversationId) ||
+          (durable && renewed.durableRecovery?.enabled !== true)
+        ) {
+          throw new Error('Session renewal did not preserve this conversation.');
+        }
+        session = this.finishInit(renewed, previous.conversationId ?? null, false);
+        this.clientSession = session;
+        this.resetClientToolsFingerprint();
+        this.config.onSessionInit?.(session);
+      };
+      if (Date.now() >= session.expiresAt.getTime() - 60000) {
+        await renewSession();
       }
 
       // Build the standard payload to get context/metadata from middleware
       const basePayload = await this.buildPayload(options.messages);
-      const recoveryVisitorToken =
-        session.durableRecovery?.enabled === true
-          ? await this.readVisitorToken()
-          : null;
 
       // Build the chat request payload with message IDs for feedback tracking
       // Filter out sessionId from metadata if present (it's only for local storage)
@@ -1869,9 +1891,17 @@ export class AgentWidgetClient {
       // ship it again or just its fingerprint (retrying once on a 409 registry
       // miss). The cache is committed only after a successful stream start
       // (below), so a 409/failure leaves it untouched.
-      const { response, commit: commitClientToolsFingerprint } =
-        await this.sendWithClientToolsDiff(session.sessionId, basePayload.clientTools, (toolFields) => {
-          const chatRequest: ClientChatRequest = { ...baseChatRequest, ...toolFields };
+      const send = async () => {
+        assertCurrentTurn();
+        const recoveryVisitorToken =
+          session.durableRecovery?.enabled === true ? await this.readVisitorToken() : null;
+        assertCurrentTurn();
+        return this.sendWithClientToolsDiff(session.sessionId, basePayload.clientTools, (toolFields) => {
+          const chatRequest: ClientChatRequest = {
+            ...baseChatRequest,
+            sessionId: session.sessionId,
+            ...toolFields,
+          };
 
           if (this.debug) {
             // eslint-disable-next-line no-console
@@ -1891,6 +1921,19 @@ export class AgentWidgetClient {
             signal: options.signal,
           });
         });
+      };
+      let result = await send();
+      assertCurrentTurn();
+      if (result.response.status === 401) {
+        const rejection = await result.response.clone().json().catch(() => null);
+        assertCurrentTurn();
+        if (rejection?.error === 'Session not found or expired') {
+          await renewSession();
+          result = await send();
+          assertCurrentTurn();
+        }
+      }
+      const { response, commit: commitClientToolsFingerprint } = result;
 
       if (!response.ok) {
         const data = await response.json().catch(() => ({ error: 'Chat request failed' }));

package/src/launcher-global.ts

@@ -13,7 +13,7 @@
  * EXTRA-tier icon (`launcher.agentIconName: "shopping-cart"`) paints a
  * correctly-sized empty placeholder and fills within one round-trip of the
  * `icons-extra.js` sibling chunk (loader registered below). See the
- * "Deferred Launcher Loading" pattern in CLAUDE.md.
+ * "Deferred Launcher Loading" pattern in AGENTS.md.
  *
  * Public global (via tsup `--global-name AgentWidgetLauncher`):
  *

package/src/ui.ts

@@ -731,6 +731,12 @@ type Controller = {
    * Required host logout wiring.
    */
   resetHistoryIdentity: () => Promise<{ remoteRevocationConfirmed: boolean }>;
+  /**
+   * Read the current browser visitor credential for a trusted voice integration.
+   * Returns null before minting, outside client-token mode, or after teardown.
+   * Never put this bearer credential in logs, URLs, or model context.
+   */
+  getVisitorToken: () => Promise<string | null>;
   /** Latest sanitized identity state; carries no token, proof, or identity id. */
   getHistoryIdentityStatus: () => HistoryIdentityStatus;
   /** `focus: false` keeps focus where it is (programmatic/preview opens). */
@@ -8982,6 +8988,7 @@ export const createAgentExperience = (
   destroyCallbacks.push(() => {
     session.destroy();
     visitorStore?.destroy();
+    visitorStore = null;
   });
 
   // Mirror read-aloud playback state into the action buttons, and surface it as
@@ -15215,6 +15222,12 @@ export const createAgentExperience = (
     resetHistoryIdentity(): Promise<{ remoteRevocationConfirmed: boolean }> {
       return resetHistoryIdentity();
     },
+    async getVisitorToken(): Promise<string | null> {
+      const store = visitorStore;
+      if (!store) return null;
+      const token = await store.get();
+      return store === visitorStore ? token : null;
+    },
     getHistoryIdentityStatus(): HistoryIdentityStatus {
       if (!historyProvider) {
         return historyFeatureEnabled()