@runtypelabs/persona 3.31.1 → 3.34.0

package/src/session.ts

@@ -1,5 +1,9 @@
 import { AgentWidgetClient, type SSEEventCallback } from "./client";
 import { isWebMcpToolName } from "./webmcp-bridge";
+import {
+  SUGGEST_REPLIES_TOOL_NAME,
+  suggestRepliesToolResult,
+} from "./suggest-replies-tool";
 import {
   AgentWidgetConfig,
   AgentWidgetEvent,
@@ -40,6 +44,49 @@ export type AgentWidgetSessionStatus =
   | "connected"
   | "error";
 
+/**
+ * Config fields the `AgentWidgetClient` reads to shape the connection and each
+ * request. When NONE of these change, `updateConfig` can refresh the live
+ * client in place (preserving the WebMCP bridge and any in-flight stream/resume)
+ * instead of swapping in a fresh client and tearing down WebMCP state. Fields
+ * outside this list (theme, copy, layout, suggestionChips, iterationDisplay,
+ * postprocessMessage, feature display toggles, …) are display-only and safe to
+ * apply mid-turn — which is what a self-styling widget needs when a `webmcp:*`
+ * theme tool re-renders the widget while the agent's turn is still streaming.
+ *
+ * Compared by identity (`!==`): primitives by value, functions/objects by
+ * reference. A consumer that rebuilds these objects on every render simply
+ * takes the (still-correct) full-rebuild path. The default is therefore safe:
+ * anything not explicitly listed here can never strand a paused turn.
+ */
+const CONNECTION_CONFIG_KEYS = [
+  "apiUrl",
+  "clientToken",
+  "flowId",
+  "agent",
+  "agentOptions",
+  "headers",
+  "getHeaders",
+  "webmcp",
+  "streamParser",
+  "parserType",
+  "contextProviders",
+  "requestMiddleware",
+  "customFetch",
+  "parseSSEEvent",
+  "onSessionInit",
+  "onSessionExpired",
+  "getStoredSessionId",
+  "setStoredSessionId",
+] as const satisfies ReadonlyArray<keyof AgentWidgetConfig>;
+
+function connectionConfigChanged(
+  prev: AgentWidgetConfig,
+  next: AgentWidgetConfig,
+): boolean {
+  return CONNECTION_CONFIG_KEYS.some((key) => prev[key] !== next[key]);
+}
+
 type SessionCallbacks = {
   onMessagesChanged: (messages: AgentWidgetMessage[]) => void;
   onStatusChanged: (status: AgentWidgetSessionStatus) => void;
@@ -91,6 +138,15 @@ const getWebMcpErrorMessage = (
   return fallback;
 };
 
+/**
+ * Tool names whose `step_await` the widget resolves automatically (no user
+ * pill click): `webmcp:*` page tools and the built-in fire-and-forget
+ * `suggest_replies`. These share the await-batch / dedupe / resume machinery;
+ * `ask_user_question` is NOT one of them — it blocks on the answer sheet.
+ */
+const isAutoResolvedLocalToolName = (name: string): boolean =>
+  isWebMcpToolName(name) || name === SUGGEST_REPLIES_TOOL_NAME;
+
 export class AgentWidgetSession {
   private client: AgentWidgetClient;
   private messages: AgentWidgetMessage[];
@@ -615,6 +671,21 @@ export class AgentWidgetSession {
   }
 
   public updateConfig(next: AgentWidgetConfig) {
+    const merged = { ...this.config, ...next };
+
+    // Connection/request-shaping change (apiUrl, clientToken, webmcp, headers,
+    // parser, agent, …) → full client rebuild. UI-only change (theme, copy,
+    // layout, suggestions, …) → refresh in place so the live stream, WebMCP
+    // bridge, and any in-flight resolve survive. The latter is what makes a
+    // self-styling widget work: a `webmcp:*` theme tool mutates config and
+    // re-renders mid-turn; recreating the client there would abort the very
+    // turn that's restyling the widget and strand the paused execution.
+    if (!connectionConfigChanged(this.config, merged)) {
+      this.config = merged;
+      this.client.updateConfig(merged);
+      return;
+    }
+
     // Replacing the client invalidates every in-flight WebMCP resolve, buffered
     // parallel-await batch, and pending approval bubble tied to the OLD client/
     // session. Tear them down BEFORE the swap (the new client has no session
@@ -626,7 +697,7 @@ export class AgentWidgetSession {
     this.webMcpInflightKeys.clear();
     this.webMcpResolvedKeys.clear();
     const prevSSECallback = this.client.getSSEEventCallback();
-    this.config = { ...this.config, ...next };
+    this.config = merged;
     this.client = new AgentWidgetClient(this.config);
     this.wireDefaultWebMcpConfirm();
     if (prevSSECallback) {
@@ -1535,7 +1606,8 @@ export class AgentWidgetSession {
   }
 
   /**
-   * Collect a `webmcp:*` LOCAL-tool `step_await` into a per-executionId batch
+   * Collect an auto-resolving LOCAL-tool `step_await` (`webmcp:*` page tools
+   * and the built-in `suggest_replies`) into a per-executionId batch
    * and schedule a single deferred flush. Parallel calls (core#3878) emit
    * several `step_await`s for ONE paused execution within the same stream tick;
    * buffering them and flushing once lets us post ONE `/resume` keyed by the
@@ -1636,6 +1708,26 @@ export class AgentWidgetSession {
     return Date.now();
   }
 
+  /**
+   * Persisted-resolution guard for `suggest_replies`. The in-memory dedupe
+   * sets (`webMcpInflightKeys` / `webMcpResolvedKeys`) are cleared by
+   * hydrateMessages/clearMessages/cancel, but `suggestRepliesResolved`
+   * survives on the stored message — so a stale `step_await` re-emit after a
+   * hydration must not re-POST `/resume` for an already-resolved call (the
+   * historical double-resume failure mode the batching work exists to avoid).
+   * Checks the LIVE message first; the handleEvent snapshot is a fresh wire
+   * skeleton whose metadata never carries the flag.
+   */
+  private isSuggestRepliesAlreadyResolved(
+    toolMessage: AgentWidgetMessage,
+  ): boolean {
+    if (toolMessage.toolCall?.name !== SUGGEST_REPLIES_TOOL_NAME) return false;
+    const stored = this.messages.find((m) => m.id === toolMessage.id);
+    return (
+      (stored ?? toolMessage).agentMetadata?.suggestRepliesResolved === true
+    );
+  }
+
   private markWebMcpToolRunning(
     toolMessage: AgentWidgetMessage,
   ): number {
@@ -1666,6 +1758,9 @@ export class AgentWidgetSession {
     result: unknown,
     startedAt: number,
     completedAt = Date.now(),
+    extraMetadata?: Partial<
+      NonNullable<AgentWidgetMessage["agentMetadata"]>
+    >,
   ): void {
     // A teardown such as clearMessages()/hydrateMessages()/new send can remove
     // the bubble while an aborted WebMCP promise is settling. Never resurrect a
@@ -1677,6 +1772,7 @@ export class AgentWidgetSession {
       agentMetadata: {
         ...toolMessage.agentMetadata,
         awaitingLocalTool: false,
+        ...extraMetadata,
       },
       toolCall: toolMessage.toolCall
         ? {
@@ -1738,7 +1834,8 @@ export class AgentWidgetSession {
         const dedupeKey = `${executionId}:${callId}`;
         if (
           this.webMcpInflightKeys.has(dedupeKey) ||
-          this.webMcpResolvedKeys.has(dedupeKey)
+          this.webMcpResolvedKeys.has(dedupeKey) ||
+          this.isSuggestRepliesAlreadyResolved(toolMessage)
         ) {
           return null;
         }
@@ -1750,15 +1847,29 @@ export class AgentWidgetSession {
         // only means the server paused for a local tool; it is not completion.
         const startedAt = this.markWebMcpToolRunning(toolMessage);
 
-        const controller = new AbortController();
-        this.webMcpResolveControllers.add(controller);
-        controllers.push(controller);
-
         // Per-call id wins for resume keying; fall back to the wire tool name
         // for legacy servers that don't emit `webMcpToolCallId`.
         const resumeKey =
           toolMessage.agentMetadata?.webMcpToolCallId ?? wireToolName;
 
+        // Built-in fire-and-forget tool: no bridge, no confirm gate, no
+        // browser-side execution — the chips render from the message list and
+        // the canned output joins the batch's single /resume.
+        if (wireToolName === SUGGEST_REPLIES_TOOL_NAME) {
+          return {
+            dedupeKey,
+            resumeKey,
+            output: suggestRepliesToolResult(),
+            toolMessage,
+            startedAt,
+            completedAt: Date.now(),
+          };
+        }
+
+        const controller = new AbortController();
+        this.webMcpResolveControllers.add(controller);
+        controllers.push(controller);
+
         const execPromise = this.client.executeWebMcpToolCall(
           wireToolName,
           toolMessage.toolCall?.args,
@@ -1853,6 +1964,9 @@ export class AgentWidgetSession {
           r.output,
           r.startedAt,
           r.completedAt,
+          r.toolMessage.toolCall?.name === SUGGEST_REPLIES_TOOL_NAME
+            ? { suggestRepliesResolved: true }
+            : undefined,
         );
       }
       if (response.body) {
@@ -1892,12 +2006,16 @@ export class AgentWidgetSession {
   }
 
   /**
-   * Resolve a paused `webmcp:*` LOCAL tool call by executing it against the
-   * host page's tool registry and posting the result to `/resume`.
+   * Resolve a paused auto-resolving LOCAL tool call and post the result to
+   * `/resume`: `webmcp:*` calls execute against the host page's tool
+   * registry; the built-in `suggest_replies` skips execution entirely and
+   * resumes with a canned "shown" result (the chips render from the message
+   * list, not from this resolve).
    *
    * Triggered automatically from `handleEvent` when a `step_await`-derived
-   * message arrives with a `webmcp:` prefix — the user does not click a
-   * pill; the bridge's confirm-bubble gate is the only interactive surface.
+   * message arrives for such a tool — the user does not click a pill; the
+   * bridge's confirm-bubble gate (WebMCP only) is the only interactive
+   * surface.
    *
    * Idempotent on the message's `toolCall.id`: re-emits of the same step_await
    * (e.g. from message coalescing) won't double-fire `tool.execute`. Failure
@@ -1918,8 +2036,9 @@ export class AgentWidgetSession {
     //     via onError so an operator can react. This is a server-side
     //     wire-shape bug — Persona can't recover it from the client.
     //   - no wireToolName: defensive guard — handleEvent only calls us
-    //     when tc.name is a `webmcp:` prefix, so this path indicates a
-    //     direct caller misuse. Silent return.
+    //     for an auto-resolving local tool name (`webmcp:*` or
+    //     `suggest_replies`), so this path indicates a direct caller
+    //     misuse. Silent return.
     //   - no toolCallId: dedupe key falls apart, but the server can still
     //     advance if we post an isError for the wireToolName. Do that
     //     and bail before the dedupe path.
@@ -1966,11 +2085,14 @@ export class AgentWidgetSession {
     }
 
     // Dedupe key scoped by executionId — see `webMcpInflightKeys` doc comment
-    // for the failure-recovery + cross-dispatch rationale.
+    // for the failure-recovery + cross-dispatch rationale. The persisted
+    // `suggestRepliesResolved` guard backs the in-memory sets across
+    // hydrations.
     const dedupeKey = `${executionId}:${toolCallId}`;
     if (
       this.webMcpInflightKeys.has(dedupeKey) ||
-      this.webMcpResolvedKeys.has(dedupeKey)
+      this.webMcpResolvedKeys.has(dedupeKey) ||
+      this.isSuggestRepliesAlreadyResolved(toolMessage)
     ) {
       return;
     }
@@ -1999,21 +2121,27 @@ export class AgentWidgetSession {
     const { signal } = resolveController;
     this.setStreaming(true);
 
+    // Built-in fire-and-forget tool: no bridge, no confirm gate, no
+    // browser-side execution — the chips render from the message list and the
+    // canned output resumes the execution immediately. Branch BEFORE any
+    // bridge access so the missing-bridge error path can never fire for it.
+    const isSuggestReplies = wireToolName === SUGGEST_REPLIES_TOOL_NAME;
+
     const args = toolMessage.toolCall?.args;
     // Thread the signal INTO the bridge — short-circuits the confirm bubble
     // and the execute() race on cancel(), so a late confirm-approval after
     // cancel() cannot fire a host-page side effect with no matching /resume.
-    const execPromise = this.client.executeWebMcpToolCall(
-      wireToolName,
-      args,
-      signal,
-    );
+    const execPromise = isSuggestReplies
+      ? null
+      : this.client.executeWebMcpToolCall(wireToolName, args, signal);
 
     let phase: "execute" | "resume" = "execute";
     let completedAt = startedAt;
     try {
       let resumeOutput: unknown;
-      if (!execPromise) {
+      if (isSuggestReplies) {
+        resumeOutput = suggestRepliesToolResult();
+      } else if (!execPromise) {
         // Client has no bridge (config.webmcp.enabled !== true). Resume with
         // an error so the dispatch can advance instead of hanging.
         resumeOutput = {
@@ -2062,6 +2190,7 @@ export class AgentWidgetSession {
             resumeOutput,
             startedAt,
             completedAt,
+            isSuggestReplies ? { suggestRepliesResolved: true } : undefined,
           );
         },
         signal,
@@ -2380,10 +2509,13 @@ export class AgentWidgetSession {
     if (event.type === "message") {
       this.upsertMessage(event.message);
 
-      // WebMCP auto-resolve: when a step_await emits a tool-variant message
-      // for a `webmcp:*` tool, drive the bridge to execute it and post the
-      // result to /resume. Unlike ask_user_question, no user pill click is
-      // required — the bridge's confirm bubble is the only interactive surface.
+      // Local-tool auto-resolve: when a step_await emits a tool-variant
+      // message for a `webmcp:*` tool — or the built-in fire-and-forget
+      // `suggest_replies` — resolve it and post the result to /resume.
+      // Unlike ask_user_question, no user pill click is required; for WebMCP
+      // the bridge's confirm bubble is the only interactive surface, and
+      // suggest_replies resumes with a canned "shown" result while the chips
+      // render above the composer.
       //
       // Defer via `queueMicrotask` so handleEvent returns FIRST. The current
       // SSE consumer is still mid-loop; once we return, the dispatch's
@@ -2397,11 +2529,19 @@ export class AgentWidgetSession {
       // if the bridge is non-operational. Otherwise the dispatch stays paused
       // indefinitely — `resolveWebMcpToolCall` translates the missing-bridge
       // case into an isError result that resumes the flow cleanly.
+      // `suggest_replies`, by contrast, is gated on its feature flag: when
+      // `features.suggestReplies.enabled === false` the widget neither
+      // renders chips nor resumes — the same parked-execution posture as a
+      // server-declared ask_user_question with its sheet disabled.
       const tc = event.message.toolCall;
+      const autoResolvable =
+        !!tc?.name &&
+        (isWebMcpToolName(tc.name) ||
+          (tc.name === SUGGEST_REPLIES_TOOL_NAME &&
+            this.config.features?.suggestReplies?.enabled !== false));
       if (
         event.message.agentMetadata?.awaitingLocalTool === true &&
-        tc?.name &&
-        isWebMcpToolName(tc.name)
+        autoResolvable
       ) {
         // Collect the await into its executionId's batch instead of resolving
         // it on the spot. Parallel same-tool calls (core#3878) arrive as
@@ -2659,6 +2799,21 @@ export class AgentWidgetSession {
           awaitingLocalTool: false,
         };
       }
+      // suggest_replies equivalent: preserve the persisted fire-and-forget
+      // resolution across re-emissions. It is the only dedupe signal that
+      // survives a hydration (the in-memory key sets are cleared), so a
+      // stale step_await re-emit must not wipe it before
+      // `isSuggestRepliesAlreadyResolved` checks it in the resolve path.
+      if (
+        existing.agentMetadata?.suggestRepliesResolved === true &&
+        withSequence.agentMetadata
+      ) {
+        merged.agentMetadata = {
+          ...(merged.agentMetadata ?? withSequence.agentMetadata),
+          suggestRepliesResolved: true,
+          awaitingLocalTool: false,
+        };
+      }
       // Approval equivalent: `agent_approval_complete` carries only the
       // resolution (approvalId, decision, resolvedBy) — the runtime does not
       // re-send toolName/description/toolType/reason/parameters, so client.ts
@@ -2686,9 +2841,10 @@ export class AgentWidgetSession {
           parameters: incoming.parameters ?? prior.parameters,
         };
       }
-      // WebMCP equivalent: once a `webmcp:*` tool has started resolving
-      // (inflight) or resolved, a duplicate `step_await` re-emit must not
-      // flip `awaitingLocalTool` back to true and resurrect the "waiting on
+      // Auto-resolved local-tool equivalent (`webmcp:*` and the built-in
+      // `suggest_replies`): once such a tool has started resolving (inflight)
+      // or resolved, a duplicate `step_await` re-emit must not flip
+      // `awaitingLocalTool` back to true and resurrect the "waiting on
       // local tool" UI. It also must not overwrite an existing running or
       // completed toolCall with the fresh running skeleton emitted by client.ts
       // for every step_await. resolveWebMcpToolCall's dedupe path returns
@@ -2699,7 +2855,7 @@ export class AgentWidgetSession {
       const reTcId = withSequence.toolCall?.id;
       if (
         reTcName &&
-        isWebMcpToolName(reTcName) &&
+        isAutoResolvedLocalToolName(reTcName) &&
         reExecId &&
         reTcId &&
         withSequence.agentMetadata?.awaitingLocalTool === true
@@ -2712,7 +2868,7 @@ export class AgentWidgetSession {
           existing.agentMetadata?.executionId === reExecId &&
           existing.toolCall?.id === reTcId &&
           existingToolName !== undefined &&
-          isWebMcpToolName(existingToolName) &&
+          isAutoResolvedLocalToolName(existingToolName) &&
           existing.toolCall?.status === "complete";
         if (isInflight || isResolved || hasCompletedTool) {
           merged.agentMetadata = {

package/src/session.webmcp.test.ts

@@ -1075,6 +1075,54 @@ describe("AgentWidgetSession — WebMCP parallel batched resume (core#3878)", ()
     expect(s.webMcpApprovalResolvers.size).toBe(0);
   });
 
+  it("a UI-only updateConfig preserves the client, bridge, and in-flight WebMCP state", async () => {
+    // Self-styling widget: a `webmcp:*` theme tool mutates config and re-renders
+    // mid-turn. updateConfig must NOT swap the client when only display fields
+    // (theme/copy/…) change — doing so would abort the very turn that's
+    // restyling the widget and strand the paused execution. (Inverse of the
+    // teardown test above.)
+    const { session } = makeSession();
+    const s = session as unknown as {
+      client: unknown;
+      config: { copy?: { welcomeTitle?: string } };
+      webMcpAwaitBatches: Map<string, unknown>;
+      webMcpApprovalResolvers: Map<string, unknown>;
+    };
+    const clientBefore = s.client;
+    feed(session, parallelAwait("toolu_A", "SHOE-001"));
+    feed(session, parallelAwait("toolu_B", "SHOE-007"));
+    session.requestWebMcpApproval({
+      toolName: "add_to_cart",
+      args: { sku: "SHOE-001" },
+    } as WebMcpConfirmInfo);
+    expect(s.webMcpAwaitBatches.size).toBe(1);
+    expect(s.webMcpApprovalResolvers.size).toBe(1);
+
+    // No apiUrl / webmcp in the patch → connection unchanged → in-place refresh.
+    session.updateConfig({ copy: { welcomeTitle: "Recolored" } });
+
+    expect(s.client).toBe(clientBefore); // same client instance, not swapped
+    expect(s.config.copy?.welcomeTitle).toBe("Recolored"); // display change applied
+    expect(s.webMcpAwaitBatches.size).toBe(1); // batch survives
+    expect(s.webMcpApprovalResolvers.size).toBe(1); // approval still pending
+  });
+
+  it("a connection change (apiUrl) still swaps the client and tears down WebMCP state", () => {
+    const { session } = makeSession();
+    const s = session as unknown as {
+      client: unknown;
+      webMcpAwaitBatches: Map<string, unknown>;
+    };
+    const clientBefore = s.client;
+    feed(session, parallelAwait("toolu_A", "SHOE-001"));
+    expect(s.webMcpAwaitBatches.size).toBe(1);
+
+    session.updateConfig({ apiUrl: "http://other" });
+
+    expect(s.client).not.toBe(clientBefore); // fresh client
+    expect(s.webMcpAwaitBatches.size).toBe(0); // batch torn down
+  });
+
   it("a teardown before the stream-end flush strands the batch", async () => {
     const { session, executeSpy, resumeSpy } = makeSession();
     feed(session, parallelAwait("toolu_A", "SHOE-001"));