@runtypelabs/persona 4.23.1 → 4.24.0

package/src/client.tool-pair-replay.test.ts

@@ -0,0 +1,325 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+import { AgentWidgetClient } from "./client";
+import { AgentWidgetSession } from "./session";
+import type { AgentWidgetMessage, ClientToolDefinition } from "./types";
+import { modelFacingToolName } from "./utils/tool-pair-replay";
+
+const SEARCH_TOOL: ClientToolDefinition = {
+  name: "search_catalog",
+  description: "Search the catalog",
+  origin: "webmcp",
+};
+
+const RESULT = { content: [{ type: "text", text: "SKU-42 costs $19" }] };
+
+const user = (id: string, content: string, at: number): AgentWidgetMessage => ({
+  id,
+  role: "user",
+  content,
+  createdAt: new Date(at).toISOString(),
+});
+
+const assistant = (id: string, content: string, at: number): AgentWidgetMessage => ({
+  id,
+  role: "assistant",
+  content,
+  createdAt: new Date(at).toISOString(),
+  variant: "assistant",
+});
+
+const answeredTool = (
+  toolCallId: string,
+  at: number,
+  overrides: Partial<NonNullable<AgentWidgetMessage["agentMetadata"]>> = {},
+): AgentWidgetMessage => ({
+  id: `tool-${toolCallId}`,
+  role: "assistant",
+  content: "",
+  createdAt: new Date(at).toISOString(),
+  variant: "tool",
+  toolCall: {
+    id: toolCallId,
+    name: "webmcp:search_catalog",
+    status: "complete",
+    args: { q: "sku 42" },
+    result: RESULT,
+  },
+  agentMetadata: {
+    executionId: "exec-1",
+    awaitingLocalTool: false,
+    webMcpToolCallId: toolCallId,
+    clientToolAnswer: {
+      toolCallId,
+      toolName: "webmcp:search_catalog",
+      args: { q: "sku 42" },
+      result: RESULT,
+    },
+    ...overrides,
+  },
+});
+
+/** Turn 1 (with its answered tool) followed by turn 2's user message. */
+const twoTurnTranscript = (): AgentWidgetMessage[] => [
+  user("u1", "What does SKU 42 cost?", 1_000),
+  answeredTool("toolu_01", 2_000),
+  assistant("a1", "SKU 42 costs $19.", 3_000),
+  user("u2", "And what was the SKU again?", 4_000),
+];
+
+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" } });
+}
+
+let bodies: Array<Record<string, unknown>>;
+beforeEach(() => {
+  bodies = [];
+  global.fetch = vi.fn().mockImplementation(async (_url: string, init: { body: string }) => {
+    bodies.push(JSON.parse(init.body));
+    return sse();
+  });
+});
+
+const withTools = (client: AgentWidgetClient, tools: ClientToolDefinition[]) => {
+  (client as unknown as { webMcpBridge: { snapshotForDispatch: () => unknown[] } }).webMcpBridge = {
+    snapshotForDispatch: () => tools,
+  };
+  return client;
+};
+
+const EXPECTED_TURN_2 = [
+  { role: "user", content: "What does SKU 42 cost?" },
+  {
+    role: "assistant",
+    content: "",
+    toolCalls: [{ toolCallId: "toolu_01", toolName: "webmcp_search_catalog", args: { q: "sku 42" } }],
+  },
+  {
+    role: "tool",
+    content: "",
+    toolResults: [{ toolCallId: "toolu_01", toolName: "webmcp_search_catalog", result: RESULT }],
+  },
+  { role: "assistant", content: "SKU 42 costs $19." },
+  { role: "user", content: "And what was the SKU again?" },
+];
+
+const stripCreatedAt = (messages: unknown) =>
+  (messages as Array<Record<string, unknown>>).map(({ createdAt: _createdAt, ...rest }) => rest);
+
+describe("tool-pair replay: proxy mode", () => {
+  it("sends turn 1's answered call and result, paired and in order, on turn 2", async () => {
+    const client = withTools(new AgentWidgetClient({ apiUrl: "http://proxy.test/chat" }), [SEARCH_TOOL]);
+    await client.dispatch({ messages: twoTurnTranscript() }, () => undefined);
+    expect(stripCreatedAt(bodies[0]!.messages)).toEqual(EXPECTED_TURN_2);
+  });
+
+  it("keeps the pair after the page stops offering the tool", async () => {
+    const client = withTools(new AgentWidgetClient({ apiUrl: "http://proxy.test/chat" }), []);
+    await client.dispatch({ messages: twoTurnTranscript() }, () => undefined);
+    expect(stripCreatedAt(bodies[0]!.messages)).toEqual(EXPECTED_TURN_2);
+    expect(bodies[0]!.clientTools).toBeUndefined();
+  });
+});
+
+describe("tool-pair replay: agent mode", () => {
+  it("sends turn 1's answered call and result, paired and in order, on turn 2", async () => {
+    const client = withTools(
+      new AgentWidgetClient({
+        apiUrl: "http://proxy.test/agents",
+        agent: { name: "Test", model: "openai:gpt-4o-mini", systemPrompt: "test" },
+      }),
+      [SEARCH_TOOL],
+    );
+    await client.dispatch({ messages: twoTurnTranscript() }, () => undefined);
+    expect(stripCreatedAt(bodies[0]!.messages)).toEqual(EXPECTED_TURN_2);
+  });
+});
+
+describe("tool-pair replay: bubbles that must not replay", () => {
+  it("a tool bubble with no accepted answer emits nothing", async () => {
+    const pending: AgentWidgetMessage = {
+      ...answeredTool("toolu_02", 2_000),
+      toolCall: { id: "toolu_02", name: "webmcp:search_catalog", status: "running", args: {} },
+      agentMetadata: { executionId: "exec-1", awaitingLocalTool: true, webMcpToolCallId: "toolu_02" },
+    };
+    const client = withTools(new AgentWidgetClient({ apiUrl: "http://proxy.test/chat" }), [SEARCH_TOOL]);
+    await client.dispatch(
+      { messages: [user("u1", "hi", 1_000), pending, user("u2", "again", 3_000)] },
+      () => undefined,
+    );
+    const messages = bodies[0]!.messages as Array<Record<string, unknown>>;
+    expect(messages.map((m) => m.role)).toEqual(["user", "user"]);
+    expect(messages.some((m) => "toolCalls" in m || "toolResults" in m)).toBe(false);
+  });
+
+  it("a server-side tool's result stays out (only browser-answered calls replay)", async () => {
+    const serverTool: AgentWidgetMessage = {
+      ...answeredTool("toolu_03", 2_000),
+      agentMetadata: { executionId: "exec-1" },
+    };
+    const client = withTools(new AgentWidgetClient({ apiUrl: "http://proxy.test/chat" }), [SEARCH_TOOL]);
+    await client.dispatch(
+      { messages: [user("u1", "hi", 1_000), serverTool, user("u2", "again", 3_000)] },
+      () => undefined,
+    );
+    expect((bodies[0]!.messages as unknown[]).length).toBe(2);
+  });
+});
+
+describe("tool-pair replay: parallel and chained calls", () => {
+  type Sent = Array<{
+    role: string;
+    toolCalls?: Array<{ toolCallId: string }>;
+    toolResults?: Array<{ toolCallId: string }>;
+  }>;
+  const inBatch = (toolCallId: string, at: number, batch: string) => {
+    const message = answeredTool(toolCallId, at);
+    message.agentMetadata!.clientToolAnswer!.batch = batch;
+    return message;
+  };
+
+  it("groups answers from one /resume batch into one call message and one result message", async () => {
+    const client = withTools(new AgentWidgetClient({ apiUrl: "http://proxy.test/chat" }), [SEARCH_TOOL]);
+    await client.dispatch(
+      {
+        messages: [
+          user("u1", "compare", 1_000),
+          inBatch("toolu_a", 2_000, "b1"),
+          inBatch("toolu_b", 2_001, "b1"),
+          assistant("a1", "done", 3_000),
+        ],
+      },
+      () => undefined,
+    );
+    const messages = bodies[0]!.messages as Sent;
+    expect(messages.map((m) => m.role)).toEqual(["user", "assistant", "tool", "assistant"]);
+    expect(messages[1]!.toolCalls!.map((c) => c.toolCallId)).toEqual(["toolu_a", "toolu_b"]);
+    expect(messages[2]!.toolResults!.map((r) => r.toolCallId)).toEqual(["toolu_a", "toolu_b"]);
+  });
+
+  it("keeps a chained call (a later /resume batch, no text between) as its own pair", async () => {
+    const client = withTools(new AgentWidgetClient({ apiUrl: "http://proxy.test/chat" }), [SEARCH_TOOL]);
+    await client.dispatch(
+      {
+        messages: [
+          user("u1", "look it up, then look up the related item", 1_000),
+          inBatch("toolu_a", 2_000, "b1"),
+          inBatch("toolu_b", 2_500, "b2"),
+          assistant("a1", "done", 3_000),
+        ],
+      },
+      () => undefined,
+    );
+    const messages = bodies[0]!.messages as Sent;
+    expect(messages.map((m) => m.role)).toEqual(["user", "assistant", "tool", "assistant", "tool", "assistant"]);
+    expect(messages[1]!.toolCalls!.map((c) => c.toolCallId)).toEqual(["toolu_a"]);
+    expect(messages[3]!.toolCalls!.map((c) => c.toolCallId)).toEqual(["toolu_b"]);
+  });
+});
+
+describe("tool-pair replay: requestMiddleware", () => {
+  it("keeps replayed pairs when the middleware removes the tools", async () => {
+    const client = withTools(
+      new AgentWidgetClient({
+        apiUrl: "http://proxy.test/chat",
+        requestMiddleware: ({ payload }) => ({ ...payload, clientTools: undefined }),
+      }),
+      [SEARCH_TOOL],
+    );
+    await client.dispatch({ messages: twoTurnTranscript() }, () => undefined);
+    expect(stripCreatedAt(bodies[0]!.messages)).toEqual(EXPECTED_TURN_2);
+  });
+});
+
+describe("tool-pair replay: client-token mode is server-owned", () => {
+  it("sends no toolCalls, toolResults or tool role on /client/chat", async () => {
+    const client = withTools(
+      new AgentWidgetClient({ clientToken: "ct_live_demo", apiUrl: "https://api.runtype.com" }),
+      [SEARCH_TOOL],
+    );
+    (client as unknown as { clientSession: { sessionId: string; expiresAt: Date } }).clientSession = {
+      sessionId: "cs_1",
+      expiresAt: new Date(Date.now() + 600_000),
+    };
+    await client.dispatch({ messages: twoTurnTranscript(), assistantMessageId: "a2" }, () => undefined);
+    const messages = bodies[0]!.messages as Array<Record<string, unknown>>;
+    expect(messages.map((m) => m.role)).toEqual(["user", "assistant", "user"]);
+    expect(messages.some((m) => "toolCalls" in m || "toolResults" in m)).toBe(false);
+  });
+});
+
+describe("modelFacingToolName", () => {
+  it("matches core's AI-SDK sanitizer", () => {
+    expect(modelFacingToolName("webmcp:get_schema")).toBe("webmcp_get_schema");
+    expect(modelFacingToolName("webmcp:Get-Slide")).toBe("webmcp_get_slide");
+    expect(modelFacingToolName("suggest_replies")).toBe("suggest_replies");
+  });
+});
+
+describe("session records the accepted client-tool answer", () => {
+  const makeSession = (resumeStatus = 200) => {
+    const session = new AgentWidgetSession(
+      { apiUrl: "http://test", webmcp: { enabled: true } },
+      {
+        onMessagesChanged: () => undefined,
+        onStatusChanged: () => undefined,
+        onStreamingChanged: () => undefined,
+      },
+    );
+    const client = (session as unknown as { client: Record<string, unknown> }).client;
+    client.executeWebMcpToolCall = vi.fn(async () => RESULT);
+    client.isWebMcpOperational = vi.fn(() => true);
+    client.resumeFlow = vi.fn(async () => new Response(new Blob([""]), { status: resumeStatus }));
+    (session as unknown as { connectStream: () => Promise<void> }).connectStream = vi.fn(async () => undefined);
+    return session;
+  };
+
+  const awaiting = (): AgentWidgetMessage => ({
+    id: "tool-toolu_01",
+    role: "assistant",
+    content: "",
+    createdAt: new Date().toISOString(),
+    variant: "tool",
+    agentMetadata: { executionId: "exec-1", awaitingLocalTool: true, webMcpToolCallId: "toolu_01" },
+    toolCall: { id: "toolu_01", name: "webmcp:search_catalog", status: "running", args: { q: "sku 42" } },
+  });
+
+  const stored = (session: AgentWidgetSession) =>
+    (session as unknown as { messages: AgentWidgetMessage[] }).messages.find((m) => m.id === "tool-toolu_01");
+
+  it("stores the answer after /resume succeeds and keeps it across a tool_complete re-emit", async () => {
+    const session = makeSession();
+    await session.resolveWebMcpToolCall(awaiting());
+    expect(stored(session)?.agentMetadata?.clientToolAnswer).toEqual({
+      toolCallId: "toolu_01",
+      toolName: "webmcp:search_catalog",
+      args: { q: "sku 42" },
+      result: RESULT,
+      batch: expect.any(String),
+    });
+
+    (session as unknown as { upsertMessage: (m: AgentWidgetMessage) => void }).upsertMessage({
+      id: "tool-toolu_01",
+      role: "assistant",
+      content: "",
+      createdAt: new Date().toISOString(),
+      variant: "tool",
+      agentMetadata: { executionId: "exec-1" },
+      toolCall: { id: "toolu_01", name: "webmcp:search_catalog", status: "complete", result: "server copy" },
+    });
+    expect(stored(session)?.agentMetadata?.clientToolAnswer?.result).toEqual(RESULT);
+  });
+
+  it("stores nothing when /resume fails", async () => {
+    const session = makeSession(500);
+    await session.resolveWebMcpToolCall(awaiting());
+    expect(stored(session)?.agentMetadata?.clientToolAnswer).toBeUndefined();
+  });
+});

package/src/client.ts

@@ -49,6 +49,7 @@ import {
 import { resolveTarget } from "./utils/target";
 import { generateTurnId } from "./utils/message-id";
 import { builtInClientToolsForDispatch } from "./ask-user-question-tool";
+import { serializeWithToolPairs } from "./utils/tool-pair-replay";
 import {
   extractTextFromJson,
   createPlainTextParser,
@@ -221,6 +222,18 @@ const hasValidContent = (message: AgentWidgetMessage): boolean => {
   return false;
 };
 
+const sortByCreatedAt = (messages: AgentWidgetMessage[]): AgentWidgetMessage[] =>
+  messages
+    .slice()
+    .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+
+// Priority: contentParts (multi-modal) > llmContent (explicit LLM content) > rawContent (structured parsers) > content (display)
+const toPayloadMessage = (message: AgentWidgetMessage) => ({
+  role: message.role,
+  content: message.contentParts ?? message.llmContent ?? message.rawContent ?? message.content,
+  createdAt: message.createdAt
+});
+
 /**
  * Maps parserType string to the corresponding parser factory function
  */
@@ -294,6 +307,14 @@ export class AgentWidgetClient {
   private currentClientTurnId: string | null = null;
   private clientSession: ClientSession | null = null;
   private sessionInitPromise: Promise<ClientSession> | null = null;
+  /**
+   * Early-init latch for `warmSession()`. `false` = armed. Otherwise it holds
+   * the session value (`null` or an expired session) the one early attempt was
+   * made against, so a failed attempt is not retried on every keystroke. It is
+   * re-armed when a session is installed or cleared, so each session lifetime
+   * gets one early init.
+   */
+  private sessionWarmLatch: ClientSession | null | false = false;
 
   // Diff-only / send-once WebMCP tool dispatch (client-token mode ONLY).
   // Fingerprint of the clientTools[] last *sent in full* and confirmed by a
@@ -608,9 +629,41 @@ export class AgentWidgetClient {
     }
   }
 
+  /**
+   * Fire-and-forget early `initSession()` for client-token mode, driven by the
+   * widget's `sessionInit` trigger (or a host calling it directly, e.g. on
+   * hover). It fires at most once per session lifetime and is a no-op while a
+   * session is live or an init is already in flight. Errors are swallowed, with
+   * no `onSessionExpired` and no UI: a send calls `initSession()` again and
+   * reuses the in-flight promise, so any failure resurfaces there exactly as it
+   * would without the early init. Sends nothing new on the wire. Outside
+   * client-token mode this does nothing.
+   *
+   * Resolves with the session this call initialized, or `null` when it was
+   * skipped or failed. It never rejects.
+   */
+  public async warmSession(): Promise<ClientSession | null> {
+    const current = this.clientSession;
+    if (
+      !this.isClientTokenMode() ||
+      this.sessionInitPromise ||
+      (current && new Date() < current.expiresAt) ||
+      this.sessionWarmLatch === current
+    ) {
+      return null;
+    }
+    this.sessionWarmLatch = current;
+    // Swallowed on purpose: the send's own initSession() reports failures.
+    return this.initSession().catch(() => null);
+  }
+
   /**
    * Initialize session for client token mode.
-   * Called automatically on first message if not already initialized.
+   * Called by the send if no live session exists. The widget normally calls
+   * it earlier, when the visitor shows intent to send (see the `sessionInit`
+   * config option and `warmSession()`), and concurrent calls share one
+   * in-flight request, so a send racing an early init issues a single
+   * `/v1/client/init`.
    */
   public async initSession(): Promise<ClientSession> {
     if (!this.isClientTokenMode()) {
@@ -627,21 +680,28 @@ export class AgentWidgetClient {
       return this.sessionInitPromise;
     }
 
-    this.sessionInitPromise = this._doInitSession();
-    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 {
-      this.sessionInitPromise = null;
-    }
+    // Callers that dedupe share this promise, so the stale check below covers
+    // them too (the send reusing an early init included).
+    const pending: Promise<ClientSession> = (this.sessionInitPromise = this._doInitSession()
+      .then((session) => {
+        // A clear or replacement (credential change, start-new, proof re-init)
+        // while this was in flight makes the result stale: never install it.
+        if (this.sessionInitPromise !== pending) return this.initSession();
+        this.clientSession = session;
+        this.sessionWarmLatch = false;
+        // 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(() => {
+        if (this.sessionInitPromise === pending) this.sessionInitPromise = null;
+      }));
+    return pending;
   }
 
   /** Visitor history rides on client-token init only, and latches off after a 403 degrade. */
@@ -953,6 +1013,7 @@ export class AgentWidgetClient {
     const installed = this.finishInit(session, previousConversationId, false);
     this.clientSession = installed;
     this.sessionInitPromise = null;
+    this.sessionWarmLatch = false;
     this.resetClientToolsFingerprint();
     return installed;
   }
@@ -1019,6 +1080,7 @@ export class AgentWidgetClient {
         if (settled) return;
         settled = true;
         this.clientSession = session;
+        this.sessionWarmLatch = false;
         this.resetClientToolsFingerprint();
       },
       discard: () => {
@@ -1089,6 +1151,7 @@ export class AgentWidgetClient {
   public clearClientSession(): void {
     this.clientSession = null;
     this.sessionInitPromise = null;
+    this.sessionWarmLatch = false;
     this.resetClientToolsFingerprint();
   }
 
@@ -1199,6 +1262,7 @@ export class AgentWidgetClient {
       
       if (response.status === 401) {
         this.clientSession = null;
+        this.sessionWarmLatch = false;
         this.config.onSessionExpired?.();
         throw new Error('Session expired. Please refresh to continue.');
       }
@@ -1218,10 +1282,9 @@ export class AgentWidgetClient {
     messageId: string, 
     type: 'upvote' | 'downvote' | 'copy'
   ): Promise<void> {
-    const session = this.getClientSession();
-    if (!session) {
-      throw new Error('No active session. Please initialize session first.');
-    }
+    // Feedback on a restored transcript can precede any init (`sessionInit`
+    // defers it to intent); the feedback click is intent enough.
+    const session = this.getClientSession() ?? (await this.initSession());
 
     return this.sendFeedback({
       sessionId: session.sessionId,
@@ -1238,10 +1301,7 @@ export class AgentWidgetClient {
    * @param comment - Optional comment
    */
   public async submitCSATFeedback(rating: number, comment?: string): Promise<void> {
-    const session = this.getClientSession();
-    if (!session) {
-      throw new Error('No active session. Please initialize session first.');
-    }
+    const session = this.getClientSession() ?? (await this.initSession());
 
     return this.sendFeedback({
       sessionId: session.sessionId,
@@ -1259,10 +1319,7 @@ export class AgentWidgetClient {
    * @param comment - Optional comment
    */
   public async submitNPSFeedback(rating: number, comment?: string): Promise<void> {
-    const session = this.getClientSession();
-    if (!session) {
-      throw new Error('No active session. Please initialize session first.');
-    }
+    const session = this.getClientSession() ?? (await this.initSession());
 
     return this.sendFeedback({
       sessionId: session.sessionId,
@@ -1298,6 +1355,40 @@ export class AgentWidgetClient {
     return this.config.getIdentityProof ? 'verified-user' : 'browser';
   }
 
+  private async resolveChatIdentityProof(signal?: AbortSignal): Promise<ClientChatRequest['identityProof']> {
+    signal?.throwIfAborted();
+    const provider = this.config.identityProvider;
+    if (provider === undefined) return undefined;
+    const getIdentityProof = this.config.getIdentityProof;
+    if (!provider.trim() || !getIdentityProof) {
+      throw new Error('Chat identity requires identityProvider and getIdentityProof.');
+    }
+    let token: string | null;
+    let onAbort: (() => void) | undefined;
+    try {
+      const proof = Promise.resolve().then(() => getIdentityProof());
+      token = signal
+        ? await Promise.race([
+            proof,
+            new Promise<never>((_, reject) => {
+              onAbort = () => reject(signal.reason);
+              signal.addEventListener('abort', onAbort, { once: true });
+              if (signal.aborted) onAbort();
+            }),
+          ])
+        : await proof;
+    } catch {
+      signal?.throwIfAborted();
+      throw new Error('The identity proof provider failed.');
+    } finally {
+      if (onAbort) signal?.removeEventListener('abort', onAbort);
+    }
+    if (typeof token !== 'string' || !token.trim()) {
+      throw new Error('A fresh identity proof is required to send this message.');
+    }
+    return { provider, token };
+  }
+
   /**
    * Resolve the proof for one logical request. `null` is an intentional
    * browser-scope fallback only while the visitor has never been bound.
@@ -1837,6 +1928,7 @@ export class AgentWidgetClient {
         }
         session = this.finishInit(renewed, previous.conversationId ?? null, false);
         this.clientSession = session;
+        this.sessionWarmLatch = false;
         this.resetClientToolsFingerprint();
         this.config.onSessionInit?.(session);
       };
@@ -1896,16 +1988,23 @@ export class AgentWidgetClient {
         const recoveryVisitorToken =
           session.durableRecovery?.enabled === true ? await this.readVisitorToken() : null;
         assertCurrentTurn();
-        return this.sendWithClientToolsDiff(session.sessionId, basePayload.clientTools, (toolFields) => {
+        return this.sendWithClientToolsDiff(session.sessionId, basePayload.clientTools, async (toolFields) => {
+          assertCurrentTurn();
+          const identityProof = await this.resolveChatIdentityProof(options.signal);
+          assertCurrentTurn();
           const chatRequest: ClientChatRequest = {
             ...baseChatRequest,
             sessionId: session.sessionId,
             ...toolFields,
+            ...(identityProof && { identityProof }),
           };
 
           if (this.debug) {
             // eslint-disable-next-line no-console
-            console.debug("[AgentWidgetClient] client token dispatch", chatRequest);
+            console.debug("[AgentWidgetClient] client token dispatch", {
+              ...chatRequest,
+              ...(identityProof && { identityProof: { provider: identityProof.provider, token: '[REDACTED]' } }),
+            });
           }
 
           return fetch(this.getClientApiUrl('chat'), {
@@ -1938,6 +2037,12 @@ export class AgentWidgetClient {
       if (!response.ok) {
         const data = await response.json().catch(() => ({ error: 'Chat request failed' }));
 
+        if (response.status === 401 && data.error === 'invalid_identity_proof') {
+          const error = new HistoryClientError('invalid_identity_proof', PROOF_REJECTED_MESSAGE);
+          forward({ type: 'error', error });
+          throw error;
+        }
+
         if (response.status === 401) {
           // Session expired
           this.clearClientSession();
@@ -2533,22 +2638,17 @@ export class AgentWidgetClient {
       throw new Error('Agent configuration required for agent mode');
     }
 
-    // Filter out messages with empty content and normalize
-    const normalizedMessages = messages
-      .slice()
-      .filter(hasValidContent)
-      .filter(m => m.role === "user" || m.role === "assistant" || m.role === "system")
-      .filter(m => !m.variant || m.variant === "assistant")
-      .sort((a, b) => {
-        const timeA = new Date(a.createdAt).getTime();
-        const timeB = new Date(b.createdAt).getTime();
-        return timeA - timeB;
-      })
-      .map((message) => ({
-        role: message.role,
-        content: message.contentParts ?? message.llmContent ?? message.rawContent ?? message.content,
-        createdAt: message.createdAt
-      }));
+    // Filter out messages with empty content and normalize; answered
+    // client-tool calls replay as paired toolCalls/toolResults messages.
+    const normalizedMessages = serializeWithToolPairs(
+      sortByCreatedAt(messages),
+      (message) =>
+        hasValidContent(message) &&
+        (message.role === "user" || message.role === "assistant" || message.role === "system") &&
+        (!message.variant || message.variant === "assistant")
+          ? toPayloadMessage(message)
+          : null
+    );
 
     const composer = this.normalizeComposerOptions(composerOptions);
     const payload: AgentWidgetAgentRequestPayload = {
@@ -2590,21 +2690,14 @@ export class AgentWidgetClient {
     messages: AgentWidgetMessage[],
     composerOptions?: ComposerOptionsPayload
   ): Promise<AgentWidgetRequestPayload> {
-    // Filter out messages with empty content to prevent validation errors
-    const normalizedMessages = messages
-      .slice()
-      .filter(hasValidContent)
-      .sort((a, b) => {
-        const timeA = new Date(a.createdAt).getTime();
-        const timeB = new Date(b.createdAt).getTime();
-        return timeA - timeB;
-      })
-      .map((message) => ({
-        role: message.role,
-        // Priority: contentParts (multi-modal) > llmContent (explicit LLM content) > rawContent (structured parsers) > content (display)
-        content: message.contentParts ?? message.llmContent ?? message.rawContent ?? message.content,
-        createdAt: message.createdAt
-      }));
+    // Filter out messages with empty content to prevent validation errors;
+    // answered client-tool calls replay as paired toolCalls/toolResults
+    // messages. Client-token mode maps `options.messages` itself and never
+    // reads these, so the server stays the replay owner there.
+    const normalizedMessages = serializeWithToolPairs(
+      sortByCreatedAt(messages),
+      (message) => (hasValidContent(message) ? toPayloadMessage(message) : null)
+    );
 
     const routed = this.routing();
     const payload: AgentWidgetRequestPayload = {