@runtypelabs/persona 4.23.1 → 4.24.0

package/src/approval-ui-entry.ts

@@ -6,7 +6,6 @@
  * `approval-ui-loader.ts`. See `src/approval-ui.ts` for the transport module.
  */
 export {
-  approvalDetailsExpansionState,
   createApprovalBubble,
   humanizeToolName,
   updateApprovalDetailsUI,

package/src/approval-ui-loader.ts

@@ -12,18 +12,19 @@ import type { ApprovalUiDeps } from "./components/approval-deps";
  * `history-view-loader.ts` for the full rationale).
  */
 export type ApprovalUiModule = {
-  approvalDetailsExpansionState: Map<string, boolean>;
   createApprovalBubble: (
     message: AgentWidgetMessage,
-    config?: AgentWidgetConfig
+    config?: AgentWidgetConfig,
+    expansionState?: Map<string, boolean>
   ) => HTMLElement;
   updateApprovalDetailsUI: (
     messageId: string,
     bubble: HTMLElement,
-    config?: AgentWidgetConfig
+    config?: AgentWidgetConfig,
+    expansionState?: Map<string, boolean>
   ) => void;
   humanizeToolName: (toolName: string) => string;
-  createBuiltInApprovalPlugin: () => {
+  createBuiltInApprovalPlugin: (expansionState?: Map<string, boolean>) => {
     plugin: AgentWidgetPlugin;
     teardown: () => void;
   };

package/src/approval-ui.ts

@@ -8,7 +8,6 @@
  * external subpath.
  */
 export {
-  approvalDetailsExpansionState,
   createApprovalBubble,
   createBuiltInApprovalPlugin,
   humanizeToolName,

package/src/client-identity-proof.test.ts

@@ -0,0 +1,193 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AgentWidgetClient } from './client';
+import type { AgentWidgetConfig, AgentWidgetEvent } from './types';
+
+const success = () => new Response('data: {"type":"done"}\n\n', {
+  headers: { 'Content-Type': 'text/event-stream' },
+});
+
+function setup(config: Partial<AgentWidgetConfig> = {}) {
+  const getIdentityProof = vi.fn<() => string | null | Promise<string | null>>()
+    .mockReturnValue('fresh-proof');
+  const onSessionExpired = vi.fn();
+  const client = new AgentWidgetClient({
+    apiUrl: 'https://example.com',
+    clientToken: 'ct_test_identity',
+    identityProvider: 'clerk',
+    getIdentityProof,
+    onSessionExpired,
+    ...config,
+  });
+  const requests: Array<{ url: string; body: Record<string, unknown> }> = [];
+  const chat = vi.fn<() => Response>().mockImplementation(success);
+  let sessionNumber = 0;
+  vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => {
+    requests.push({ url, body: JSON.parse(String(init.body)) });
+    if (url.endsWith('/init')) {
+      return Response.json({
+        sessionId: `session-${++sessionNumber}`,
+        expiresAt: new Date(Date.now() + 600_000).toISOString(),
+        flow: { id: 'agent-1', name: 'Agent', description: null },
+        config: { welcomeMessage: null, placeholder: 'Ask...', theme: null },
+      });
+    }
+    return chat();
+  }));
+  const events: AgentWidgetEvent[] = [];
+  const run = (signal?: AbortSignal) => client.dispatch({
+    messages: [{ id: 'message-1', role: 'user', content: 'Show my orders', createdAt: '2026-09-25' }],
+    signal,
+  }, (event) => events.push(event));
+  const chatBodies = () => requests.filter((r) => r.url.endsWith('/chat')).map((r) => r.body);
+  return { client, getIdentityProof, chat, requests, run, chatBodies, events, onSessionExpired };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe('client token execution identity', () => {
+  it.each([undefined, false, true])('sends the first turn proof with history enabled=%s', async (enabled) => {
+    const h = setup({ features: { history: { enabled } } });
+    h.chat.mockImplementation(() => h.chatBodies().at(-1)?.identityProof
+      ? success()
+      : Response.json({ error: 'Tenant scope required' }, { status: 403 }));
+    await h.run();
+    expect(h.chatBodies()[0].identityProof).toEqual({ provider: 'clerk', token: 'fresh-proof' });
+    expect(h.getIdentityProof).toHaveBeenCalledTimes(1);
+  });
+
+  it('gets a new proof on every turn without persisting it into session state', async () => {
+    const setStoredSessionId = vi.fn();
+    const h = setup({ setStoredSessionId });
+    h.getIdentityProof.mockReturnValueOnce('first-proof').mockReturnValueOnce('second-proof');
+    await h.run();
+    await h.run();
+    expect(h.chatBodies().map((b) => b.identityProof)).toEqual([
+      { provider: 'clerk', token: 'first-proof' },
+      { provider: 'clerk', token: 'second-proof' },
+    ]);
+    expect(JSON.stringify(setStoredSessionId.mock.calls)).not.toContain('proof');
+    expect(h.requests.filter((r) => r.url.endsWith('/init'))).toHaveLength(1);
+  });
+
+  it('refreshes the proof when an expired session causes a retry', async () => {
+    const h = setup();
+    h.getIdentityProof.mockReturnValueOnce('before-renewal').mockReturnValueOnce('after-renewal');
+    h.chat.mockImplementationOnce(() => Response.json({ error: 'Session not found or expired' }, { status: 401 }));
+    await h.run();
+    expect(h.chatBodies().map((b) => b.identityProof)).toEqual([
+      { provider: 'clerk', token: 'before-renewal' },
+      { provider: 'clerk', token: 'after-renewal' },
+    ]);
+    expect(h.chatBodies()[1].sessionId).toBe('session-2');
+  });
+
+  it('refreshes the proof on a tool registry cache-miss retry', async () => {
+    const h = setup();
+    (h.client as unknown as { webMcpBridge: unknown }).webMcpBridge = {
+      snapshotForDispatch: () => [{ name: 'search', description: 'Search', origin: 'webmcp' }],
+    };
+    await h.run();
+    h.getIdentityProof.mockReturnValueOnce('before-retry').mockReturnValueOnce('after-retry');
+    h.chat.mockImplementationOnce(() => Response.json({ error: 'client_tools_resend_required' }, { status: 409 }));
+    await h.run();
+    expect(h.chatBodies().slice(1).map((b) => b.identityProof)).toEqual([
+      { provider: 'clerk', token: 'before-retry' },
+      { provider: 'clerk', token: 'after-retry' },
+    ]);
+  });
+
+  it.each([null, ''])('does not send a chat request when the configured provider returns %s', async (proof) => {
+    const h = setup();
+    h.getIdentityProof.mockReturnValue(proof);
+    await expect(h.run()).rejects.toThrow('identity proof');
+    expect(h.chat).not.toHaveBeenCalled();
+    expect(h.events.some((event) => event.type === 'error')).toBe(true);
+  });
+
+  it('fails visibly without exposing an exception from the proof callback', async () => {
+    const h = setup();
+    h.getIdentityProof.mockRejectedValue(new Error('secret-proof-in-provider-error'));
+    await expect(h.run()).rejects.toThrow('identity proof provider failed');
+    expect(h.chat).not.toHaveBeenCalled();
+    expect(h.events.filter((e) => e.type === 'error').map((e) => e.error.message).join()).not.toContain('secret-proof');
+  });
+
+  it('requires a callback when a provider is configured', async () => {
+    const h = setup({ getIdentityProof: undefined });
+    await expect(h.run()).rejects.toThrow('getIdentityProof');
+    expect(h.chat).not.toHaveBeenCalled();
+  });
+
+  it('preserves history-only callbacks when execution identity is not configured', async () => {
+    const h = setup({ identityProvider: undefined });
+    await h.run();
+    expect(h.getIdentityProof).not.toHaveBeenCalled();
+    expect(h.chatBodies()[0]).not.toHaveProperty('identityProof');
+  });
+
+  it('does not send a turn cancelled while its proof is being obtained', async () => {
+    const h = setup();
+    let resolveProof!: (proof: string) => void;
+    h.getIdentityProof.mockReturnValue(new Promise<string>((resolve) => { resolveProof = resolve; }));
+    const abort = new AbortController();
+    const running = h.run(abort.signal).catch((error: unknown) => error);
+    await vi.waitFor(() => expect(h.getIdentityProof).toHaveBeenCalled());
+    abort.abort();
+    resolveProof('late-proof');
+    expect(await running).toMatchObject({ name: 'AbortError' });
+    expect(h.chat).not.toHaveBeenCalled();
+  });
+
+  it('settles cancellation even when the identity provider never resolves', async () => {
+    const h = setup();
+    h.getIdentityProof.mockReturnValue(new Promise<string>(() => {}));
+    const abort = new AbortController();
+    const settled = vi.fn();
+    const running = h.run(abort.signal).then(settled, settled);
+    await vi.waitFor(() => expect(h.getIdentityProof).toHaveBeenCalled());
+    abort.abort();
+    await vi.waitFor(() => expect(settled).toHaveBeenCalledWith(expect.objectContaining({ name: 'AbortError' })));
+    await running;
+    expect(h.chat).not.toHaveBeenCalled();
+
+    h.getIdentityProof.mockReturnValue('replacement-proof');
+    await h.run();
+    expect(h.chatBodies()).toHaveLength(1);
+    expect(h.chatBodies()[0].identityProof).toEqual({ provider: 'clerk', token: 'replacement-proof' });
+  });
+
+  it('handles a provider rejection after cancellation without exposing it', async () => {
+    const h = setup();
+    let rejectProof!: (error: Error) => void;
+    h.getIdentityProof.mockReturnValue(new Promise<string>((_, reject) => { rejectProof = reject; }));
+    const abort = new AbortController();
+    const settled = vi.fn();
+    const running = h.run(abort.signal).then(settled, settled);
+    await vi.waitFor(() => expect(h.getIdentityProof).toHaveBeenCalled());
+    abort.abort();
+    await vi.waitFor(() => expect(settled).toHaveBeenCalledWith(expect.objectContaining({ name: 'AbortError' })));
+    rejectProof(new Error('secret-from-late-provider-failure'));
+    await running;
+    expect(h.chat).not.toHaveBeenCalled();
+    expect(h.events.filter((e) => e.type === 'error').map((e) => e.error.message).join()).not.toContain('secret-from');
+  });
+
+  it('does not log the proof in debug mode', async () => {
+    const debug = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const h = setup({ debug: true });
+    await h.run();
+    expect(h.chatBodies()[0].identityProof).toBeDefined();
+    expect(JSON.stringify(debug.mock.calls)).not.toContain('fresh-proof');
+  });
+
+  it('reports a rejected proof without calling it a session expiry or retrying', async () => {
+    const h = setup();
+    h.chat.mockImplementation(() => Response.json({ error: 'invalid_identity_proof', errorDescription: 'invalid_signature' }, { status: 401 }));
+    await expect(h.run()).rejects.toThrow('identity proof was rejected');
+    expect(h.chat).toHaveBeenCalledTimes(1);
+    expect(h.onSessionExpired).not.toHaveBeenCalled();
+  });
+});

package/src/client-session-warm.test.ts

@@ -0,0 +1,216 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AgentWidgetClient } from "./client";
+import type { ClientSession } from "./types";
+
+const initBody = (sessionId: string, ttl = 600_000) => ({
+  sessionId,
+  expiresAt: new Date(Date.now() + ttl).toISOString(),
+  flow: { id: "agent-1", name: "Agent", description: null },
+  config: { welcomeMessage: null, placeholder: "Ask...", theme: null },
+});
+
+type Reply = () => Response | Promise<Response>;
+
+function setup(replies: Reply[] = []) {
+  const initRequests: Array<{ body: Record<string, unknown>; headers: Headers }> = [];
+  const chatRequests: string[] = [];
+  let n = 0;
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string, init: RequestInit) => {
+      if (url.endsWith("/v1/client/init")) {
+        initRequests.push({
+          body: JSON.parse(String(init.body)),
+          headers: new Headers(init.headers),
+        });
+        const reply = replies[n++];
+        return reply ? reply() : Response.json(initBody(`session-${n}`));
+      }
+      chatRequests.push(url);
+      return new Response('data: {"type":"done"}\n\n', {
+        headers: { "Content-Type": "text/event-stream" },
+      });
+    })
+  );
+  const onSessionExpired = vi.fn();
+  const onSessionInit = vi.fn();
+  const client = new AgentWidgetClient({
+    clientToken: "ct_test_warm",
+    apiUrl: "https://example.com",
+    onSessionExpired,
+    onSessionInit,
+  });
+  return { client, initRequests, chatRequests, onSessionExpired, onSessionInit };
+}
+
+const send = (client: AgentWidgetClient) =>
+  client.dispatch(
+    {
+      messages: [
+        { id: "u1", role: "user", content: "hi", createdAt: new Date().toISOString() },
+      ],
+      assistantMessageId: "a1",
+    },
+    () => {}
+  );
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("AgentWidgetClient.warmSession", () => {
+  it("an early init followed immediately by a send issues exactly one init", async () => {
+    const { client, initRequests, chatRequests } = setup();
+    void client.warmSession();
+    await send(client);
+    expect(initRequests).toHaveLength(1);
+    expect(chatRequests).toHaveLength(1);
+  });
+
+  it("a send while the early init is still in flight reuses it", async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => (release = resolve));
+    const { client, initRequests, chatRequests } = setup([
+      async () => {
+        await gate;
+        return Response.json(initBody("session-slow"));
+      },
+    ]);
+    const warmed = client.warmSession();
+    const sent = send(client);
+    await vi.waitFor(() => expect(initRequests).toHaveLength(1));
+    expect(chatRequests).toHaveLength(0);
+    release();
+    await sent;
+    await expect(warmed).resolves.toMatchObject({ sessionId: "session-slow" });
+    expect(initRequests).toHaveLength(1);
+    expect(chatRequests).toHaveLength(1);
+  });
+
+  it("sends the same init request the send would", async () => {
+    const early = setup();
+    await early.client.warmSession();
+    vi.unstubAllGlobals();
+    const lazy = setup();
+    await send(lazy.client);
+    expect(early.initRequests[0].body).toEqual(lazy.initRequests[0].body);
+    const headerMap = (headers: Headers) => {
+      const out: Record<string, string> = {};
+      headers.forEach((value, key) => (out[key] = value));
+      return out;
+    };
+    expect(headerMap(early.initRequests[0].headers)).toEqual(
+      headerMap(lazy.initRequests[0].headers)
+    );
+  });
+
+  it("swallows failures silently and lets the send retry init", async () => {
+    const { client, initRequests, chatRequests, onSessionExpired } = setup([
+      () => Response.json({ error: "boom" }, { status: 500 }),
+    ]);
+    await expect(client.warmSession()).resolves.toBeNull();
+    expect(onSessionExpired).not.toHaveBeenCalled();
+    // Latched: further intent signals do not hammer init after a failure.
+    await client.warmSession();
+    expect(initRequests).toHaveLength(1);
+    await send(client);
+    expect(initRequests).toHaveLength(2);
+    expect(chatRequests).toHaveLength(1);
+  });
+
+  it("is a no-op while a session is live", async () => {
+    const { client, initRequests } = setup();
+    await client.warmSession();
+    await client.warmSession();
+    expect(initRequests).toHaveLength(1);
+  });
+
+  it("re-arms when the session is cleared (start-new, credential change)", async () => {
+    const { client, initRequests } = setup([
+      () => Response.json({ error: "boom" }, { status: 500 }),
+    ]);
+    await client.warmSession();
+    await client.warmSession();
+    expect(initRequests).toHaveLength(1);
+    client.clearClientSession();
+    await expect(client.warmSession()).resolves.toMatchObject({ sessionId: "session-2" });
+    expect(initRequests).toHaveLength(2);
+  });
+
+  it("re-arms after start-new-conversation installs a fresh session", async () => {
+    const { client, initRequests } = setup([
+      () => Response.json({ error: "boom" }, { status: 500 }),
+      // Start-new's own session; expired so the next early init is observable.
+      () => Response.json(initBody("session-new-conversation", -1_000)),
+    ]);
+    await client.warmSession();
+    await client.warmSession();
+    expect(initRequests).toHaveLength(1);
+    const prepared = await client.prepareNewConversationSession();
+    prepared.commit();
+    expect(initRequests).toHaveLength(2);
+    await expect(client.warmSession()).resolves.toMatchObject({ sessionId: "session-3" });
+    expect(initRequests).toHaveLength(3);
+  });
+
+  it("re-arms once the session expires", async () => {
+    const { client, initRequests } = setup([
+      () => Response.json(initBody("session-short", -1_000)),
+    ]);
+    await client.warmSession();
+    expect(initRequests).toHaveLength(1);
+    await expect(client.warmSession()).resolves.toMatchObject({ sessionId: "session-2" });
+    expect(initRequests).toHaveLength(2);
+  });
+
+  it("never installs an init that a clear superseded while in flight", async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => (release = resolve));
+    const { client, initRequests, onSessionInit } = setup([
+      async () => {
+        await gate;
+        return Response.json(initBody("session-stale"));
+      },
+    ]);
+    const warmed = client.warmSession();
+    const sent = client.initSession();
+    await vi.waitFor(() => expect(initRequests).toHaveLength(1));
+    // e.g. a sibling tab replaced the visitor credential
+    client.handleExternalCredentialChange();
+    release();
+    await expect(sent).resolves.toMatchObject({ sessionId: "session-2" });
+    await expect(warmed).resolves.toMatchObject({ sessionId: "session-2" });
+    expect(client.getClientSession()?.sessionId).toBe("session-2");
+    expect(initRequests).toHaveLength(2);
+    expect(onSessionInit.mock.calls.map(([s]) => s.sessionId)).toEqual(["session-2"]);
+  });
+
+  it("does nothing outside client token mode", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const client = new AgentWidgetClient({ apiUrl: "https://example.com/api/chat" });
+    await expect(client.warmSession()).resolves.toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("feedback before any init initializes the session on demand", async () => {
+    const { client, initRequests } = setup();
+    const feedbackUrls: string[] = [];
+    const inner = globalThis.fetch as unknown as (u: string, i: RequestInit) => Promise<Response>;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string, init: RequestInit) => {
+        if (url.includes("/feedback")) {
+          feedbackUrls.push(url);
+          return Response.json({ ok: true });
+        }
+        return inner(url, init);
+      })
+    );
+    await client.submitMessageFeedback("m1", "upvote");
+    expect(initRequests).toHaveLength(1);
+    expect(feedbackUrls).toHaveLength(1);
+    expect((client.getClientSession() as ClientSession).sessionId).toBe("session-1");
+  });
+});

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

@@ -755,6 +755,7 @@ describe('controller wiring', () => {
     const controller = createAgentExperience(mount, {
       apiUrl: API_URL,
       clientToken: CLIENT_TOKEN,
+      sessionInit: 'mount',
       launcher: { enabled: false },
     });
     await vi.waitFor(() => expect(requests).toHaveLength(1));
@@ -800,6 +801,7 @@ describe('controller wiring', () => {
     const controller = createAgentExperience(mount, {
       apiUrl: API_URL,
       clientToken: CLIENT_TOKEN,
+      sessionInit: 'mount',
       launcher: { enabled: false },
     });
     await vi.waitFor(() => expect(requests).toHaveLength(1));
@@ -849,6 +851,7 @@ describe('controller wiring', () => {
     const controller = createAgentExperience(mount, {
       apiUrl: API_URL,
       clientToken: CLIENT_TOKEN,
+      sessionInit: 'mount',
       launcher: { enabled: false },
     });
     await vi.waitFor(() => expect(requests).toHaveLength(1));
@@ -907,6 +910,7 @@ describe('controller wiring', () => {
     const controller = createAgentExperience(mount, {
       apiUrl: API_URL,
       clientToken: CLIENT_TOKEN,
+      sessionInit: 'mount',
       launcher: { enabled: false },
       storageAdapter: {
         save: async (state) => {
@@ -1037,6 +1041,7 @@ describe('controller wiring', () => {
     const controller = createAgentExperience(mount, {
       apiUrl: API_URL,
       clientToken: CLIENT_TOKEN,
+      sessionInit: 'mount',
       launcher: { enabled: false },
       reconnectStream,
       storageAdapter: {
@@ -1089,6 +1094,7 @@ describe('voice integration visitor credential access', () => {
     const controller = createAgentExperience(mount, {
       apiUrl: API_URL,
       clientToken: CLIENT_TOKEN,
+      sessionInit: 'mount',
       launcher: { enabled: false },
       ...config,
     });