@runtypelabs/persona 3.29.0 → 3.30.0

package/src/session.webmcp.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
 import { AgentWidgetSession } from "./session";
 import type {
@@ -80,6 +80,10 @@ describe("AgentWidgetSession — WebMCP resolve", () => {
     vi.clearAllMocks();
   });
 
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   it("posts result to /resume on the happy path", async () => {
     const { session, executeSpy, resumeSpy } = makeSession({
       executeReturn: {
@@ -97,6 +101,33 @@ describe("AgentWidgetSession — WebMCP resolve", () => {
     );
   });
 
+  it("records the elapsed time of the resolved browser WebMCP promise", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    const { session } = makeSession({
+      executeImpl: async () => {
+        vi.advanceTimersByTime(1_250);
+        return { content: [{ type: "text", text: "loaded jade" }] };
+      },
+    });
+
+    await session.resolveWebMcpToolCall(
+      awaitingMessage("tool-1", "webmcp:get_product_by_url"),
+    );
+
+    const stored = (
+      session as unknown as { messages: AgentWidgetMessage[] }
+    ).messages.find((m) => m.toolCall?.id === "tool-1");
+    expect(stored?.agentMetadata?.awaitingLocalTool).toBe(false);
+    expect(stored?.toolCall?.status).toBe("complete");
+    expect(stored?.toolCall?.startedAt).toBe(1_000);
+    expect(stored?.toolCall?.completedAt).toBe(2_250);
+    expect(stored?.toolCall?.durationMs).toBe(1_250);
+    expect(stored?.toolCall?.result).toEqual({
+      content: [{ type: "text", text: "loaded jade" }],
+    });
+  });
+
   it("still resumes (with isError) when the bridge is not operational", async () => {
     // BugBot finding #1: previously, handleEvent skipped resolveWebMcpToolCall
     // entirely when `isWebMcpOperational()` was false — leaving the dispatch
@@ -152,6 +183,13 @@ describe("AgentWidgetSession — WebMCP resolve", () => {
 
     const msg = awaitingMessage("tool-1", "webmcp:search");
     await session.resolveWebMcpToolCall(msg);
+    const afterFailedResume = (
+      session as unknown as { messages: AgentWidgetMessage[] }
+    ).messages.find((m) => m.toolCall?.id === "tool-1");
+    expect(afterFailedResume?.toolCall?.status).toBe("running");
+    expect(afterFailedResume?.toolCall?.result).toBeUndefined();
+    expect(afterFailedResume?.toolCall?.durationMs).toBeUndefined();
+
     await session.resolveWebMcpToolCall(msg); // retry — must be allowed
     await session.resolveWebMcpToolCall(msg); // post-success — must be blocked
 
@@ -159,6 +197,29 @@ describe("AgentWidgetSession — WebMCP resolve", () => {
     expect(resumeSpy).toHaveBeenCalledTimes(2);
   });
 
+  it("marks the bubble complete with an error when browser execution throws before /resume", async () => {
+    const { session, resumeSpy } = makeSession({
+      executeImpl: async () => {
+        throw new Error("page tool exploded");
+      },
+    });
+
+    await session.resolveWebMcpToolCall(
+      awaitingMessage("tool-1", "webmcp:search"),
+    );
+
+    const stored = (
+      session as unknown as { messages: AgentWidgetMessage[] }
+    ).messages.find((m) => m.toolCall?.id === "tool-1");
+    expect(resumeSpy).not.toHaveBeenCalled();
+    expect(stored?.toolCall?.status).toBe("complete");
+    expect(stored?.toolCall?.durationMs).toBeGreaterThanOrEqual(0);
+    expect(stored?.toolCall?.result).toMatchObject({
+      isError: true,
+      content: [{ type: "text", text: "page tool exploded" }],
+    });
+  });
+
   it("threads an AbortSignal into resumeFlow", async () => {
     // BugBot finding #6: cancel() needs to propagate into /resume.
     const { session, resumeSpy } = makeSession();
@@ -189,6 +250,14 @@ describe("AgentWidgetSession — WebMCP resolve", () => {
     release();
     await inflight;
     expect(resumeSpy).not.toHaveBeenCalled();
+    const stored = (
+      session as unknown as { messages: AgentWidgetMessage[] }
+    ).messages.find((m) => m.toolCall?.id === "tool-1");
+    expect(stored?.toolCall?.status).toBe("complete");
+    expect(stored?.toolCall?.result).toMatchObject({
+      isError: true,
+      content: [{ type: "text", text: "Aborted by cancel()" }],
+    });
   });
 
   it("does NOT abort the shared session abortController", async () => {
@@ -282,11 +351,12 @@ describe("AgentWidgetSession — WebMCP resolve", () => {
     expect(executeSpy).not.toHaveBeenCalled();
   });
 
-  it("a stale step_await re-emit does not resurrect awaitingLocalTool once resolved", () => {
+  it("a stale step_await re-emit does not resurrect awaitingLocalTool or reset completed tool state once resolved", () => {
     // BugBot: a duplicate step_await (awaitingLocalTool:true) for an
     // already-resolved webmcp tool must not flip the message back to awaiting
-    // and show a stuck local-tool wait. upsertMessage clears it when the
-    // tool's `${executionId}:${toolCallId}` key is inflight/resolved.
+    // or running and show a stuck local-tool wait / lose the measured duration.
+    // upsertMessage clears it when the tool's `${executionId}:${toolCallId}`
+    // key is inflight/resolved.
     const session = makeSession().session;
     const s = session as unknown as {
       webMcpResolvedKeys: Set<string>;
@@ -298,11 +368,182 @@ describe("AgentWidgetSession — WebMCP resolve", () => {
     s.upsertMessage({
       ...awaitingMessage("tool-1", "webmcp:search"),
       agentMetadata: { executionId: "exec-1", awaitingLocalTool: false },
+      streaming: false,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "complete",
+        args: { q: "shoes" },
+        result: { content: [{ type: "text", text: "ok" }] },
+        startedAt: 1_000,
+        completedAt: 2_200,
+        durationMs: 1_200,
+      },
+    });
+    // Stale re-emit flips awaiting back to true and carries the running state
+    // emitted by client.ts for WebMCP step_await events.
+    s.upsertMessage({
+      ...awaitingMessage("tool-1", "webmcp:search"),
+      streaming: false,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "running",
+        args: { q: "shoes" },
+        startedAt: 3_000,
+      },
+    });
+    const stored = s.messages.find((m) => m.toolCall?.id === "tool-1");
+    expect(stored?.agentMetadata?.awaitingLocalTool).toBe(false);
+    expect(stored?.streaming).toBe(false);
+    expect(stored?.toolCall?.status).toBe("complete");
+    expect(stored?.toolCall?.result).toEqual({
+      content: [{ type: "text", text: "ok" }],
+    });
+    expect(stored?.toolCall?.startedAt).toBe(1_000);
+    expect(stored?.toolCall?.completedAt).toBe(2_200);
+    expect(stored?.toolCall?.durationMs).toBe(1_200);
+  });
+
+  it("a stale step_await re-emit does not reset in-flight WebMCP tool timing", () => {
+    const session = makeSession().session;
+    const s = session as unknown as {
+      webMcpInflightKeys: Set<string>;
+      upsertMessage: (m: AgentWidgetMessage) => void;
+      messages: AgentWidgetMessage[];
+    };
+    s.webMcpInflightKeys.add("exec-1:tool-1");
+    s.upsertMessage({
+      ...awaitingMessage("tool-1", "webmcp:search"),
+      agentMetadata: { executionId: "exec-1", awaitingLocalTool: false },
+      streaming: true,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "running",
+        args: { q: "shoes" },
+        startedAt: 1_000,
+      },
+    });
+
+    s.upsertMessage({
+      ...awaitingMessage("tool-1", "webmcp:search"),
+      streaming: false,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "running",
+        args: { q: "shoes" },
+        startedAt: 3_000,
+      },
     });
-    // Stale re-emit flips awaiting back to true on the wire.
-    s.upsertMessage(awaitingMessage("tool-1", "webmcp:search"));
+
     const stored = s.messages.find((m) => m.toolCall?.id === "tool-1");
     expect(stored?.agentMetadata?.awaitingLocalTool).toBe(false);
+    expect(stored?.streaming).toBe(true);
+    expect(stored?.toolCall?.status).toBe("running");
+    expect(stored?.toolCall?.startedAt).toBe(1_000);
+    expect(stored?.toolCall?.durationMs).toBeUndefined();
+  });
+
+  it("a stale step_await re-emit does not reset completed WebMCP local-error state", () => {
+    const session = makeSession().session;
+    const s = session as unknown as {
+      upsertMessage: (m: AgentWidgetMessage) => void;
+      messages: AgentWidgetMessage[];
+    };
+    s.upsertMessage({
+      ...awaitingMessage("tool-1", "webmcp:search"),
+      agentMetadata: { executionId: "exec-1", awaitingLocalTool: false },
+      streaming: false,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "complete",
+        args: { q: "shoes" },
+        result: {
+          isError: true,
+          content: [{ type: "text", text: "page tool exploded" }],
+        },
+        startedAt: 1_000,
+        completedAt: 1_500,
+        durationMs: 500,
+      },
+    });
+
+    s.upsertMessage({
+      ...awaitingMessage("tool-1", "webmcp:search"),
+      streaming: false,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "running",
+        args: { q: "shoes" },
+        startedAt: 3_000,
+      },
+    });
+
+    const stored = s.messages.find((m) => m.toolCall?.id === "tool-1");
+    expect(stored?.agentMetadata?.awaitingLocalTool).toBe(false);
+    expect(stored?.streaming).toBe(false);
+    expect(stored?.toolCall?.status).toBe("complete");
+    expect(stored?.toolCall?.result).toEqual({
+      isError: true,
+      content: [{ type: "text", text: "page tool exploded" }],
+    });
+    expect(stored?.toolCall?.startedAt).toBe(1_000);
+    expect(stored?.toolCall?.completedAt).toBe(1_500);
+    expect(stored?.toolCall?.durationMs).toBe(500);
+  });
+
+  it("a new execution reusing a completed tool id is not treated as stale", () => {
+    const session = makeSession().session;
+    const s = session as unknown as {
+      upsertMessage: (m: AgentWidgetMessage) => void;
+      messages: AgentWidgetMessage[];
+    };
+    s.upsertMessage({
+      ...awaitingMessage("tool-1", "webmcp:search"),
+      id: "tool-tool-1",
+      agentMetadata: { executionId: "exec-1", awaitingLocalTool: false },
+      streaming: false,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "complete",
+        args: { q: "shoes" },
+        result: {
+          isError: true,
+          content: [{ type: "text", text: "page tool exploded" }],
+        },
+        startedAt: 1_000,
+        completedAt: 1_500,
+        durationMs: 500,
+      },
+    });
+
+    s.upsertMessage({
+      ...awaitingMessage("tool-1", "webmcp:search", "exec-2"),
+      id: "tool-tool-1",
+      streaming: false,
+      toolCall: {
+        id: "tool-1",
+        name: "webmcp:search",
+        status: "running",
+        args: { q: "boots" },
+        startedAt: 3_000,
+      },
+    });
+
+    const stored = s.messages.find((m) => m.id === "tool-tool-1");
+    expect(stored?.agentMetadata?.executionId).toBe("exec-2");
+    expect(stored?.agentMetadata?.awaitingLocalTool).toBe(true);
+    expect(stored?.toolCall?.status).toBe("running");
+    expect(stored?.toolCall?.args).toEqual({ q: "boots" });
+    expect(stored?.toolCall?.startedAt).toBe(3_000);
+    expect(stored?.toolCall?.result).toBeUndefined();
+    expect(stored?.toolCall?.completedAt).toBeUndefined();
+    expect(stored?.toolCall?.durationMs).toBeUndefined();
   });
 
   it("an error event does not clear streaming while a webmcp resolve is in flight", () => {
@@ -576,6 +817,10 @@ describe("AgentWidgetSession — WebMCP parallel batched resume (core#3878)", ()
     vi.clearAllMocks();
   });
 
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   // A `step_await(local_tool_required)` message as client.ts emits it for a
   // PARALLEL local-tool call: the per-call `toolCallId` is both the toolCall.id
   // AND `agentMetadata.webMcpToolCallId`. Two of these for one executionId share
@@ -705,6 +950,81 @@ describe("AgentWidgetSession — WebMCP parallel batched resume (core#3878)", ()
     expect(Object.keys(toolOutputs).sort()).toEqual(["toolu_A", "toolu_B"]);
   });
 
+  it("records elapsed time for each resolved tool in a batched WebMCP resume", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+
+    let releaseA: (r: WebMcpToolResult) => void = () => undefined;
+    let releaseB: (r: WebMcpToolResult) => void = () => undefined;
+    const pA = new Promise<WebMcpToolResult>((r) => (releaseA = r));
+    const pB = new Promise<WebMcpToolResult>((r) => (releaseB = r));
+    const { session, resumeSpy } = makeSession();
+    const client = (session as unknown as { client: Record<string, unknown> })
+      .client;
+    (client.executeWebMcpToolCall as ReturnType<typeof vi.fn>).mockImplementation(
+      (_name: string, args: { sku: string }) =>
+        args.sku === "SHOE-001" ? pA : pB,
+    );
+
+    feed(session, parallelAwait("toolu_A", "SHOE-001"));
+    feed(session, parallelAwait("toolu_B", "SHOE-007"));
+    endStream(session);
+    await flushMicrotasks();
+
+    vi.setSystemTime(1_800);
+    releaseA({ content: [{ type: "text", text: "a" }] });
+    await flushMicrotasks();
+
+    let messages = (session as unknown as { messages: AgentWidgetMessage[] })
+      .messages;
+    const toolA = messages.find((m) => m.toolCall?.id === "toolu_A");
+    const toolBWhileRunning = messages.find((m) => m.toolCall?.id === "toolu_B");
+    expect(toolA?.toolCall?.status).toBe("running");
+    expect(toolA?.toolCall?.durationMs).toBeUndefined();
+    expect(toolBWhileRunning?.toolCall?.status).toBe("running");
+    expect(resumeSpy).not.toHaveBeenCalled();
+
+    vi.setSystemTime(2_600);
+    releaseB({ content: [{ type: "text", text: "b" }] });
+    await flushMicrotasks();
+
+    messages = (session as unknown as { messages: AgentWidgetMessage[] })
+      .messages;
+    const completedToolA = messages.find((m) => m.toolCall?.id === "toolu_A");
+    const toolB = messages.find((m) => m.toolCall?.id === "toolu_B");
+    expect(completedToolA?.toolCall?.status).toBe("complete");
+    expect(completedToolA?.toolCall?.durationMs).toBe(800);
+    expect(toolB?.toolCall?.status).toBe("complete");
+    expect(toolB?.toolCall?.durationMs).toBe(1_600);
+    expect(resumeSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not mark batched WebMCP bubbles complete when the shared /resume fails", async () => {
+    const { session, client, resumeSpy } = makeSession();
+    (client.resumeFlow as ReturnType<typeof vi.fn>).mockImplementationOnce(
+      async () => {
+        throw new Error("resume failed");
+      },
+    );
+
+    feed(session, parallelAwait("toolu_A", "SHOE-001"));
+    feed(session, parallelAwait("toolu_B", "SHOE-007"));
+    endStream(session);
+    await flushMicrotasks();
+
+    const messages = (session as unknown as { messages: AgentWidgetMessage[] })
+      .messages;
+    const toolA = messages.find((m) => m.toolCall?.id === "toolu_A");
+    const toolB = messages.find((m) => m.toolCall?.id === "toolu_B");
+    expect(resumeSpy).toHaveBeenCalledTimes(1);
+    expect(toolA?.toolCall?.status).toBe("running");
+    expect(toolA?.toolCall?.result).toBeUndefined();
+    expect(toolA?.toolCall?.durationMs).toBeUndefined();
+    expect(toolB?.toolCall?.status).toBe("running");
+    expect(toolB?.toolCall?.result).toBeUndefined();
+    expect(toolB?.toolCall?.durationMs).toBeUndefined();
+  });
+
   it("dedupes a duplicate parallel await within the same batch", async () => {
     const { session, executeSpy, resumeSpy } = makeSession();
     feed(session, parallelAwait("toolu_A", "SHOE-001"));

package/src/theme-editor/preview-utils.test.ts

@@ -49,6 +49,16 @@ describe("theme editor preview demo data", () => {
     expect(reasoningMessage.reasoning?.status).toBe("streaming");
   });
 
+  it("creates a pending approval preview entry for theming the approval bubble", () => {
+    const message = createPreviewTranscriptEntry("approval-request", 3);
+
+    expect(message.variant).toBe("approval");
+    expect(message.approval?.status).toBe("pending");
+    expect(message.approval?.toolName).toBe("add_to_cart");
+    // Includes parameters so the params block is exercised when theming.
+    expect(message.approval?.parameters).toBeTruthy();
+  });
+
   it("appends public preview transcript entries to an existing conversation", () => {
     const messages = appendPreviewTranscriptEntry([], "tool-running");
     const updated = appendPreviewTranscriptEntry(messages, "reasoning-complete");

package/src/theme-editor/preview-utils.ts

@@ -206,7 +206,8 @@ export type PreviewTranscriptEntryPreset =
   | 'reasoning-streaming'
   | 'reasoning-complete'
   | 'tool-running'
-  | 'tool-complete';
+  | 'tool-complete'
+  | 'approval-request';
 
 const PREVIEW_TRANSCRIPT_PRESET_LABELS: Record<PreviewTranscriptEntryPreset, string> = {
   'user-message': 'User message',
@@ -218,6 +219,7 @@ const PREVIEW_TRANSCRIPT_PRESET_LABELS: Record<PreviewTranscriptEntryPreset, str
   'reasoning-complete': 'Reasoning (complete)',
   'tool-running': 'Tool call (running)',
   'tool-complete': 'Tool call (complete)',
+  'approval-request': 'Approval request',
 };
 
 export function getPreviewTranscriptPresetLabel(preset: PreviewTranscriptEntryPreset): string {
@@ -325,6 +327,32 @@ export function createPreviewTranscriptEntry(
           durationMs: 1200,
         },
       };
+    case 'approval-request': {
+      // Use the `approval-<approvalId>` id convention so the optimistic status
+      // flip in `session.resolveApproval` updates this bubble in place when the
+      // Approve/Deny buttons are clicked.
+      const approvalId = `preview-approval-${suffix}`;
+      return {
+        id: `approval-${approvalId}`,
+        role: 'assistant',
+        content: '',
+        createdAt,
+        streaming: false,
+        variant: 'approval',
+        approval: {
+          id: approvalId,
+          status: 'pending',
+          agentId: 'preview-agent',
+          executionId: `preview-exec-${suffix}`,
+          toolName: 'add_to_cart',
+          description:
+            'Add the selected item to the shopping cart. Approve to let the assistant continue.',
+          parameters: {
+            items: [{ productEntityId: 129, quantity: 1 }],
+          },
+        },
+      };
+    }
     case 'tool-complete':
       return {
         id: `preview-seq-tool-complete-${suffix}`,

package/src/theme-editor/sections.test.ts

@@ -27,6 +27,23 @@ describe("theme editor scroll-to-bottom controls", () => {
     expect(fieldPaths).toContain("theme.components.scrollToBottom.iconSize");
   });
 
+  it("exposes a shadow control for every themeable component", () => {
+    const fieldPaths = COMPONENTS_SECTIONS.flatMap((section) => section.fields.map((field) => field.path));
+
+    // Pre-existing shadow controls.
+    expect(fieldPaths).toContain("theme.components.launcher.shadow");
+    expect(fieldPaths).toContain("theme.components.panel.shadow");
+    expect(fieldPaths).toContain("theme.components.scrollToBottom.shadow");
+    // Newly added component shadow controls.
+    expect(fieldPaths).toContain("theme.components.message.user.shadow");
+    expect(fieldPaths).toContain("theme.components.message.assistant.shadow");
+    expect(fieldPaths).toContain("theme.components.toolBubble.shadow");
+    expect(fieldPaths).toContain("theme.components.reasoningBubble.shadow");
+    expect(fieldPaths).toContain("theme.components.approval.requested.shadow");
+    expect(fieldPaths).toContain("theme.components.introCard.shadow");
+    expect(fieldPaths).toContain("theme.components.composer.shadow");
+  });
+
   it("adds a scroll-to-bottom interface role mapping", () => {
     const role = ALL_ROLES.find((entry) => entry.roleId === "role-scroll-to-bottom");
 

package/src/theme-editor/sections.ts

@@ -455,6 +455,36 @@ const scrollToBottomSectionDef: SectionDef = {
   ],
 };
 
+// Reusable shadow-scale options matching the launcher / panel / scroll-to-bottom selects.
+const SHADOW_SCALE_OPTIONS: { value: string; label: string }[] = [
+  { value: 'palette.shadows.none', label: 'None' },
+  { value: 'palette.shadows.sm', label: 'Small' },
+  { value: 'palette.shadows.md', label: 'Medium' },
+  { value: 'palette.shadows.lg', label: 'Large' },
+  { value: 'palette.shadows.xl', label: 'Extra Large' },
+];
+
+// The approval and intro-card defaults are a bespoke "card" shadow rather than a
+// palette step, so expose it as a leading "Default" option users can keep.
+const CARD_SHADOW = '0 5px 15px rgba(15, 23, 42, 0.08)';
+const CARD_SHADOW_OPTIONS = [{ value: CARD_SHADOW, label: 'Default' }, ...SHADOW_SCALE_OPTIONS];
+
+const componentShadowsSectionDef: SectionDef = {
+  id: 'comp-shadows',
+  title: 'Component Shadows',
+  description: 'Box-shadow for chat bubbles and surfaces.',
+  collapsed: true,
+  fields: [
+    { id: 'shadow-msg-user', label: 'User Message', type: 'select', path: 'theme.components.message.user.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-msg-assistant', label: 'Assistant Message', type: 'select', path: 'theme.components.message.assistant.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-tool-bubble', label: 'Tool Call Bubble', type: 'select', path: 'theme.components.toolBubble.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-reasoning-bubble', label: 'Reasoning Bubble', type: 'select', path: 'theme.components.reasoningBubble.shadow', defaultValue: 'palette.shadows.sm', options: SHADOW_SCALE_OPTIONS },
+    { id: 'shadow-approval', label: 'Approval Bubble', type: 'select', path: 'theme.components.approval.requested.shadow', defaultValue: CARD_SHADOW, options: CARD_SHADOW_OPTIONS },
+    { id: 'shadow-intro-card', label: 'Intro Card', type: 'select', path: 'theme.components.introCard.shadow', defaultValue: CARD_SHADOW, options: CARD_SHADOW_OPTIONS },
+    { id: 'shadow-composer', label: 'Composer', type: 'select', path: 'theme.components.composer.shadow', defaultValue: 'palette.shadows.none', options: SHADOW_SCALE_OPTIONS },
+  ],
+};
+
 /** Shared shape sections (not scoped to light/dark) */
 export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   panelLayoutSectionDef,
@@ -462,6 +492,7 @@ export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   messageShapeSectionDef,
   inputShapeSectionDef,
   buttonShapeSectionDef,
+  componentShadowsSectionDef,
 ];
 
 /** Component color sections (can be scoped for light/dark) */

package/src/theme-reference.ts

@@ -136,7 +136,7 @@ export const THEME_TOKEN_DOCS = {
       voice:
         'recording (indicator, background, border), processing (icon, background), speaking (icon).',
       approval:
-        'requested (background, border, text), approve (background, foreground), deny (background, foreground).',
+        'requested (background, border, text, shadow), approve (background, foreground), deny (background, foreground).',
       attachment: 'image (background, border).',
       scrollToBottom:
         'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',

package/src/types/theme.ts

@@ -330,6 +330,8 @@ export interface ApprovalTokens {
     background: TokenReference<'color'>;
     border: TokenReference<'color'>;
     text: TokenReference<'color'>;
+    /** Box-shadow for the approval bubble (token ref or raw CSS, e.g. `none`). */
+    shadow: string;
   };
   approve: ComponentTokenSet;
   deny: ComponentTokenSet;

package/src/types.ts

@@ -255,6 +255,12 @@ export type WebMcpConfirmInfo = {
   toolName: string;
   args: unknown;
   description?: string;
+  /**
+   * Display title the tool declared via the WebMCP spec's
+   * `ToolDescriptor.title` (e.g. `"Add to Cart"`). Absent when the tool
+   * didn't declare one.
+   */
+  title?: string;
   annotations?: {
     readOnlyHint?: boolean;
     untrustedContentHint?: boolean;
@@ -1816,6 +1822,23 @@ export interface VoiceProvider {
   stopPlayback?(): void;
 }
 
+/**
+ * Extra context for an approval decision, surfaced to `onDecision` and to the
+ * `approve`/`deny` callbacks passed to the `renderApproval` plugin hook.
+ */
+export type AgentWidgetApprovalDecisionOptions = {
+  /**
+   * The user chose a "remember this" affordance (e.g. an "Always allow"
+   * button) rather than a one-time decision. The widget resolves the *current*
+   * approval identically whether or not this is set — an approval bubble is a
+   * single binary gate (`approved`/`denied`). Persisting a don't-ask-again
+   * policy for *future* approvals (auto-resolving them, or not surfacing them)
+   * is the integrator's responsibility, typically inside `onDecision`.
+   * Defaults to absent/`false`.
+   */
+  remember?: boolean;
+};
+
 /**
  * Configuration for tool approval bubbles.
  * Controls styling, labels, and behavior of the approval UI.
@@ -1825,6 +1848,8 @@ export type AgentWidgetApprovalConfig = {
   backgroundColor?: string;
   /** Border color of the approval bubble */
   borderColor?: string;
+  /** Box-shadow for the approval bubble; pass `"none"` to remove it. Overrides the default `persona-shadow-sm`. */
+  shadow?: string;
   /** Color for the title text */
   titleColor?: string;
   /** Color for the description text */
@@ -1847,19 +1872,51 @@ export type AgentWidgetApprovalConfig = {
   approveLabel?: string;
   /** Label for the deny button */
   denyLabel?: string;
+  /**
+   * How the technical details (the tool's agent-facing description and the
+   * raw parameters JSON) are presented:
+   * - `"collapsed"` (default) — hidden behind a "Show details" toggle
+   * - `"expanded"` — visible, with the toggle available to hide them
+   * - `"hidden"` — never rendered
+   */
+  detailsDisplay?: "collapsed" | "expanded" | "hidden";
+  /** Label for the toggle that reveals the technical details */
+  showDetailsLabel?: string;
+  /** Label for the toggle that hides the technical details */
+  hideDetailsLabel?: string;
+  /**
+   * Build the user-facing summary line for an approval request. Overrides the
+   * default "The assistant wants to use “Tool name”." copy. Return a falsy
+   * value to fall back to the default for that approval. `displayTitle` is
+   * the display name the tool declared via the WebMCP spec's
+   * `ToolDescriptor.title`, when one exists.
+   */
+  formatDescription?: (approval: {
+    toolName: string;
+    toolType?: string;
+    description: string;
+    parameters?: unknown;
+    displayTitle?: string;
+  }) => string | undefined;
   /**
    * Custom handler for approval decisions.
    * Return void to let the SDK auto-resolve via the API,
    * or return a Response/ReadableStream for custom handling.
+   *
+   * `options.remember` is `true` when the decision came from a "remember this"
+   * affordance (e.g. an "Always allow" button in a custom `renderApproval`
+   * plugin). Use it to persist a don't-ask-again policy for future approvals;
+   * the current approval resolves the same way regardless.
    */
   onDecision?: (
     data: { approvalId: string; executionId: string; agentId: string; toolName: string },
-    decision: 'approved' | 'denied'
+    decision: 'approved' | 'denied',
+    options?: AgentWidgetApprovalDecisionOptions
   ) => Promise<Response | ReadableStream<Uint8Array> | void>;
 };
 
 export type AgentWidgetToolCallConfig = {
-  /** Box-shadow for tool-call bubbles; overrides `theme.toolBubbleShadow` when set. */
+  /** Box-shadow for tool-call bubbles; pass `"none"` to remove it. Overrides the `components.toolBubble.shadow` token / `--persona-tool-bubble-shadow`. */
   shadow?: string;
   /** Background color of the tool call bubble container. */
   backgroundColor?: string;