@runtypelabs/persona 4.6.0 → 4.7.0

package/src/client.ts

@@ -17,6 +17,7 @@ import {
   ClientSession,
   ClientInitResponse,
   ClientChatRequest,
+  ClientToolDefinition,
   ClientFeedbackRequest,
   ClientFeedbackType,
   PersonaArtifactKind,
@@ -180,6 +181,14 @@ export class AgentWidgetClient {
   // (silent re-init / expiry) forces a fresh full send.
   private lastSentClientToolsFingerprint: string | null = null;
   private clientToolsFingerprintSessionId: string | null = null;
+  // Session under which a non-empty clientTools[] was last committed and not
+  // yet confirmed cleared server-side. Distinct from the fingerprint above:
+  // an empty-tool chat turn commits a null fingerprint, but OMITTING the
+  // fields on chat doesn't clear the tools persisted for a still-paused
+  // execution — so a later resume with an empty registry must still send the
+  // explicit `clientTools: []` replace. Reset only by an explicit [] replace,
+  // a session change, or a conversation reset.
+  private sentNonEmptyClientToolsSessionId: string | null = null;
 
   // WebMCP: page-discovered tool consumption (see ./webmcp-bridge).
   // Constructed lazily: null when `config.webmcp?.enabled !== true`.
@@ -438,6 +447,7 @@ export class AgentWidgetClient {
   public resetClientToolsFingerprint(): void {
     this.lastSentClientToolsFingerprint = null;
     this.clientToolsFingerprintSessionId = null;
+    this.sentNonEmptyClientToolsSessionId = null;
   }
 
   /**
@@ -614,6 +624,7 @@ export class AgentWidgetClient {
    * Send a message - handles both proxy and client token modes
    */
   public async dispatch(options: DispatchOptions, onEvent: SSEHandler) {
+    options.signal?.throwIfAborted();
     if (this.isClientTokenMode()) {
       return this.dispatchClientToken(options, onEvent);
     }
@@ -627,11 +638,6 @@ export class AgentWidgetClient {
    * Client token mode dispatch
    */
   private async dispatchClientToken(options: DispatchOptions, onEvent: SSEHandler) {
-    const controller = new AbortController();
-    if (options.signal) {
-      options.signal.addEventListener("abort", () => controller.abort());
-    }
-
     onEvent({ type: "status", status: "connecting" });
 
     try {
@@ -678,71 +684,32 @@ export class AgentWidgetClient {
       };
 
       // 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 } : {}),
-        };
-
-        if (this.debug) {
-          // eslint-disable-next-line no-console
-          console.debug("[AgentWidgetClient] client token dispatch", chatRequest);
-        }
+      // snapshotted the full set; `sendWithClientToolsDiff` decides whether to
+      // ship it again or just its fingerprint (retrying once on a 409 registry
+      // miss). The cache is committed only after a successful stream start
+      // (below), so a 409/failure leaves it untouched.
+      const { response, commit: commitClientToolsFingerprint } =
+        await this.sendWithClientToolsDiff(session.sessionId, basePayload.clientTools, (toolFields) => {
+          const chatRequest: ClientChatRequest = { ...baseChatRequest, ...toolFields };
+
+          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',
-            'X-Persona-Version': VERSION,
-          },
-          body: JSON.stringify(chatRequest),
-          signal: controller.signal,
+          return fetch(this.getClientApiUrl('chat'), {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'X-Persona-Version': VERSION,
+            },
+            body: JSON.stringify(chatRequest),
+            signal: options.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 data = errorData ?? (await response.json().catch(() => ({ error: 'Chat request failed' })));
+        const data = await response.json().catch(() => ({ error: 'Chat request failed' }));
 
         if (response.status === 401) {
           // Session expired
@@ -773,8 +740,7 @@ export class AgentWidgetClient {
       // 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;
+      commitClientToolsFingerprint();
 
       onEvent({ type: "status", status: "connected" });
       
@@ -798,11 +764,6 @@ export class AgentWidgetClient {
    * Proxy mode dispatch (original implementation)
    */
   private async dispatchProxy(options: DispatchOptions, onEvent: SSEHandler) {
-    const controller = new AbortController();
-    if (options.signal) {
-      options.signal.addEventListener("abort", () => controller.abort());
-    }
-
     onEvent({ type: "status", status: "connecting" });
 
     const payload = await this.buildPayload(options.messages);
@@ -836,7 +797,7 @@ export class AgentWidgetClient {
             method: "POST",
             headers,
             body: JSON.stringify(payload),
-            signal: controller.signal
+            signal: options.signal
           },
           payload
         );
@@ -850,7 +811,7 @@ export class AgentWidgetClient {
         method: "POST",
         headers,
         body: JSON.stringify(payload),
-        signal: controller.signal
+        signal: options.signal
       });
     }
 
@@ -874,11 +835,6 @@ export class AgentWidgetClient {
    * Agent mode dispatch
    */
   private async dispatchAgent(options: DispatchOptions, onEvent: SSEHandler) {
-    const controller = new AbortController();
-    if (options.signal) {
-      options.signal.addEventListener("abort", () => controller.abort());
-    }
-
     onEvent({ type: "status", status: "connecting" });
 
     const payload = await this.buildAgentPayload(options.messages);
@@ -912,7 +868,7 @@ export class AgentWidgetClient {
             method: "POST",
             headers,
             body: JSON.stringify(payload),
-            signal: controller.signal
+            signal: options.signal
           },
           payload as unknown as AgentWidgetRequestPayload
         );
@@ -926,7 +882,7 @@ export class AgentWidgetClient {
         method: "POST",
         headers,
         body: JSON.stringify(payload),
-        signal: controller.signal
+        signal: options.signal
       });
     }
 
@@ -1007,8 +963,13 @@ export class AgentWidgetClient {
    *  - **client-token mode**: POST `${apiBase}/v1/client/resume` (the
    *    session-authenticated sibling of `/v1/client/chat`; runtypelabs/core#3889),
    *    with the active `sessionId` in the body and no Bearer key: a browser
-   *    client-token page holds no secret. `clientTools` are already persisted
-   *    server-side from the dispatch turn, so only `toolOutputs` is re-sent.
+   *    client-token page holds no secret. The page's tool registry is
+   *    re-snapshotted and sent alongside `toolOutputs` via the same diff-only
+   *    `clientTools` / `clientToolsFingerprint` protocol as `/v1/client/chat`
+   *    (runtypelabs/core#5361), so tools registered by a mid-run page
+   *    navigation replace the run's dispatch-time set and become callable on
+   *    the next model turn. Old servers strip the unknown fields and keep the
+   *    frozen-at-dispatch behavior.
    *  - **dispatch / proxy mode**: POST `${apiUrl}/resume`: Runtype mounts
    *    resume as a child of `/v1/dispatch`, so the URL is `${apiUrl}/resume`,
    *    and proxies follow the same shape (`/api/chat/dispatch/resume`).
@@ -1020,6 +981,113 @@ export class AgentWidgetClient {
    * @param toolOutputs - Map keyed by per-call `toolCallId` (core#3878),
    *   falling back to tool name for legacy servers → the tool's result value.
    */
+  /**
+   * Diff-only / send-once WebMCP clientTools transport, shared by the
+   * client-token chat (`/v1/client/chat`) and resume (`/v1/client/resume`)
+   * paths — both routes speak the same protocol (runtypelabs/core#5361).
+   *
+   * Decides, against the shared fingerprint cache, whether this request ships
+   * the full `clientTools[]` + fingerprint (first send under this session, or
+   * a changed set) or the fingerprint alone (unchanged set; the server reuses
+   * its stored copy). Runs `doFetch` with the chosen fields and retries
+   * EXACTLY once with the full array on a
+   * `409 { error: 'client_tools_resend_required' }` registry miss — the retry
+   * is 409-*triggered*, never 409-*expected*, so servers predating the
+   * protocol (which strip the unknown fields and never 409) work unchanged.
+   * The 409 body is probed on a `clone()` so the original response body stays
+   * readable by the caller's error handling.
+   *
+   * The cache is NOT committed here: callers invoke the returned `commit()`
+   * only after the server has accepted the request (response OK / stream
+   * started), so a failed request can never record a fingerprint the server
+   * never stored. A resend-required miss invalidates the cached fingerprint
+   * immediately so later turns keep resending in full until a clean success
+   * commits a fresh one.
+   *
+   * `emptyMeansReplace` (resume only): when the live snapshot is empty but a
+   * non-empty set was committed under this session and never explicitly
+   * cleared (the paused tool navigated to a page with no tool registry), ship
+   * an explicit `clientTools: []` so the server REPLACES the persisted
+   * dispatch-time set with nothing and clears its stored registry. Chat keeps
+   * its omit-when-empty behavior: on `/chat`, absent fields already mean "no
+   * tools this turn", whereas on `/resume` absence means "keep the frozen
+   * dispatch-time set".
+   */
+  private async sendWithClientToolsDiff(
+    sessionId: string,
+    fullClientTools: ClientToolDefinition[] | undefined,
+    doFetch: (
+      toolFields: Pick<ClientChatRequest, 'clientTools' | 'clientToolsFingerprint'>
+    ) => Promise<Response>,
+    opts?: { emptyMeansReplace?: boolean }
+  ): Promise<{ response: Response; commit: () => void }> {
+    const hasClientTools = !!(fullClientTools && fullClientTools.length > 0);
+    const clientToolsFingerprint = hasClientTools
+      ? computeClientToolsFingerprint(fullClientTools!)
+      : undefined;
+    const sameSession = this.clientToolsFingerprintSessionId === sessionId;
+    const unchanged =
+      hasClientTools && sameSession && this.lastSentClientToolsFingerprint === clientToolsFingerprint;
+    // Keyed on `sentNonEmptyClientToolsSessionId`, NOT the fingerprint: an
+    // interleaved empty-tool chat turn commits a null fingerprint without
+    // clearing the tools persisted for a still-paused execution, so the
+    // fingerprint alone would lose the pending clear. The dedicated flag
+    // survives omitted-empty commits and is reset only once an explicit []
+    // replace is confirmed.
+    const sendEmptyReplace =
+      !hasClientTools &&
+      opts?.emptyMeansReplace === true &&
+      this.sentNonEmptyClientToolsSessionId === sessionId;
+
+    // `forceFull` flips to true after a 409 cache-miss so the single retry
+    // resends the full list.
+    let forceFull = false;
+    let response: Response;
+    for (let attempt = 0; ; attempt++) {
+      const sendFull = hasClientTools && (forceFull || !unchanged);
+      response = await doFetch({
+        ...(sendFull && fullClientTools ? { clientTools: fullClientTools } : {}),
+        ...(sendEmptyReplace ? { clientTools: [] } : {}),
+        ...(clientToolsFingerprint ? { clientToolsFingerprint } : {}),
+      });
+
+      // 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 caller's normal error handling (no infinite loop).
+      if (response.status === 409 && attempt === 0 && hasClientTools) {
+        const body = (await response
+          .clone()
+          .json()
+          .catch(() => null)) as { error?: 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;
+        }
+      }
+      break;
+    }
+
+    return {
+      response,
+      commit: () => {
+        this.lastSentClientToolsFingerprint = clientToolsFingerprint ?? null;
+        this.clientToolsFingerprintSessionId = sessionId;
+        if (hasClientTools) {
+          this.sentNonEmptyClientToolsSessionId = sessionId;
+        } else if (sendEmptyReplace) {
+          // The explicit [] replaced the persisted set server-side; the
+          // pending clear is done.
+          this.sentNonEmptyClientToolsSessionId = null;
+        }
+        // Omitted-empty commits (chat with zero tools) leave the flag set:
+        // they don't touch tools persisted for a paused execution.
+      },
+    };
+  }
+
   public async resumeFlow(
     executionId: string,
     toolOutputs: Record<string, unknown>,
@@ -1060,6 +1128,47 @@ export class AgentWidgetClient {
       body.sessionId = resumeSessionId;
     }
 
+    if (isClientToken && resumeSessionId) {
+      // Mid-run WebMCP tool refresh (runtypelabs/core#5361): the paused tool
+      // may have navigated the page, so the dispatch-time snapshot the server
+      // persisted can be stale. Re-snapshot the registry — the same built-in +
+      // bridge composition as the payload builders, so fingerprints computed
+      // here and on chat turns describe the same tool space — and ship it via
+      // the shared diff-only protocol. `emptyMeansReplace` sends an explicit
+      // `clientTools: []` when the registry vanished after a non-empty send,
+      // so the server replaces the persisted set instead of keeping it frozen.
+      const fullClientTools = [
+        ...builtInClientToolsForDispatch(this.config),
+        ...((await this.webMcpBridge?.snapshotForDispatch()) ?? []),
+      ];
+      const { response, commit } = await this.sendWithClientToolsDiff(
+        resumeSessionId,
+        fullClientTools,
+        (toolFields) => {
+          const resumeRequest = { ...body, ...toolFields };
+          if (this.debug) {
+            // eslint-disable-next-line no-console
+            console.debug("[AgentWidgetClient] client token resume", resumeRequest);
+          }
+          return fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(resumeRequest),
+            signal: options?.signal,
+          });
+        },
+        { emptyMeansReplace: true }
+      );
+      // The server stores the refreshed registry before running the
+      // continuation pipeline, so an OK response means it holds this set under
+      // this fingerprint. Mirror chat's commit-on-success discipline: a failed
+      // resume must not record a fingerprint the server never stored.
+      if (response.ok) {
+        commit();
+      }
+      return response;
+    }
+
     return fetch(url, {
       method: 'POST',
       headers,
@@ -2562,7 +2671,11 @@ export class AgentWidgetClient {
             const message =
               typeof e === "string" && e !== ""
                 ? e
-                : e != null && typeof e === "object" && "message" in e
+                : // Reflect.has, not `in`: the `in` operator inside an arrow body can
+                  // be minified into a `for(init;;)` head, which Oxc mis-parses and
+                  // Rolldown (Vite 8) silently emits as an empty chunk. Same
+                  // [[HasProperty]] semantics. Enforced by scripts/check-dist-no-in-for-init.mjs.
+                  e != null && typeof e === "object" && Reflect.has(e, "message")
                   ? String((e as { message?: unknown }).message ?? "Step failed")
                   : "Step failed";
             onEvent({ type: "error", error: new Error(message) });
@@ -3145,7 +3258,8 @@ export class AgentWidgetClient {
             const e = payload.error;
             if (typeof e === "string" && e !== "") {
               resolvedError = new Error(e);
-            } else if (e != null && typeof e === "object" && "message" in e) {
+            } else if (e != null && typeof e === "object" && Reflect.has(e, "message")) {
+              // Reflect.has, not `in` — see the note on the equivalent guard above.
               resolvedError = new Error(String((e as { message?: unknown }).message ?? e));
             }
           }

package/src/generated/runtype-openapi-contract.ts

@@ -41,6 +41,7 @@ export type RuntypeExecutionStreamEvent = ({
 };
   type: "execution_complete";
 }) | ({
+  blockReason?: string;
   code?: string;
   completedAt?: string;
   error: string | {
@@ -295,6 +296,7 @@ export type RuntypeExecutionStreamEvent = ({
   startedAt?: string;
   subagent?: {
   agentName?: string;
+  parentToolCallId?: string;
   toolName: string;
 };
   timeout?: number;
@@ -389,6 +391,7 @@ export type RuntypeFlowSSEEvent = {
   totalTokensUsed?: number;
   type: "flow_complete";
 } | ({
+  blockReason?: string;
   code?: string;
   error: string | {
   code: string;
@@ -409,6 +412,7 @@ export type RuntypeFlowSSEEvent = {
   type: "flow_error";
   upgradeUrl?: string;
 }) | ({
+  approvalId?: string;
   awaitReason?: string;
   awaitedAt: string;
   crawlId?: string;
@@ -419,6 +423,7 @@ export type RuntypeFlowSSEEvent = {
   parameters?: Record<string, unknown>;
   seq?: number;
   stepId?: string;
+  timeout?: number;
   toolCallId?: string;
   toolId?: string;
   toolName?: string;
@@ -673,7 +678,7 @@ export type RuntypeClientInitResponse = {
   welcomeMessage?: string | null;
 };
   expiresAt: string;
-  flow: {
+  flow?: {
   description?: string | null;
   id: string;
   name?: string | null;
@@ -695,6 +700,10 @@ export type RuntypeClientChatRequest = {
   untrustedContentHint?: boolean;
 }>;
   clientToolsFingerprint?: string;
+  identityProof?: {
+  provider: string;
+  token: string;
+};
   inputs?: Record<string, unknown>;
   messages: Array<{
   content: string | (Array<{

package/src/runtime/persist-state.test.ts

@@ -16,6 +16,23 @@ const baseConfig = () => ({
 const inject = (controller: ReturnType<typeof createAgentExperience>) =>
   controller.injectAssistantMessage({ content: "hello world" });
 
+const deferred = () => {
+  let resolve!: () => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+};
+
+const flushMicrotasks = async (times = 4) => {
+  for (let index = 0; index < times; index += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+};
+
 describe("persistState gates storage adapter", () => {
   afterEach(() => {
     document.body.innerHTML = "";
@@ -149,4 +166,105 @@ describe("persistState gates storage adapter", () => {
     expect(controller.getMessages()).toEqual([]);
     controller.destroy();
   });
+
+  it("serializes async saves and preserves the newest transcript", async () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const firstSave = deferred();
+    const payloads: Array<{ messages?: Array<{ content?: string }> }> = [];
+    const save = vi.fn((state: { messages?: Array<{ content?: string }> }) => {
+      payloads.push(state);
+      return save.mock.calls.length === 1 ? firstSave.promise : Promise.resolve();
+    });
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save },
+    });
+
+    controller.injectAssistantMessage({ content: "first" });
+    controller.injectAssistantMessage({ content: "second" });
+
+    expect(save).toHaveBeenCalledTimes(1);
+    firstSave.resolve();
+    await flushMicrotasks();
+
+    expect(save).toHaveBeenCalledTimes(2);
+    expect(payloads[1].messages?.map((message) => message.content)).toEqual([
+      "first",
+      "second",
+    ]);
+    controller.destroy();
+  });
+
+  it("orders clear after pending saves so stale state cannot be resurrected", async () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const firstSave = deferred();
+    const operations: string[] = [];
+    const save = vi.fn(() => {
+      operations.push("save");
+      return save.mock.calls.length === 1 ? firstSave.promise : Promise.resolve();
+    });
+    const clear = vi.fn(() => {
+      operations.push("clear");
+      return Promise.resolve();
+    });
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save, clear },
+    });
+
+    inject(controller);
+    controller.clearChat();
+
+    expect(operations).toEqual(["save"]);
+    firstSave.resolve();
+    await flushMicrotasks(20);
+
+    expect(operations).toEqual(["save", "save", "clear"]);
+    expect(clear).toHaveBeenCalledTimes(1);
+    controller.destroy();
+  });
+
+  it("continues queued storage mutations after an async save rejects", async () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const firstSave = deferred();
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const save = vi.fn(() =>
+      save.mock.calls.length === 1 ? firstSave.promise : Promise.resolve()
+    );
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save },
+    });
+
+    controller.injectAssistantMessage({ content: "first" });
+    controller.injectAssistantMessage({ content: "second" });
+    firstSave.reject(new Error("storage unavailable"));
+    await flushMicrotasks(8);
+
+    expect(save).toHaveBeenCalledTimes(2);
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[AgentWidget] Failed to persist state:",
+      expect.any(Error)
+    );
+    errorSpy.mockRestore();
+    controller.destroy();
+  });
+
+  it("keeps synchronous adapters synchronous", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const save = vi.fn();
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save },
+    });
+
+    inject(controller);
+
+    expect(save).toHaveBeenCalledTimes(1);
+    controller.destroy();
+  });
 });

package/src/ui.scroll-additive.test.ts

@@ -30,7 +30,7 @@ const getLiveRegion = (mount: HTMLElement) =>
 const installRafMock = () => {
   let nextId = 1;
   const callbacks = new Map<number, RafCallback>();
-  let now = 0;
+  let now = performance.now();
   vi.stubGlobal("requestAnimationFrame", (cb: RafCallback) => {
     const id = nextId++;
     callbacks.set(id, cb);