@runtypelabs/persona 3.28.0 → 3.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.28.0",
+  "version": "3.29.1",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/client.test.ts

@@ -3056,6 +3056,46 @@ describe('AgentWidgetClient — step_await parsing', () => {
     expect(toolMsg!.agentMetadata?.awaitingLocalTool).toBe(true);
   });
 
+  it('emits a running tool message for WebMCP local_tool_required until the browser tool resolves', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      body: buildStepAwaitStream({
+        awaitReason: 'local_tool_required',
+        id: 'step-1',
+        name: 'Test Step',
+        stepType: 'prompt',
+        index: 0,
+        toolCallId: 'tc_webmcp_1',
+        toolName: 'webmcp:get_product_by_url',
+        executionId: 'exec_abc',
+        startedAt: 1234,
+        parameters: { path: '/jade/' },
+      }),
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const toolMsg = events
+      .filter((e) => e.type === 'message')
+      .map((e) => (e as { message: AgentWidgetMessage }).message)
+      .find((m) => m.variant === 'tool' && m.toolCall?.name === 'webmcp:get_product_by_url');
+
+    expect(toolMsg).toBeDefined();
+    expect(toolMsg!.toolCall!.id).toBe('tc_webmcp_1');
+    expect(toolMsg!.toolCall!.status).toBe('running');
+    expect(toolMsg!.toolCall!.startedAt).toBe(1234);
+    expect(toolMsg!.toolCall!.completedAt).toBeUndefined();
+    expect(toolMsg!.toolCall!.durationMs).toBeUndefined();
+    expect(toolMsg!.toolCall!.args).toEqual({ path: '/jade/' });
+    expect(toolMsg!.agentMetadata?.executionId).toBe('exec_abc');
+    expect(toolMsg!.agentMetadata?.awaitingLocalTool).toBe(true);
+  });
+
   it('ignores step_await events whose awaitReason is not local_tool_required', async () => {
     global.fetch = vi.fn().mockResolvedValue({
       ok: true,

package/src/client.ts

@@ -23,7 +23,7 @@ import {
   ContentPart,
   WebMcpConfirmHandler
 } from "./types";
-import { WebMcpBridge, computeClientToolsFingerprint } from "./webmcp-bridge";
+import { WebMcpBridge, computeClientToolsFingerprint, isWebMcpToolName } from "./webmcp-bridge";
 import {
   extractTextFromJson,
   createPlainTextParser,
@@ -2026,14 +2026,28 @@ export class AgentWidgetClient {
           const toolId =
             toolCallId ?? (payload.toolId as string) ?? `local-${nextSequence()}`;
           const toolMessage = ensureToolMessage(toolId);
+          const toolName = payload.toolName as string;
+          const webMcpTool = isWebMcpToolName(toolName);
           const tool = toolMessage.toolCall ?? { id: toolId, status: "pending" as const };
-          tool.name = payload.toolName as string;
+          tool.name = toolName;
           tool.args = payload.parameters;
-          tool.status = "complete";
+          // WebMCP tools are executed asynchronously by the browser AFTER this
+          // `step_await` arrives. Keep them running until session.ts resolves
+          // the page tool and records its actual elapsed time. Other local
+          // tools (for example ask_user_question) keep the existing complete
+          // state because they are waiting for a user interaction, not an
+          // automatic page-tool execution.
+          tool.status = webMcpTool ? "running" : "complete";
           tool.chunks = tool.chunks ?? [];
           tool.startedAt =
             tool.startedAt ?? resolveTimestamp(payload.startedAt ?? payload.timestamp);
-          tool.completedAt = tool.completedAt ?? tool.startedAt;
+          if (webMcpTool) {
+            tool.completedAt = undefined;
+            tool.duration = undefined;
+            tool.durationMs = undefined;
+          } else {
+            tool.completedAt = tool.completedAt ?? tool.startedAt;
+          }
           toolMessage.toolCall = tool;
           toolMessage.streaming = false;
           toolMessage.agentMetadata = {

package/src/codegen.test.ts

@@ -36,4 +36,47 @@ describe("codegen subpath", () => {
     expect(code).toContain(`@runtypelabs/persona@${VERSION}/dist/install.global.js`);
     expect(code).not.toContain("@latest");
   });
+
+  describe("mount target option", () => {
+    it("defaults to body when no target is given", () => {
+      expect(fromSubpath(config, "react-component")).toContain("target: 'body'");
+      expect(fromSubpath(config, "script-manual")).toContain("target: 'body'");
+      // installer omits the target key entirely (installer falls back to body)
+      expect(fromSubpath(config, "script-installer")).not.toContain('"target"');
+    });
+
+    it("emits the selector as the initAgentWidget target for code formats", () => {
+      const opts = { target: "#chat" };
+      expect(fromSubpath(config, "esm", opts)).toContain("target: '#chat'");
+      expect(fromSubpath(config, "react-component", opts)).toContain("target: '#chat'");
+      expect(fromSubpath(config, "script-manual", opts)).toContain("target: '#chat'");
+    });
+
+    it("serializes the selector as a top-level installer option (sibling of config)", () => {
+      // install.ts reads the mount point from the TOP LEVEL of data-config, not
+      // from inside the widget config. Parse the emitted data-config and assert
+      // the structure so a regression to the nested form is caught.
+      const code = fromSubpath(config, "script-installer", { target: "#chat" });
+      const json = code.match(/data-config='([^']*)'/)?.[1];
+      expect(json).toBeTruthy();
+      const parsed = JSON.parse(json!);
+      expect(parsed.target).toBe("#chat");
+      expect(parsed.config).toBeTruthy();
+      // target must NOT be buried inside the widget config (where it's ignored)
+      expect(parsed.config.target).toBeUndefined();
+    });
+
+    it("keeps target as a top-level sibling alongside windowKey", () => {
+      const code = fromSubpath(config, "script-installer", { target: "#chat", windowKey: "myWidget" });
+      const parsed = JSON.parse(code.match(/data-config='([^']*)'/)![1]);
+      expect(parsed.target).toBe("#chat");
+      expect(parsed.windowKey).toBe("myWidget");
+      expect(parsed.config).toBeTruthy();
+    });
+
+    it("escapes single quotes in the selector so it can't break the literal", () => {
+      const code = fromSubpath(config, "react-component", { target: "[data-x='y']" });
+      expect(code).toContain("target: '[data-x=\\'y\\']'");
+    });
+  });
 });

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

@@ -206,6 +206,7 @@ export type RuntypeAgentSSEEvent = {
   iteration: number;
   reflection?: string;
   seq: number;
+  timestamp?: string;
   type: "agent_reflection";
 } | {
   activatedCapabilities: Array<string>;
@@ -213,6 +214,7 @@ export type RuntypeAgentSSEEvent = {
   iteration: number;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_loaded";
 } | ({
@@ -222,6 +224,7 @@ export type RuntypeAgentSSEEvent = {
   proposalId?: string;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_proposed";
 }) | ({
@@ -255,6 +258,7 @@ export type RuntypeAgentSSEEvent = {
   iteration?: number;
   recoverable: boolean;
   seq: number;
+  timestamp?: string;
   type: "agent_error";
 } | {
   executionId: string;
@@ -289,6 +293,7 @@ export type RuntypeFlowSSEEvent = {
   failedSteps?: number;
   finalOutput?: string;
   flowId?: string;
+  flowName?: string;
   output?: unknown;
   seq?: number;
   source?: string;
@@ -340,6 +345,7 @@ export type RuntypeFlowSSEEvent = {
   id?: string;
   index?: number;
   name?: string;
+  outputVariable?: string;
   seq?: number;
   startedAt: string;
   stepId?: string;
@@ -751,6 +757,7 @@ export type RuntypeDispatchSSEEvent = {
   iteration: number;
   reflection?: string;
   seq: number;
+  timestamp?: string;
   type: "agent_reflection";
 } | {
   activatedCapabilities: Array<string>;
@@ -758,6 +765,7 @@ export type RuntypeDispatchSSEEvent = {
   iteration: number;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_loaded";
 } | ({
@@ -767,6 +775,7 @@ export type RuntypeDispatchSSEEvent = {
   proposalId?: string;
   seq: number;
   skill: string;
+  timestamp?: string;
   toolCallId: string;
   type: "agent_skill_proposed";
 }) | ({
@@ -800,6 +809,7 @@ export type RuntypeDispatchSSEEvent = {
   iteration?: number;
   recoverable: boolean;
   seq: number;
+  timestamp?: string;
   type: "agent_error";
 } | {
   executionId: string;
@@ -832,6 +842,7 @@ export type RuntypeDispatchSSEEvent = {
   failedSteps?: number;
   finalOutput?: string;
   flowId?: string;
+  flowName?: string;
   output?: unknown;
   seq?: number;
   source?: string;
@@ -883,6 +894,7 @@ export type RuntypeDispatchSSEEvent = {
   id?: string;
   index?: number;
   name?: string;
+  outputVariable?: string;
   seq?: number;
   startedAt: string;
   stepId?: string;

package/src/session.ts

@@ -76,6 +76,20 @@ function buildDispatchErrorContent(
   return err.message ? `${base}\n\n_Details: ${err.message}_` : base;
 }
 
+const buildWebMcpErrorResult = (message: string) => ({
+  isError: true,
+  content: [{ type: "text" as const, text: message }],
+});
+
+const getWebMcpErrorMessage = (
+  error: unknown,
+  fallback = "WebMCP tool execution failed.",
+): string => {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === "string" && error) return error;
+  return fallback;
+};
+
 export class AgentWidgetSession {
   private client: AgentWidgetClient;
   private messages: AgentWidgetMessage[];
@@ -1595,6 +1609,78 @@ export class AgentWidgetSession {
     }
   }
 
+  private resolveWebMcpToolStartedAt(
+    toolMessage: AgentWidgetMessage,
+  ): number {
+    const stored = this.messages.find((m) => m.id === toolMessage.id);
+    const candidates = [
+      stored?.toolCall?.startedAt,
+      toolMessage.toolCall?.startedAt,
+    ];
+    for (const candidate of candidates) {
+      if (typeof candidate === "number" && Number.isFinite(candidate)) {
+        return candidate;
+      }
+    }
+    return Date.now();
+  }
+
+  private markWebMcpToolRunning(
+    toolMessage: AgentWidgetMessage,
+  ): number {
+    const startedAt = this.resolveWebMcpToolStartedAt(toolMessage);
+    this.upsertMessage({
+      ...toolMessage,
+      streaming: true,
+      agentMetadata: {
+        ...toolMessage.agentMetadata,
+        awaitingLocalTool: false,
+      },
+      toolCall: toolMessage.toolCall
+        ? {
+            ...toolMessage.toolCall,
+            status: "running",
+            startedAt,
+            completedAt: undefined,
+            duration: undefined,
+            durationMs: undefined,
+          }
+        : toolMessage.toolCall,
+    });
+    return startedAt;
+  }
+
+  private markWebMcpToolComplete(
+    toolMessage: AgentWidgetMessage,
+    result: unknown,
+    startedAt: number,
+    completedAt = Date.now(),
+  ): void {
+    // A teardown such as clearMessages()/hydrateMessages()/new send can remove
+    // the bubble while an aborted WebMCP promise is settling. Never resurrect a
+    // cleared message just to mark the old resolve complete.
+    if (!this.messages.some((message) => message.id === toolMessage.id)) return;
+    this.upsertMessage({
+      ...toolMessage,
+      streaming: false,
+      agentMetadata: {
+        ...toolMessage.agentMetadata,
+        awaitingLocalTool: false,
+      },
+      toolCall: toolMessage.toolCall
+        ? {
+            ...toolMessage.toolCall,
+            status: "complete",
+            result,
+            startedAt,
+            completedAt,
+            duration: undefined,
+            durationMs: Math.max(0, completedAt - startedAt),
+          }
+        : toolMessage.toolCall,
+    });
+  }
+
   /**
    * Resolve TWO OR MORE parallel local-tool awaits sharing one paused
    * executionId with a SINGLE `/resume` (core#3878). Each call is executed
@@ -1613,6 +1699,14 @@ export class AgentWidgetSession {
     executionId: string,
     snapshots: AgentWidgetMessage[],
   ): Promise<void> {
+    type ExecutedWebMcpTool = {
+      dedupeKey: string;
+      resumeKey: string;
+      output: unknown;
+      toolMessage: AgentWidgetMessage;
+      startedAt: number;
+      completedAt: number;
+    };
     const claimedKeys: string[] = [];
     const controllers: AbortController[] = [];
     // Dedicated controller for the shared resume fetch so cancel() can abort it
@@ -1640,14 +1734,10 @@ export class AgentWidgetSession {
         this.webMcpInflightKeys.add(dedupeKey);
         claimedKeys.push(dedupeKey);
 
-        // Clear the awaiting flag so the local-tool UI doesn't linger.
-        this.upsertMessage({
-          ...toolMessage,
-          agentMetadata: {
-            ...toolMessage.agentMetadata,
-            awaitingLocalTool: false,
-          },
-        });
+        // Clear the awaiting flag and keep the tool bubble running while the
+        // browser-side WebMCP promise is in flight. The initial `step_await`
+        // 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);
@@ -1686,24 +1776,43 @@ export class AgentWidgetSession {
                 error instanceof Error ? error : new Error(String(error)),
               );
             }
+            this.markWebMcpToolComplete(
+              toolMessage,
+              buildWebMcpErrorResult(
+                isAbortError
+                  ? "Aborted by cancel()"
+                  : getWebMcpErrorMessage(error),
+              ),
+              startedAt,
+            );
             // Release the dedupe claim so a re-emit can retry this call.
             this.webMcpInflightKeys.delete(dedupeKey);
             return null;
           }
         }
         if (controller.signal.aborted) {
+          this.markWebMcpToolComplete(
+            toolMessage,
+            buildWebMcpErrorResult("Aborted by cancel()"),
+            startedAt,
+          );
           this.webMcpInflightKeys.delete(dedupeKey);
           return null;
         }
-        return { dedupeKey, resumeKey, output };
+        return {
+          dedupeKey,
+          resumeKey,
+          output,
+          toolMessage,
+          startedAt,
+          completedAt: Date.now(),
+        };
       }),
     );
 
+    let ready: ExecutedWebMcpTool[] = [];
     try {
-      const ready = executed.filter(
-        (r): r is { dedupeKey: string; resumeKey: string; output: unknown } =>
-          r !== null,
-      );
+      ready = executed.filter((r): r is ExecutedWebMcpTool => r !== null);
       // Everything deduped/aborted/failed — nothing to post.
       if (ready.length === 0) return;
 
@@ -1723,9 +1832,17 @@ export class AgentWidgetSession {
         throw new Error(errorData?.error ?? `Resume failed: ${response.status}`);
       }
       // Server accepted the batch — mark every included call resolved so stale
-      // re-emits don't re-execute the page tool.
+      // re-emits don't re-execute the page tool, then complete each bubble.
+      // Do this only after /resume HTTP success; if /resume fails, the server
+      // may still be paused and the retry path must not show a final result.
       for (const r of ready) {
         this.webMcpResolvedKeys.add(r.dedupeKey);
+        this.markWebMcpToolComplete(
+          r.toolMessage,
+          r.output,
+          r.startedAt,
+          r.completedAt,
+        );
       }
       if (response.body) {
         await this.connectStream(response.body, { allowReentry: true });
@@ -1740,6 +1857,14 @@ export class AgentWidgetSession {
         this.callbacks.onError?.(
           error instanceof Error ? error : new Error(String(error)),
         );
+      } else {
+        for (const r of ready) {
+          this.markWebMcpToolComplete(
+            r.toolMessage,
+            buildWebMcpErrorResult("Aborted by cancel()"),
+            r.startedAt,
+          );
+        }
       }
     } finally {
       for (const key of claimedKeys) {
@@ -1842,14 +1967,10 @@ export class AgentWidgetSession {
 
     // Mark resolved on the message so the UI's local-tool sheet (if any
     // generic one ever lands) does not show — this is a fully-automatic
-    // tool from the user's perspective, modulo the confirm bubble.
-    this.upsertMessage({
-      ...toolMessage,
-      agentMetadata: {
-        ...toolMessage.agentMetadata,
-        awaitingLocalTool: false,
-      },
-    });
+    // tool from the user's perspective, modulo the confirm bubble. Keep the
+    // tool bubble running until the browser-side promise resolves; the
+    // initial step_await was only the server pause, not tool completion.
+    const startedAt = this.markWebMcpToolRunning(toolMessage);
 
     // Per-resolve AbortController, NOT the shared `this.abortController`.
     // A single turn can produce multiple `webmcp:*` step_await messages —
@@ -1877,6 +1998,8 @@ export class AgentWidgetSession {
       signal,
     );
 
+    let phase: "execute" | "resume" = "execute";
+    let completedAt = startedAt;
     try {
       let resumeOutput: unknown;
       if (!execPromise) {
@@ -1891,6 +2014,7 @@ export class AgentWidgetSession {
       } else {
         resumeOutput = await execPromise;
       }
+      completedAt = Date.now();
       // If cancel() fired during execute, the bridge returned an aborted
       // result — don't post it. The server's SSE has been torn down; a
       // /resume now would just produce an orphan dispatch on the server.
@@ -1898,6 +2022,11 @@ export class AgentWidgetSession {
       // the resolve set) so we don't clobber a sibling resolve or a live
       // dispatch's controller here.
       if (signal.aborted) {
+        this.markWebMcpToolComplete(
+          toolMessage,
+          buildWebMcpErrorResult("Aborted by cancel()"),
+          startedAt,
+        );
         return;
       }
       // Mark resolved as soon as the HTTP /resume returns OK — not after the
@@ -1913,9 +2042,16 @@ export class AgentWidgetSession {
       // call (only same-tool PARALLEL calls could collide on the name).
       const resumeKey =
         toolMessage.agentMetadata?.webMcpToolCallId ?? wireToolName;
+      phase = "resume";
       await this.resumeWithToolOutput(executionId, resumeKey, resumeOutput, {
         onHttpOk: () => {
           this.webMcpResolvedKeys.add(dedupeKey);
+          this.markWebMcpToolComplete(
+            toolMessage,
+            resumeOutput,
+            startedAt,
+            completedAt,
+          );
         },
         signal,
       });
@@ -1928,6 +2064,17 @@ export class AgentWidgetSession {
       // Streaming/teardown handled by the shared `finally` (gated on the
       // resolve set) — do NOT null the shared `this.abortController` here; it
       // may belong to a live dispatch or sibling resolve, not to us.
+      if (phase === "execute" || isAbortError || signal.aborted) {
+        this.markWebMcpToolComplete(
+          toolMessage,
+          buildWebMcpErrorResult(
+            isAbortError || signal.aborted
+              ? "Aborted by cancel()"
+              : getWebMcpErrorMessage(error),
+          ),
+          startedAt,
+        );
+      }
       if (!isAbortError) {
         // The bridge normalizes tool errors into result objects, so reaching
         // here means a network failure during `/resume` itself, OR a stream
@@ -2504,9 +2651,11 @@ export class AgentWidgetSession {
       // 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
-      // local tool" UI. resolveWebMcpToolCall's dedupe path returns without
-      // re-touching the message, so correct the merge here (also avoids a
-      // one-frame flash before that microtask runs).
+      // 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
+      // without re-touching the message, so correct the merge here (also avoids
+      // a one-frame flash before that microtask runs).
       const reTcName = withSequence.toolCall?.name;
       const reExecId = withSequence.agentMetadata?.executionId;
       const reTcId = withSequence.toolCall?.id;
@@ -2518,14 +2667,26 @@ export class AgentWidgetSession {
         withSequence.agentMetadata?.awaitingLocalTool === true
       ) {
         const reKey = `${reExecId}:${reTcId}`;
-        if (
-          this.webMcpInflightKeys.has(reKey) ||
-          this.webMcpResolvedKeys.has(reKey)
-        ) {
+        const isInflight = this.webMcpInflightKeys.has(reKey);
+        const isResolved = this.webMcpResolvedKeys.has(reKey);
+        const existingToolName = existing.toolCall?.name;
+        const hasCompletedTool =
+          existing.agentMetadata?.executionId === reExecId &&
+          existing.toolCall?.id === reTcId &&
+          existingToolName !== undefined &&
+          isWebMcpToolName(existingToolName) &&
+          existing.toolCall?.status === "complete";
+        if (isInflight || isResolved || hasCompletedTool) {
           merged.agentMetadata = {
             ...(merged.agentMetadata ?? {}),
             awaitingLocalTool: false,
           };
+          // Preserve the in-flight/completed tool state. For in-flight calls,
+          // this keeps the original `startedAt`; for completed calls, it keeps
+          // the measured duration/result even when the call completed with a
+          // local/browser error and therefore was not promoted to resolved.
+          merged.toolCall = existing.toolCall;
+          merged.streaming = existing.streaming;
         }
       }
       return merged;