@runtypelabs/persona 3.22.0 → 3.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.22.0",
+  "version": "3.24.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",
@@ -58,6 +58,7 @@
     "zod": "^3.22.4"
   },
   "devDependencies": {
+    "@size-limit/file": "^12.1.0",
     "@types/node": "^20.12.7",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
@@ -66,6 +67,7 @@
     "eslint-config-prettier": "^9.1.0",
     "fake-indexeddb": "^6.2.5",
     "rimraf": "^5.0.5",
+    "size-limit": "^12.1.0",
     "tsup": "^8.0.1",
     "typescript": "^5.4.5",
     "vitest": "^4.0.9"
@@ -98,10 +100,10 @@
   },
   "scripts": {
     "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:theme-ref && pnpm run build:theme-editor && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:animations",
-    "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:testing": "tsup src/testing.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --dts --out-dir dist --no-splitting",
-    "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --dts --out-dir dist/animations --no-splitting",
+    "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:testing": "tsup src/testing.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
+    "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --minify --dts --out-dir dist/animations --no-splitting",
     "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
     "build:styles": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('src/styles/widget.css','dist/widget.css');\"",
     "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" && tsup src/index-global.ts --format iife --global-name AgentWidget --minify --sourcemap --splitting false --out-dir dist --loader \".css=text\" && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
@@ -110,6 +112,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:ui": "vitest --ui",
-    "test:run": "vitest run"
+    "test:run": "vitest run",
+    "size": "size-limit"
   }
 }

package/src/client.test.ts

@@ -3771,3 +3771,264 @@ describe('AgentWidgetClient - requestMiddleware preserves clientTools', () => {
   });
 });
 
+
+// ============================================================================
+// Diff-only / send-once WebMCP clientTools (client-token mode)
+// ============================================================================
+
+describe('AgentWidgetClient - diff-only clientTools (client-token)', () => {
+  const TOOLS = [
+    { name: 'add_to_cart', description: 'Add to cart', origin: 'webmcp' as const },
+  ];
+
+  function sse(): Response {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+      start(c) {
+        c.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+        c.close();
+      },
+    });
+    return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });
+  }
+
+  // A client-token client with a live session (so initSession short-circuits)
+  // and a stubbed bridge returning `tools`.
+  function makeClient(tools: unknown[]) {
+    const client = new AgentWidgetClient({
+      clientToken: 'ct_live_demo',
+      apiUrl: 'https://api.runtype-staging.com',
+    });
+    (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
+      sessionId: 'cs_diff_1',
+      expiresAt: new Date(Date.now() + 600_000),
+    };
+    (client as unknown as { webMcpBridge: { snapshotForDispatch: () => unknown[] } | null }).webMcpBridge = {
+      snapshotForDispatch: () => tools,
+    };
+    return client;
+  }
+
+  const userMsg = (content = 'hi') => ({
+    messages: [{ id: 'u1', role: 'user' as const, content, createdAt: new Date().toISOString() }],
+    assistantMessageId: 'a1',
+  });
+
+  let chatBodies: Array<Record<string, unknown>>;
+  beforeEach(() => {
+    chatBodies = [];
+  });
+
+  function captureSseFetch() {
+    return vi.fn().mockImplementation(async (url: string, init: { body: string }) => {
+      if (url.includes('/client/chat')) chatBodies.push(JSON.parse(init.body));
+      return sse();
+    });
+  }
+
+  it('first turn sends the full tool list AND a fingerprint', async () => {
+    global.fetch = captureSseFetch();
+    const client = makeClient(TOOLS);
+
+    await client.dispatch(userMsg(), () => undefined);
+
+    expect(chatBodies).toHaveLength(1);
+    expect(chatBodies[0]!.clientTools).toEqual(TOOLS);
+    expect(typeof chatBodies[0]!.clientToolsFingerprint).toBe('string');
+  });
+
+  it('an unchanged second turn sends fingerprint-only (no clientTools array)', async () => {
+    global.fetch = captureSseFetch();
+    const client = makeClient(TOOLS);
+
+    await client.dispatch(userMsg('one'), () => undefined);
+    await client.dispatch(userMsg('two'), () => undefined);
+
+    expect(chatBodies).toHaveLength(2);
+    expect(chatBodies[1]!.clientTools).toBeUndefined();
+    expect(chatBodies[1]!.clientToolsFingerprint).toBe(chatBodies[0]!.clientToolsFingerprint);
+  });
+
+  it('a changed tool set resends the full list with a new fingerprint', async () => {
+    global.fetch = captureSseFetch();
+    // Mutable stub so the second turn snapshots a different set.
+    const live = [...TOOLS];
+    const client = new AgentWidgetClient({
+      clientToken: 'ct_live_demo',
+      apiUrl: 'https://api.runtype-staging.com',
+    });
+    (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
+      sessionId: 'cs_diff_1',
+      expiresAt: new Date(Date.now() + 600_000),
+    };
+    (client as unknown as { webMcpBridge: { snapshotForDispatch: () => unknown[] } | null }).webMcpBridge = {
+      snapshotForDispatch: () => live,
+    };
+
+    await client.dispatch(userMsg('one'), () => undefined);
+    live.push({ name: 'checkout', description: 'Checkout', origin: 'webmcp' });
+    await client.dispatch(userMsg('two'), () => undefined);
+
+    expect(chatBodies).toHaveLength(2);
+    expect(chatBodies[1]!.clientTools).toEqual(live);
+    expect(chatBodies[1]!.clientToolsFingerprint).not.toBe(chatBodies[0]!.clientToolsFingerprint);
+  });
+
+  it('order-independent: reordering the same tools stays fingerprint-only', async () => {
+    global.fetch = captureSseFetch();
+    const live = [
+      { name: 'a', description: 'A', origin: 'webmcp' as const },
+      { name: 'b', description: 'B', origin: 'webmcp' as const },
+    ];
+    const client = new AgentWidgetClient({
+      clientToken: 'ct_live_demo',
+      apiUrl: 'https://api.runtype-staging.com',
+    });
+    (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
+      sessionId: 'cs_diff_1',
+      expiresAt: new Date(Date.now() + 600_000),
+    };
+    let current = live;
+    (client as unknown as { webMcpBridge: { snapshotForDispatch: () => unknown[] } | null }).webMcpBridge = {
+      snapshotForDispatch: () => current,
+    };
+
+    await client.dispatch(userMsg('one'), () => undefined);
+    current = [live[1]!, live[0]!]; // same set, reordered
+    await client.dispatch(userMsg('two'), () => undefined);
+
+    expect(chatBodies[1]!.clientTools).toBeUndefined();
+  });
+
+  it('a 409 client_tools_resend_required triggers exactly one retry with the full list', async () => {
+    let call = 0;
+    global.fetch = vi.fn().mockImplementation(async (url: string, init: { body: string }) => {
+      if (!url.includes('/client/chat')) return sse();
+      call += 1;
+      chatBodies.push(JSON.parse(init.body));
+      if (call === 1) {
+        return new Response(JSON.stringify({ error: 'client_tools_resend_required' }), {
+          status: 409,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      return sse();
+    });
+    const client = makeClient(TOOLS);
+    // Pre-seed the cache so the first attempt would be fingerprint-only — the
+    // server then forces a resend.
+    (client as unknown as { lastSentClientToolsFingerprint: string | null; clientToolsFingerprintSessionId: string | null }).lastSentClientToolsFingerprint =
+      'stale';
+    (client as unknown as { clientToolsFingerprintSessionId: string | null }).clientToolsFingerprintSessionId =
+      'cs_diff_1';
+
+    await client.dispatch(userMsg(), () => undefined);
+
+    expect(chatBodies).toHaveLength(2);
+    // Retry carried the full list...
+    expect(chatBodies[1]!.clientTools).toEqual(TOOLS);
+    // ...with the SAME messages + assistantMessageId (no double user message).
+    expect(chatBodies[1]!.messages).toEqual(chatBodies[0]!.messages);
+    expect(chatBodies[1]!.assistantMessageId).toBe(chatBodies[0]!.assistantMessageId);
+  });
+
+  it('clearMessages-style reset (resetClientToolsFingerprint) forces a full resend next turn', async () => {
+    global.fetch = captureSseFetch();
+    const client = makeClient(TOOLS);
+
+    await client.dispatch(userMsg('one'), () => undefined);
+    client.resetClientToolsFingerprint();
+    await client.dispatch(userMsg('two'), () => undefined);
+
+    expect(chatBodies[1]!.clientTools).toEqual(TOOLS); // not fingerprint-only
+  });
+
+  it('does not commit the cache on a network failure (next turn resends full)', async () => {
+    let call = 0;
+    global.fetch = vi.fn().mockImplementation(async (url: string, init: { body: string }) => {
+      if (!url.includes('/client/chat')) return sse();
+      call += 1;
+      chatBodies.push(JSON.parse(init.body));
+      if (call === 1) throw new Error('network down');
+      return sse();
+    });
+    const client = makeClient(TOOLS);
+
+    await client.dispatch(userMsg('one'), () => undefined).catch(() => undefined);
+    await client.dispatch(userMsg('two'), () => undefined);
+
+    // Second turn still sends the full list because the first never committed.
+    expect(chatBodies[1]!.clientTools).toEqual(TOOLS);
+  });
+
+  it('minting a fresh session via initSession() resets the fingerprint cache', async () => {
+    global.fetch = vi.fn().mockImplementation(async (url: string) => {
+      if (url.includes('/client/init')) {
+        return new Response(
+          JSON.stringify({
+            sessionId: 'cs_freshly_minted',
+            expiresAt: new Date(Date.now() + 600_000).toISOString(),
+            flow: { id: 'flow_x', name: 'F', description: null },
+            config: { welcomeMessage: null, placeholder: 'p', theme: null },
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      }
+      return sse();
+    });
+    const client = new AgentWidgetClient({
+      clientToken: 'ct_live_demo',
+      apiUrl: 'https://api.runtype-staging.com',
+    });
+    // Pre-seed a stale fingerprint bound to a prior session (no live session, so
+    // initSession() takes the mint path and fetches /client/init).
+    const internals = client as unknown as {
+      lastSentClientToolsFingerprint: string | null;
+      clientToolsFingerprintSessionId: string | null;
+    };
+    internals.lastSentClientToolsFingerprint = 'stale-fp';
+    internals.clientToolsFingerprintSessionId = 'cs_old';
+
+    await client.initSession();
+
+    expect(internals.lastSentClientToolsFingerprint).toBeNull();
+    expect(internals.clientToolsFingerprintSessionId).toBeNull();
+  });
+});
+
+describe('AgentWidgetClient - non-client-token paths always send full clientTools', () => {
+  function sse(): Response {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+      start(c) {
+        c.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+        c.close();
+      },
+    });
+    return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });
+  }
+
+  it('proxy mode sends full clientTools and no fingerprint on every turn', async () => {
+    const bodies: Array<Record<string, unknown>> = [];
+    global.fetch = vi.fn().mockImplementation(async (_url: string, init: { body: string }) => {
+      bodies.push(JSON.parse(init.body));
+      return sse();
+    });
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    (client as unknown as { webMcpBridge: { snapshotForDispatch: () => unknown[] } | null }).webMcpBridge = {
+      snapshotForDispatch: () => [{ name: 'search', description: 's', origin: 'webmcp' }],
+    };
+
+    const msg = () => ({
+      messages: [{ id: 'u1', role: 'user' as const, content: 'hi', createdAt: new Date().toISOString() }],
+    });
+    await client.dispatch(msg(), () => undefined);
+    await client.dispatch(msg(), () => undefined);
+
+    expect(bodies).toHaveLength(2);
+    for (const b of bodies) {
+      expect(b.clientTools).toEqual([{ name: 'search', description: 's', origin: 'webmcp' }]);
+      expect(b.clientToolsFingerprint).toBeUndefined();
+    }
+  });
+});

package/src/client.ts

@@ -23,7 +23,7 @@ import {
   ContentPart,
   WebMcpConfirmHandler
 } from "./types";
-import { WebMcpBridge } from "./webmcp-bridge";
+import { WebMcpBridge, computeClientToolsFingerprint } from "./webmcp-bridge";
 import {
   extractTextFromJson,
   createPlainTextParser,
@@ -171,6 +171,14 @@ export class AgentWidgetClient {
   private clientSession: ClientSession | null = null;
   private sessionInitPromise: Promise<ClientSession> | null = null;
 
+  // Diff-only / send-once WebMCP tool dispatch (client-token mode ONLY).
+  // Fingerprint of the clientTools[] last *sent in full* and confirmed by a
+  // successful stream start; null => the next client-token turn sends the full
+  // array. Paired with the sessionId it was sent under so a session change
+  // (silent re-init / expiry) forces a fresh full send.
+  private lastSentClientToolsFingerprint: string | null = null;
+  private clientToolsFingerprintSessionId: string | null = null;
+
   // WebMCP — page-discovered tool consumption (see ./webmcp-bridge).
   // Constructed lazily: null when `config.webmcp?.enabled !== true`.
   private readonly webMcpBridge: WebMcpBridge | null;
@@ -297,6 +305,12 @@ export class AgentWidgetClient {
     try {
       const session = await this.sessionInitPromise;
       this.clientSession = session;
+      // A freshly-minted session must resend the full WebMCP tool list on its
+      // next turn: drop any diff-only fingerprint cached under a prior session,
+      // so we never claim "unchanged" against a session the server didn't store
+      // the set under. (Belt-and-suspenders with the sessionId comparison in the
+      // send decision and the server's 409 resend signal.)
+      this.resetClientToolsFingerprint();
       this.config.onSessionInit?.(session);
       return session;
     } finally {
@@ -358,6 +372,17 @@ export class AgentWidgetClient {
   public clearClientSession(): void {
     this.clientSession = null;
     this.sessionInitPromise = null;
+    this.resetClientToolsFingerprint();
+  }
+
+  /**
+   * Forget the diff-only WebMCP tool fingerprint so the next client-token turn
+   * resends the full `clientTools[]`. Called when the session is cleared and
+   * when the conversation is reset (`WidgetSession.clearMessages`).
+   */
+  public resetClientToolsFingerprint(): void {
+    this.lastSentClientToolsFingerprint = null;
+    this.clientToolsFingerprintSessionId = null;
   }
 
   /**
@@ -551,7 +576,7 @@ export class AgentWidgetClient {
       // 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.clientSession = null;
+        this.clearClientSession();
         this.config.onSessionExpired?.();
         const error = new Error('Session expired. Please refresh to continue.');
         onEvent({ type: "error", error });
@@ -569,7 +594,8 @@ export class AgentWidgetClient {
           )
         : undefined;
       
-      const chatRequest: ClientChatRequest = {
+      // Common (tools-independent) fields for the chat request.
+      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 => ({
@@ -584,44 +610,90 @@ export class AgentWidgetClient {
         ...(sanitizedMetadata && Object.keys(sanitizedMetadata).length > 0 && { metadata: sanitizedMetadata }),
         ...(basePayload.inputs && Object.keys(basePayload.inputs).length > 0 && { inputs: basePayload.inputs }),
         ...(basePayload.context && { context: basePayload.context }),
-        // Forward per-turn WebMCP tools snapshotted by buildPayload(). The
-        // client-token chat endpoint accepts the same shape as /v1/dispatch.
-        ...(basePayload.clientTools && basePayload.clientTools.length > 0 && { clientTools: basePayload.clientTools }),
       };
 
-      if (this.debug) {
-        // eslint-disable-next-line no-console
-        console.debug("[AgentWidgetClient] client token dispatch", chatRequest);
-      }
+      // Diff-only / send-once WebMCP tool dispatch. `buildPayload()` already
+      // snapshotted the full set; decide whether to ship it again or just its
+      // fingerprint. First turn of a session, or a changed set, sends the full
+      // array; an unchanged set sends only the fingerprint and the server
+      // reuses its stored copy. The cache is committed only after a successful
+      // stream start (below), so a 409/failure leaves it untouched.
+      const fullClientTools = basePayload.clientTools;
+      const hasClientTools = !!(fullClientTools && fullClientTools.length > 0);
+      const clientToolsFingerprint = hasClientTools
+        ? computeClientToolsFingerprint(fullClientTools!)
+        : undefined;
+      const sameSession = this.clientToolsFingerprintSessionId === session.sessionId;
+      const unchanged =
+        hasClientTools && sameSession && this.lastSentClientToolsFingerprint === clientToolsFingerprint;
+
+      // `forceFull` flips to true after a 409 cache-miss so the single retry
+      // resends the full list. Capture any error body read inside the loop so
+      // the `!response.ok` handler below doesn't re-consume the stream.
+      let forceFull = false;
+      let errorData: { error?: string; hint?: string } | null = null;
+      let response: Response;
+      for (let attempt = 0; ; attempt++) {
+        const sendFull = hasClientTools && (forceFull || !unchanged);
+        const chatRequest: ClientChatRequest = {
+          ...baseChatRequest,
+          ...(sendFull && fullClientTools ? { clientTools: fullClientTools } : {}),
+          ...(clientToolsFingerprint ? { clientToolsFingerprint } : {}),
+        };
 
-      const response = await fetch(this.getClientApiUrl('chat'), {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(chatRequest),
-        signal: controller.signal,
-      });
+        if (this.debug) {
+          // eslint-disable-next-line no-console
+          console.debug("[AgentWidgetClient] client token dispatch", chatRequest);
+        }
+
+        response = await fetch(this.getClientApiUrl('chat'), {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(chatRequest),
+          signal: controller.signal,
+        });
+
+        // Diff-only cache miss: the server has no stored tool set matching our
+        // fingerprint. Retry exactly once with the full list. A second miss
+        // falls through to the normal error handling below (no infinite loop).
+        if (response.status === 409 && attempt === 0 && hasClientTools) {
+          const body = (await response.json().catch(() => null)) as
+            | { error?: string; hint?: string }
+            | null;
+          if (body?.error === 'client_tools_resend_required') {
+            forceFull = true;
+            // Invalidate so future turns also resend until a clean success
+            // commits a fresh fingerprint.
+            this.lastSentClientToolsFingerprint = null;
+            continue;
+          }
+          // Some other 409 — keep the parsed body for the handler below.
+          errorData = body ?? { error: 'Chat request failed' };
+        }
+        break;
+      }
 
       if (!response.ok) {
-        const errorData = await response.json().catch(() => ({ error: 'Chat request failed' }));
-        
+        const data = errorData ?? (await response.json().catch(() => ({ error: 'Chat request failed' })));
+
         if (response.status === 401) {
           // Session expired
-          this.clientSession = null;
+          this.clearClientSession();
           this.config.onSessionExpired?.();
           const error = new Error('Session expired. Please refresh to continue.');
           onEvent({ type: "error", error });
           throw error;
         }
-        
+
         if (response.status === 429) {
-          const error = new Error(errorData.hint || 'Message limit reached for this session.');
+          const error = new Error(data.hint || 'Message limit reached for this session.');
           onEvent({ type: "error", error });
           throw error;
         }
-        
-        const error = new Error(errorData.error || 'Failed to send message');
+
+        const error = new Error(data.error || 'Failed to send message');
         onEvent({ type: "error", error });
         throw error;
       }
@@ -632,6 +704,12 @@ export class AgentWidgetClient {
         throw error;
       }
 
+      // Stream is good: the server now holds this tool set under this
+      // fingerprint for the session. Commit the cache so unchanged follow-up
+      // turns can send fingerprint-only.
+      this.lastSentClientToolsFingerprint = clientToolsFingerprint ?? null;
+      this.clientToolsFingerprintSessionId = session.sessionId;
+
       onEvent({ type: "status", status: "connected" });
       
       // Stream the response (same SSE handling as proxy mode)