@runtypelabs/persona 4.23.0 → 4.23.2

package/src/types.ts

@@ -593,10 +593,34 @@ export type AgentWidgetContextMentionTokenRenderContext = {
   readonly: boolean;
 };
 
+/** One earlier client-tool call replayed to the model, in `/v1/dispatch` shape. */
+export type AgentWidgetReplayedToolCall = {
+  toolCallId: string;
+  /** Model-facing (sanitized) name, e.g. `webmcp_search`. */
+  toolName: string;
+  args: Record<string, unknown>;
+};
+
+/** The browser's answer to an {@link AgentWidgetReplayedToolCall}. */
+export type AgentWidgetReplayedToolResult = {
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+};
+
+/**
+ * A message in the proxy/agent request payload. Earlier client-tool calls the
+ * browser answered replay as an assistant message carrying `toolCalls`,
+ * followed by a `tool` message carrying the matching `toolResults`; both have
+ * empty `content`. Client-token mode never sends them: the server replays
+ * from its own stored transcript there.
+ */
 export type AgentWidgetRequestPayloadMessage = {
-  role: AgentWidgetMessageRole;
+  role: AgentWidgetMessageRole | "tool";
   content: MessageContent;
   createdAt: string;
+  toolCalls?: AgentWidgetReplayedToolCall[];
+  toolResults?: AgentWidgetReplayedToolResult[];
 };
 
 export type AgentWidgetRequestPayload = {
@@ -1032,6 +1056,24 @@ export type AgentMessageMetadata = {
    * never re-resume the call.
    */
   suggestRepliesResolved?: boolean;
+  /**
+   * The client-tool answer the server accepted through `/resume`, kept so
+   * later proxy/agent turns can replay the call and its result to the model.
+   * `toolName` is the widget's internal name (`webmcp:<name>` or a bare
+   * built-in). Set only after the resume succeeds; preserved across
+   * re-emissions of the tool message.
+   */
+  clientToolAnswer?: {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    result: unknown;
+    /**
+     * Shared by the answers posted in one `/resume`, i.e. one assistant
+     * turn's parallel calls; a chained call gets a new batch.
+     */
+    batch?: string;
+  };
 };
 
 export type AgentWidgetRequestMiddlewareContext = {

package/src/utils/tool-pair-replay.ts

@@ -0,0 +1,100 @@
+/**
+ * Client-tool pair replay for the proxy and agent payload builders.
+ *
+ * In proxy and agent mode the widget holds the only copy of a client-tool
+ * result, so it owns replaying it. Each call the browser answered through
+ * `/resume` is sent to later turns as an assistant `toolCalls` message plus a
+ * `tool` message with the matching `toolResults`, with the full result.
+ * A pair replays even after the page stops offering its tool: the model
+ * already saw that result, and a follow-up about it must not lose it.
+ */
+
+import type {
+  AgentWidgetMessage,
+  AgentWidgetReplayedToolCall,
+  AgentWidgetReplayedToolResult,
+  AgentWidgetRequestPayloadMessage,
+} from "../types";
+
+/**
+ * The name a tool reaches the model as (`webmcp:get_schema` ->
+ * `webmcp_get_schema`).
+ */
+export const modelFacingToolName = (name: string): string =>
+  name
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .toLowerCase()
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "");
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const replayablePair = (
+  message: AgentWidgetMessage,
+): { call: AgentWidgetReplayedToolCall; result: AgentWidgetReplayedToolResult } | null => {
+  if (message.variant !== "tool") return null;
+  const answer = message.agentMetadata?.clientToolAnswer;
+  if (!answer || !answer.toolCallId || answer.result === undefined) return null;
+  const toolName = modelFacingToolName(answer.toolName);
+  if (!toolName) return null;
+  return {
+    call: {
+      toolCallId: answer.toolCallId,
+      toolName,
+      args: isRecord(answer.args) ? answer.args : {},
+    },
+    result: { toolCallId: answer.toolCallId, toolName, result: answer.result },
+  };
+};
+
+/**
+ * Serialize time-ordered messages, interleaving replayable tool pairs.
+ * `toPayload` maps an ordinary message (or returns null to drop it). Answers
+ * posted in the same `/resume` batch are one assistant turn's parallel calls,
+ * so they group into one call message and one result message; a later batch
+ * (a chained call) starts a new pair even with no text between them.
+ */
+export const serializeWithToolPairs = (
+  messages: readonly AgentWidgetMessage[],
+  toPayload: (message: AgentWidgetMessage) => AgentWidgetRequestPayloadMessage | null,
+): AgentWidgetRequestPayloadMessage[] => {
+  const out: AgentWidgetRequestPayloadMessage[] = [];
+  let calls: AgentWidgetReplayedToolCall[] = [];
+  let results: AgentWidgetReplayedToolResult[] = [];
+  let groupCreatedAt = "";
+  let groupBatch: string | undefined;
+
+  const flush = () => {
+    if (calls.length === 0) return;
+    out.push(
+      { role: "assistant", content: "", createdAt: groupCreatedAt, toolCalls: calls },
+      { role: "tool", content: "", createdAt: groupCreatedAt, toolResults: results },
+    );
+    calls = [];
+    results = [];
+  };
+
+  for (const message of messages) {
+    const pair = replayablePair(message);
+    if (pair) {
+      const batch = message.agentMetadata?.clientToolAnswer?.batch;
+      if (calls.length > 0 && (batch === undefined || batch !== groupBatch)) flush();
+      if (calls.length === 0) {
+        groupCreatedAt = message.createdAt;
+        groupBatch = batch;
+      }
+      if (!calls.some((call) => call.toolCallId === pair.call.toolCallId)) {
+        calls.push(pair.call);
+        results.push(pair.result);
+      }
+      continue;
+    }
+    const mapped = toPayload(message);
+    if (!mapped) continue;
+    flush();
+    out.push(mapped);
+  }
+  flush();
+  return out;
+};