@runtypelabs/persona 4.6.1 → 4.8.0

package/src/client.ts

@@ -17,13 +17,19 @@ import {
   ClientSession,
   ClientInitResponse,
   ClientChatRequest,
+  ClientToolDefinition,
   ClientFeedbackRequest,
   ClientFeedbackType,
   PersonaArtifactKind,
+  PersonaArtifactFileMeta,
   ContentPart,
   WebMcpConfirmHandler
 } from "./types";
 import { WebMcpBridge, computeClientToolsFingerprint, isWebMcpToolName } from "./webmcp-bridge";
+import {
+  buildArtifactRefRawContent,
+  resolveArtifactDisplayMode
+} from "./utils/artifact-display";
 import { resolveTarget } from "./utils/target";
 import { builtInClientToolsForDispatch } from "./ask-user-question-tool";
 import {
@@ -180,6 +186,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 +452,7 @@ export class AgentWidgetClient {
   public resetClientToolsFingerprint(): void {
     this.lastSentClientToolsFingerprint = null;
     this.clientToolsFingerprintSessionId = null;
+    this.sentNonEmptyClientToolsSessionId = null;
   }
 
   /**
@@ -614,6 +629,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 +643,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 +689,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 +745,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 +769,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 +802,7 @@ export class AgentWidgetClient {
             method: "POST",
             headers,
             body: JSON.stringify(payload),
-            signal: controller.signal
+            signal: options.signal
           },
           payload
         );
@@ -850,7 +816,7 @@ export class AgentWidgetClient {
         method: "POST",
         headers,
         body: JSON.stringify(payload),
-        signal: controller.signal
+        signal: options.signal
       });
     }
 
@@ -874,11 +840,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 +873,7 @@ export class AgentWidgetClient {
             method: "POST",
             headers,
             body: JSON.stringify(payload),
-            signal: controller.signal
+            signal: options.signal
           },
           payload as unknown as AgentWidgetRequestPayload
         );
@@ -926,7 +887,7 @@ export class AgentWidgetClient {
         method: "POST",
         headers,
         body: JSON.stringify(payload),
-        signal: controller.signal
+        signal: options.signal
       });
     }
 
@@ -1007,8 +968,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 +986,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 +1133,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,
@@ -1592,12 +1706,25 @@ export class AgentWidgetClient {
 
     // Track tool call IDs for artifact emit tools so we can suppress their UI
     const artifactToolCallIds = new Set<string>();
-    // Track artifact reference card messages so we can update them on artifact_complete
+    // Track artifact block messages (reference card or inline block) so we can
+    // update them on artifact_complete
     const artifactCardMessages = new Map<string, AgentWidgetMessage>();
     // Track artifact IDs that already have a reference card (from auto-creation or transcript_insert)
     const artifactIdsWithCards = new Set<string>();
-    // Accumulate artifact markdown content for embedding in card props on complete
-    const artifactContent = new Map<string, { markdown: string; title?: string }>();
+    // Accumulate artifact markdown content (and component props) for embedding
+    // in block props on complete. `props` accumulates across `artifact_update`
+    // events so an inline component block hydrates with its real props after a
+    // refresh (the session artifact registry, which also tracks them live, is
+    // not persisted).
+    const artifactContent = new Map<
+      string,
+      {
+        markdown: string;
+        title?: string;
+        file?: PersonaArtifactFileMeta;
+        props?: Record<string, unknown>;
+      }
+    >();
     const isArtifactEmitToolName = (name: string | undefined): boolean => {
       if (!name) return false;
       const normalized = name.replace(/_+/g, "_").replace(/^_|_$/g, "");
@@ -2996,17 +3123,57 @@ export class AgentWidgetClient {
             const at = payload.artifactType as PersonaArtifactKind;
             const artId = String(payload.id);
             const artTitle = typeof payload.title === "string" ? payload.title : undefined;
+            // Additive `file` metadata: validate shape (object with string path +
+            // string mimeType; optional string language). Drop silently if malformed
+            // so old/new backends and unexpected payloads never break the stream.
+            const rawFile = payload.file;
+            let artFile: PersonaArtifactFileMeta | undefined;
+            if (
+              rawFile &&
+              typeof rawFile === "object" &&
+              !Array.isArray(rawFile) &&
+              typeof rawFile.path === "string" &&
+              typeof rawFile.mimeType === "string"
+            ) {
+              artFile = {
+                path: rawFile.path,
+                mimeType: rawFile.mimeType,
+                ...(typeof rawFile.language === "string" ? { language: rawFile.language } : {}),
+              };
+            }
             onEvent({
               type: "artifact_start",
               id: artId,
               artifactType: at,
               title: artTitle,
-              component: typeof payload.component === "string" ? payload.component : undefined
+              component: typeof payload.component === "string" ? payload.component : undefined,
+              ...(artFile ? { file: artFile } : {})
             });
-            artifactContent.set(artId, { markdown: "", title: artTitle });
-            // Insert inline artifact reference card (skip if already present from transcript_insert)
+            // Seed component props from artifact_start when the payload
+            // carries them; artifact_update events accumulate the rest below.
+            const startProps =
+              payload.props && typeof payload.props === "object" && !Array.isArray(payload.props)
+                ? { ...(payload.props as Record<string, unknown>) }
+                : undefined;
+            artifactContent.set(artId, {
+              markdown: "",
+              title: artTitle,
+              file: artFile,
+              ...(startProps ? { props: startProps } : {})
+            });
+            // Insert the in-thread artifact block (skip if already present from
+            // transcript_insert). The resolved display mode picks the component:
+            // "card"/"panel" inject the reference card; "inline" injects the
+            // inline preview block. Both share the rawContent JSON-component
+            // shape so transcript persistence and hydration work unchanged.
             if (!artifactIdsWithCards.has(artId)) {
               artifactIdsWithCards.add(artId);
+              const displayMode = resolveArtifactDisplayMode(
+                this.config.features?.artifacts,
+                at
+              );
+              const artComponent =
+                typeof payload.component === "string" ? payload.component : undefined;
               const cardMsg: AgentWidgetMessage = {
                 id: `artifact-ref-${artId}`,
                 role: "assistant",
@@ -3014,9 +3181,13 @@ export class AgentWidgetClient {
                 createdAt: new Date().toISOString(),
                 streaming: true,
                 sequence: nextSequence(),
-                rawContent: JSON.stringify({
-                  component: "PersonaArtifactCard",
-                  props: { artifactId: artId, title: artTitle, artifactType: at, status: "streaming" },
+                rawContent: buildArtifactRefRawContent(displayMode, {
+                  artifactId: artId,
+                  title: artTitle,
+                  artifactType: at,
+                  status: "streaming",
+                  ...(artFile ? { file: artFile } : {}),
+                  ...(artComponent ? { component: artComponent } : {}),
                 }),
               };
               artifactCardMessages.set(artId, cardMsg);
@@ -3043,6 +3214,13 @@ export class AgentWidgetClient {
               props,
               component: typeof payload.component === "string" ? payload.component : undefined
             });
+            // Accumulate for hydration: embedded on artifact_complete so an
+            // inline component block re-renders with its real props after a
+            // refresh.
+            const updateAcc = artifactContent.get(String(payload.id));
+            if (updateAcc) {
+              updateAcc.props = { ...(updateAcc.props ?? {}), ...props };
+            }
           } else if (payloadType === "artifact_complete") {
             const artCompleteId = String(payload.id);
             onEvent({ type: "artifact_complete", id: artCompleteId });
@@ -3059,6 +3237,20 @@ export class AgentWidgetClient {
                   if (acc?.markdown) {
                     parsed.props.markdown = acc.markdown;
                   }
+                  // Persist file metadata too so the download path unfences correctly after refresh.
+                  if (acc?.file) {
+                    parsed.props.file = acc.file;
+                  }
+                  // Embed accumulated component props so an inline component
+                  // block hydrates with its real props after a refresh. Only
+                  // the inline block reads them; the card never does.
+                  if (
+                    parsed.component === "PersonaArtifactInline" &&
+                    acc?.props &&
+                    Object.keys(acc.props).length > 0
+                  ) {
+                    parsed.props.componentProps = acc.props;
+                  }
                 }
                 refMsg.rawContent = JSON.stringify(parsed);
               } catch { /* ignore parse errors */ }