@runtypelabs/persona 3.23.0 → 3.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.23.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",

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)

package/src/session.ts

@@ -2059,6 +2059,10 @@ export class AgentWidgetSession {
     // a tool with the same key resolved in the prior conversation.
     this.webMcpInflightKeys.clear();
     this.webMcpResolvedKeys.clear();
+    // A fresh conversation must resend the full WebMCP tool list on its next
+    // turn — drop the diff-only fingerprint cache (server keys by recordId, so
+    // a new conversation has no stored set to match).
+    this.client.resetClientToolsFingerprint();
     this.setStreaming(false);
     this.setStatus("idle");
     this.callbacks.onMessagesChanged([...this.messages]);

package/src/types.ts

@@ -2224,6 +2224,23 @@ export type ClientChatRequest = {
   context?: Record<string, unknown>;
   /** WebMCP page-discovered tools — same shape as `dispatch.clientTools[]`. */
   clientTools?: ClientToolDefinition[];
+  /**
+   * Diff-only / send-once: order-independent fingerprint of the client tool set.
+   * When the set is unchanged from the previous turn the widget sends this
+   * WITHOUT `clientTools` and the server reuses its stored set. On a cache miss
+   * the server replies `409 { error: 'client_tools_resend_required' }` and the
+   * widget retries once with the full `clientTools[]`.
+   */
+  clientToolsFingerprint?: string;
+};
+
+/**
+ * Body the server returns (HTTP 409) when it holds no stored tool set matching
+ * a fingerprint-only `/client/chat` turn. The widget retries once with the full
+ * `clientTools[]` (and the fingerprint).
+ */
+export type ClientToolsResendRequiredResponse = {
+  error: 'client_tools_resend_required';
 };
 
 /**

package/src/webmcp-bridge.test.ts

@@ -29,7 +29,9 @@ import {
   WebMcpBridge,
   isWebMcpToolName,
   stripWebMcpPrefix,
+  computeClientToolsFingerprint,
 } from "./webmcp-bridge";
+import type { ClientToolDefinition } from "./types";
 
 type MockClient = { requestUserInteraction: (cb: () => unknown) => Promise<unknown> };
 
@@ -427,3 +429,81 @@ describe("WebMcpBridge.executeToolCall", () => {
     expect(executeSpy).not.toHaveBeenCalled();
   });
 });
+
+describe("computeClientToolsFingerprint — diff-only / send-once", () => {
+  const tool = (over: Partial<ClientToolDefinition> = {}): ClientToolDefinition => ({
+    name: "search",
+    description: "Search the catalog",
+    parametersSchema: { type: "object", properties: { q: { type: "string" } } },
+    origin: "webmcp",
+    ...over,
+  });
+
+  it("returns a stable sentinel for an empty set", () => {
+    expect(computeClientToolsFingerprint([])).toBe(computeClientToolsFingerprint([]));
+    expect(computeClientToolsFingerprint([])).toBe("0:empty");
+  });
+
+  it("is deterministic for the same set", () => {
+    const a = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    const b = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    expect(a).toBe(b);
+  });
+
+  it("is order-independent (tool order does not matter)", () => {
+    const ab = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    const ba = computeClientToolsFingerprint([tool({ name: "b" }), tool({ name: "a" })]);
+    expect(ab).toBe(ba);
+  });
+
+  it("changes when a description changes", () => {
+    expect(computeClientToolsFingerprint([tool({ description: "x" })])).not.toBe(
+      computeClientToolsFingerprint([tool({ description: "y" })]),
+    );
+  });
+
+  it("changes when the schema changes", () => {
+    const base = computeClientToolsFingerprint([tool()]);
+    const changed = computeClientToolsFingerprint([
+      tool({ parametersSchema: { type: "object", properties: { q: { type: "number" } } } }),
+    ]);
+    expect(changed).not.toBe(base);
+  });
+
+  it("changes when a tool is added", () => {
+    const one = computeClientToolsFingerprint([tool({ name: "a" })]);
+    const two = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    expect(two).not.toBe(one);
+  });
+
+  it("ignores pageOrigin (audit metadata, not part of the contract)", () => {
+    const withOrigin = computeClientToolsFingerprint([tool({ pageOrigin: "https://a.example" })]);
+    const without = computeClientToolsFingerprint([tool({ pageOrigin: undefined })]);
+    expect(withOrigin).toBe(without);
+  });
+
+  it("reflects annotations (they ride along to the server)", () => {
+    const plain = computeClientToolsFingerprint([tool()]);
+    const annotated = computeClientToolsFingerprint([
+      tool({ annotations: { readOnlyHint: true } }),
+    ]);
+    expect(annotated).not.toBe(plain);
+  });
+
+  it("stays within the server's 128-char wire bound for large tool sets", () => {
+    // The server validates `clientToolsFingerprint` as `z.string().max(128)`.
+    // A fingerprint that grew with the tool content would 400 the first turn.
+    const many = Array.from({ length: 50 }, (_, i) =>
+      tool({
+        name: `tool_${i}`,
+        description: `A fairly long description for tool number ${i} `.repeat(8),
+        parametersSchema: {
+          type: "object",
+          properties: { a: { type: "string" }, b: { type: "number" }, c: { type: "boolean" } },
+        },
+      }),
+    );
+    const fp = computeClientToolsFingerprint(many);
+    expect(fp.length).toBeLessThanOrEqual(128);
+  });
+});

package/src/webmcp-bridge.ts

@@ -86,6 +86,74 @@ const log = {
   },
 };
 
+/**
+ * Compute a stable, order-independent fingerprint of a `ClientToolDefinition[]`
+ * snapshot, for the diff-only / send-once dispatch path (client-token mode).
+ *
+ * The widget caches "the fingerprint of the tool set last sent in full" for the
+ * current session; an unchanged set on a follow-up turn lets it ship only the
+ * fingerprint instead of the whole array. Per-tool strings are sorted so tool
+ * ordering does not affect the result. `pageOrigin` is deliberately excluded —
+ * it is audit metadata, not part of the tool contract.
+ *
+ * This is a fast, non-cryptographic content key. The canonical per-tool content
+ * is hashed down to a short, fixed-length digest so the result fits the server's
+ * `clientToolsFingerprint` wire field (`z.string().max(128)`) regardless of how
+ * many tools the page registers — sending the raw concatenated content would
+ * overflow that bound and be rejected with a 400. The server stores and compares
+ * the widget's fingerprint verbatim, so cross-implementation byte-equality is NOT
+ * required — only self-consistency across this widget's turns.
+ */
+export function computeClientToolsFingerprint(
+  tools: ClientToolDefinition[],
+): string {
+  if (tools.length === 0) return "0:empty";
+  const parts = tools
+    .map((t) =>
+      [
+        t.name,
+        t.description ?? "",
+        t.parametersSchema ? JSON.stringify(t.parametersSchema) : "",
+        t.origin ?? "",
+        t.annotations ? JSON.stringify(t.annotations) : "",
+      ].join("\x1f"),
+    )
+    .sort();
+  return `${tools.length}:${hashFingerprintContent(parts.join("\x1e"))}`;
+}
+
+/**
+ * cyrb53 — a fast, well-distributed non-cryptographic string hash. Returns a
+ * 53-bit value (safe-integer range). Two independent seeds are combined by the
+ * caller for a ~106-bit digest, which makes accidental collisions across a
+ * single conversation's handful of tool-set variants infeasible.
+ */
+function cyrb53(str: string, seed: number): number {
+  let h1 = 0xdeadbeef ^ seed;
+  let h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+
+/**
+ * Compress the canonical tool-set content string into a short, fixed-length
+ * fingerprint (≤ ~24 chars) that fits the server's 128-char wire bound. Uses two
+ * seeded cyrb53 passes, base-36 encoded.
+ */
+function hashFingerprintContent(content: string): string {
+  const a = cyrb53(content, 0).toString(36);
+  const b = cyrb53(content, 0x9e3779b1).toString(36);
+  return `${a}.${b}`;
+}
+
 export class WebMcpBridge {
   private confirmHandler: WebMcpConfirmHandler | null;
   private readonly timeoutMs: number;