@runtypelabs/persona 4.23.2 → 4.25.0

package/src/client.ts

@@ -307,6 +307,14 @@ export class AgentWidgetClient {
   private currentClientTurnId: string | null = null;
   private clientSession: ClientSession | null = null;
   private sessionInitPromise: Promise<ClientSession> | null = null;
+  /**
+   * Early-init latch for `warmSession()`. `false` = armed. Otherwise it holds
+   * the session value (`null` or an expired session) the one early attempt was
+   * made against, so a failed attempt is not retried on every keystroke. It is
+   * re-armed when a session is installed or cleared, so each session lifetime
+   * gets one early init.
+   */
+  private sessionWarmLatch: ClientSession | null | false = false;
 
   // Diff-only / send-once WebMCP tool dispatch (client-token mode ONLY).
   // Fingerprint of the clientTools[] last *sent in full* and confirmed by a
@@ -621,9 +629,41 @@ export class AgentWidgetClient {
     }
   }
 
+  /**
+   * Fire-and-forget early `initSession()` for client-token mode, driven by the
+   * widget's `sessionInit` trigger (or a host calling it directly, e.g. on
+   * hover). It fires at most once per session lifetime and is a no-op while a
+   * session is live or an init is already in flight. Errors are swallowed, with
+   * no `onSessionExpired` and no UI: a send calls `initSession()` again and
+   * reuses the in-flight promise, so any failure resurfaces there exactly as it
+   * would without the early init. Sends nothing new on the wire. Outside
+   * client-token mode this does nothing.
+   *
+   * Resolves with the session this call initialized, or `null` when it was
+   * skipped or failed. It never rejects.
+   */
+  public async warmSession(): Promise<ClientSession | null> {
+    const current = this.clientSession;
+    if (
+      !this.isClientTokenMode() ||
+      this.sessionInitPromise ||
+      (current && new Date() < current.expiresAt) ||
+      this.sessionWarmLatch === current
+    ) {
+      return null;
+    }
+    this.sessionWarmLatch = current;
+    // Swallowed on purpose: the send's own initSession() reports failures.
+    return this.initSession().catch(() => null);
+  }
+
   /**
    * Initialize session for client token mode.
-   * Called automatically on first message if not already initialized.
+   * Called by the send if no live session exists. The widget normally calls
+   * it earlier, when the visitor shows intent to send (see the `sessionInit`
+   * config option and `warmSession()`), and concurrent calls share one
+   * in-flight request, so a send racing an early init issues a single
+   * `/v1/client/init`.
    */
   public async initSession(): Promise<ClientSession> {
     if (!this.isClientTokenMode()) {
@@ -640,21 +680,28 @@ export class AgentWidgetClient {
       return this.sessionInitPromise;
     }
 
-    this.sessionInitPromise = this._doInitSession();
-    try {
-      const session = await this.sessionInitPromise;
-      this.clientSession = session;
-      // A freshly-minted session must resend the full WebMCP tool list on its
-      // next turn: drop any diff-only fingerprint cached under a prior session,
-      // so we never claim "unchanged" against a session the server didn't store
-      // the set under. (Belt-and-suspenders with the sessionId comparison in the
-      // send decision and the server's 409 resend signal.)
-      this.resetClientToolsFingerprint();
-      this.config.onSessionInit?.(session);
-      return session;
-    } finally {
-      this.sessionInitPromise = null;
-    }
+    // Callers that dedupe share this promise, so the stale check below covers
+    // them too (the send reusing an early init included).
+    const pending: Promise<ClientSession> = (this.sessionInitPromise = this._doInitSession()
+      .then((session) => {
+        // A clear or replacement (credential change, start-new, proof re-init)
+        // while this was in flight makes the result stale: never install it.
+        if (this.sessionInitPromise !== pending) return this.initSession();
+        this.clientSession = session;
+        this.sessionWarmLatch = false;
+        // A freshly-minted session must resend the full WebMCP tool list on its
+        // next turn: drop any diff-only fingerprint cached under a prior session,
+        // so we never claim "unchanged" against a session the server didn't store
+        // the set under. (Belt-and-suspenders with the sessionId comparison in the
+        // send decision and the server's 409 resend signal.)
+        this.resetClientToolsFingerprint();
+        this.config.onSessionInit?.(session);
+        return session;
+      })
+      .finally(() => {
+        if (this.sessionInitPromise === pending) this.sessionInitPromise = null;
+      }));
+    return pending;
   }
 
   /** Visitor history rides on client-token init only, and latches off after a 403 degrade. */
@@ -966,6 +1013,7 @@ export class AgentWidgetClient {
     const installed = this.finishInit(session, previousConversationId, false);
     this.clientSession = installed;
     this.sessionInitPromise = null;
+    this.sessionWarmLatch = false;
     this.resetClientToolsFingerprint();
     return installed;
   }
@@ -1032,6 +1080,7 @@ export class AgentWidgetClient {
         if (settled) return;
         settled = true;
         this.clientSession = session;
+        this.sessionWarmLatch = false;
         this.resetClientToolsFingerprint();
       },
       discard: () => {
@@ -1102,6 +1151,7 @@ export class AgentWidgetClient {
   public clearClientSession(): void {
     this.clientSession = null;
     this.sessionInitPromise = null;
+    this.sessionWarmLatch = false;
     this.resetClientToolsFingerprint();
   }
 
@@ -1212,6 +1262,7 @@ export class AgentWidgetClient {
       
       if (response.status === 401) {
         this.clientSession = null;
+        this.sessionWarmLatch = false;
         this.config.onSessionExpired?.();
         throw new Error('Session expired. Please refresh to continue.');
       }
@@ -1231,10 +1282,9 @@ export class AgentWidgetClient {
     messageId: string, 
     type: 'upvote' | 'downvote' | 'copy'
   ): Promise<void> {
-    const session = this.getClientSession();
-    if (!session) {
-      throw new Error('No active session. Please initialize session first.');
-    }
+    // Feedback on a restored transcript can precede any init (`sessionInit`
+    // defers it to intent); the feedback click is intent enough.
+    const session = this.getClientSession() ?? (await this.initSession());
 
     return this.sendFeedback({
       sessionId: session.sessionId,
@@ -1251,10 +1301,7 @@ export class AgentWidgetClient {
    * @param comment - Optional comment
    */
   public async submitCSATFeedback(rating: number, comment?: string): Promise<void> {
-    const session = this.getClientSession();
-    if (!session) {
-      throw new Error('No active session. Please initialize session first.');
-    }
+    const session = this.getClientSession() ?? (await this.initSession());
 
     return this.sendFeedback({
       sessionId: session.sessionId,
@@ -1272,10 +1319,7 @@ export class AgentWidgetClient {
    * @param comment - Optional comment
    */
   public async submitNPSFeedback(rating: number, comment?: string): Promise<void> {
-    const session = this.getClientSession();
-    if (!session) {
-      throw new Error('No active session. Please initialize session first.');
-    }
+    const session = this.getClientSession() ?? (await this.initSession());
 
     return this.sendFeedback({
       sessionId: session.sessionId,
@@ -1311,6 +1355,40 @@ export class AgentWidgetClient {
     return this.config.getIdentityProof ? 'verified-user' : 'browser';
   }
 
+  private async resolveChatIdentityProof(signal?: AbortSignal): Promise<ClientChatRequest['identityProof']> {
+    signal?.throwIfAborted();
+    const provider = this.config.identityProvider;
+    if (provider === undefined) return undefined;
+    const getIdentityProof = this.config.getIdentityProof;
+    if (!provider.trim() || !getIdentityProof) {
+      throw new Error('Chat identity requires identityProvider and getIdentityProof.');
+    }
+    let token: string | null;
+    let onAbort: (() => void) | undefined;
+    try {
+      const proof = Promise.resolve().then(() => getIdentityProof());
+      token = signal
+        ? await Promise.race([
+            proof,
+            new Promise<never>((_, reject) => {
+              onAbort = () => reject(signal.reason);
+              signal.addEventListener('abort', onAbort, { once: true });
+              if (signal.aborted) onAbort();
+            }),
+          ])
+        : await proof;
+    } catch {
+      signal?.throwIfAborted();
+      throw new Error('The identity proof provider failed.');
+    } finally {
+      if (onAbort) signal?.removeEventListener('abort', onAbort);
+    }
+    if (typeof token !== 'string' || !token.trim()) {
+      throw new Error('A fresh identity proof is required to send this message.');
+    }
+    return { provider, token };
+  }
+
   /**
    * Resolve the proof for one logical request. `null` is an intentional
    * browser-scope fallback only while the visitor has never been bound.
@@ -1850,6 +1928,7 @@ export class AgentWidgetClient {
         }
         session = this.finishInit(renewed, previous.conversationId ?? null, false);
         this.clientSession = session;
+        this.sessionWarmLatch = false;
         this.resetClientToolsFingerprint();
         this.config.onSessionInit?.(session);
       };
@@ -1909,16 +1988,23 @@ export class AgentWidgetClient {
         const recoveryVisitorToken =
           session.durableRecovery?.enabled === true ? await this.readVisitorToken() : null;
         assertCurrentTurn();
-        return this.sendWithClientToolsDiff(session.sessionId, basePayload.clientTools, (toolFields) => {
+        return this.sendWithClientToolsDiff(session.sessionId, basePayload.clientTools, async (toolFields) => {
+          assertCurrentTurn();
+          const identityProof = await this.resolveChatIdentityProof(options.signal);
+          assertCurrentTurn();
           const chatRequest: ClientChatRequest = {
             ...baseChatRequest,
             sessionId: session.sessionId,
             ...toolFields,
+            ...(identityProof && { identityProof }),
           };
 
           if (this.debug) {
             // eslint-disable-next-line no-console
-            console.debug("[AgentWidgetClient] client token dispatch", chatRequest);
+            console.debug("[AgentWidgetClient] client token dispatch", {
+              ...chatRequest,
+              ...(identityProof && { identityProof: { provider: identityProof.provider, token: '[REDACTED]' } }),
+            });
           }
 
           return fetch(this.getClientApiUrl('chat'), {
@@ -1951,6 +2037,12 @@ export class AgentWidgetClient {
       if (!response.ok) {
         const data = await response.json().catch(() => ({ error: 'Chat request failed' }));
 
+        if (response.status === 401 && data.error === 'invalid_identity_proof') {
+          const error = new HistoryClientError('invalid_identity_proof', PROOF_REJECTED_MESSAGE);
+          forward({ type: 'error', error });
+          throw error;
+        }
+
         if (response.status === 401) {
           // Session expired
           this.clearClientSession();

package/src/codegen.test.ts

@@ -66,6 +66,30 @@ describe("codegen subpath", () => {
     });
   });
 
+  it("preserves an authored v5 defaults opt-in in every output format", () => {
+    const futureConfig = { ...config, future: { v5Defaults: true } };
+    for (const format of [
+      "esm",
+      "script-installer",
+      "script-manual",
+      "script-advanced",
+      "react-component",
+      "react-advanced",
+    ] as const) {
+      const code = fromSubpath(futureConfig, format);
+      expect(code).toContain("v5Defaults");
+      expect(code).toContain("true");
+    }
+
+    const installer = fromSubpath(futureConfig, "script-installer");
+    const payload = JSON.parse(installer.match(/data-config='([^']*)'/)![1]);
+    expect(payload.future).toEqual({ v5Defaults: true });
+
+    expect(
+      fromSubpath({ ...config, future: { v5Defaults: false } }, "esm")
+    ).toContain("future: { v5Defaults: false }");
+  });
+
   describe("mount target option", () => {
     it("defaults to body when no target is given", () => {
       expect(fromSubpath(config, "react-component")).toContain("target: 'body'");

package/src/components/activity-row.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { activityDuration, createActivityLifecycle } from './activity-row';
+import { createToolBubble } from './tool-bubble';
+import { createReasoningBubble } from './reasoning-bubble';
+import type { AgentWidgetMessage } from '../types';
+const message = (status: 'pending' | 'running' | 'complete' = 'running', chunks: string[] = []): AgentWidgetMessage => ({ id: 'tool', role: 'assistant', content: '', createdAt: '2026-01-01', variant: 'tool', toolCall: { id: 'tool', name: 'Search', status, chunks, durationMs: 65000 } });
+afterEach(() => vi.useRealTimers());
+describe.each([false, true])('activity rows (V5 %s)', v5Defaults => {
+  it('defaults to the selected variant and supports explicit overrides', () => {
+    const config = { future: { v5Defaults } };
+    expect(createToolBubble(message(), config).classList.contains('persona-activity-row')).toBe(v5Defaults);
+    for (const variant of ['card', 'row'] as const) {
+      const node = createToolBubble(message('complete'), { ...config, features: { toolCallDisplay: { variant } } });
+      expect(node.classList.contains('persona-activity-row')).toBe(variant === 'row');
+      if (variant === 'row') { expect(node.textContent).toContain('Used Search'); expect(node.textContent).toContain('1m 5s'); }
+    }
+  });
+  it('resolves icon visibility and removes the icon slot on successful completion', () => {
+    for (const kind of ['tool', 'reasoning'] as const) {
+      for (const mode of [undefined, 'always', 'active', 'never'] as const) {
+        const key = kind === 'tool' ? 'toolCallDisplay' : 'reasoningDisplay';
+        const config = { future: { v5Defaults }, features: { [key]: { variant: 'row' as const, iconVisibility: mode } } };
+        const m = message('complete');
+        const node = kind === 'tool' ? createToolBubble(m, config) : createReasoningBubble({ ...m, toolCall: undefined, variant: 'reasoning', reasoning: { id: 'r', status: 'complete', chunks: ['Details'] } }, config);
+        expect(!!node.querySelector('.persona-activity-icon')).toBe((mode ?? (v5Defaults ? 'active' : 'always')) === 'always');
+        expect(node.querySelector('.persona-activity-chevron')).not.toBeNull();
+      }
+    }
+  });
+  it('keeps attention and active indicators unless explicitly disabled', () => {
+    for (const status of ['pending', 'running', 'complete'] as const) {
+      const m = message(status); if (status === 'complete') m.toolCall!.success = false;
+      for (const iconVisibility of ['active', 'never'] as const) {
+        const node = createToolBubble(m, { future: { v5Defaults }, features: { toolCallDisplay: { variant: 'row', iconVisibility } } });
+        expect(!!node.querySelector('.persona-activity-icon')).toBe(iconVisibility === 'active');
+      }
+    }
+  });
+  it('keeps custom content and exposes accessible row controls', () => {
+    const node = createToolBubble(message(), { future: { v5Defaults }, features: { toolCallDisplay: { variant: 'row' } }, toolCall: { renderCollapsedSummary: () => 'Custom summary' } });
+    expect(node.textContent?.replace(/\u00a0/g, ' ')).toContain('Custom summary');
+    const button = node.querySelector('button')!;
+    expect(button.getAttribute('aria-expanded')).toBe('false');
+    expect(button.getAttribute('aria-controls')).toBe(node.querySelector('.persona-activity-body')?.id);
+    expect(Array.from(button.children).map(el => el.className)).toEqual(expect.arrayContaining(['persona-activity-icon']));
+    expect(button.children[1].classList.contains('persona-activity-label')).toBe(true);
+    expect(button.children[2].classList.contains('persona-activity-chevron')).toBe(true);
+  });
+  it('formats completed reasoning and retains card override', () => {
+    const m: AgentWidgetMessage = { ...message(), variant: 'reasoning', toolCall: undefined, reasoning: { id: 'r', status: 'complete', chunks: ['Details'], durationMs: 100 } };
+    const node = createReasoningBubble(m, { future: { v5Defaults }, features: { reasoningDisplay: { variant: 'row' } } });
+    expect(node.textContent).toContain('Thought for a moment');
+  });
+});
+it.each([['pending', 'pending'], ['running', 'running'], ['complete', 'done']] as const)('maps %s status to %s', (status, expected) => {
+  const node = createToolBubble(message(status), { features: { toolCallDisplay: { variant: 'row' } } });
+  expect(node.dataset.activityState).toBe(expected);
+  expect(node.querySelector('.persona-activity-icon svg')).not.toBeNull();
+});
+it('maps failure, denied, and approval-waiting icons', () => {
+  const m = message('complete'); m.toolCall!.success = false;
+  expect(createToolBubble(m, { future: { v5Defaults: true } }).dataset.activityState).toBe('error');
+  for (const status of ['denied', 'pending'] as const) {
+    m.approval = { id: 'a', status, agentId: 'a', executionId: 'e', toolName: 'Search', description: '' };
+    expect(createToolBubble(m, { future: { v5Defaults: true } }).dataset.activityState).toBe(status === 'denied' ? 'denied' : 'awaiting-approval');
+  }
+});
+it('formats short and multi-minute durations', () => {
+  expect([undefined, 200, 12000, 65000].map(activityDuration)).toEqual(['a moment', 'a moment', '12s', '1m 5s']);
+});
+describe('activity lifecycle', () => {
+  it('waits for a token and collapses exactly once after completion', () => {
+    vi.useFakeTimers(); const changed = vi.fn(); const lifecycle = createActivityLifecycle(changed); const expanded = new Set<string>();
+    lifecycle.observe(message(), 'tool', expanded); expect(expanded.size).toBe(0);
+    lifecycle.observe(message('running', ['token']), 'tool', expanded); expect(expanded.has('tool')).toBe(true);
+    lifecycle.observe(message('complete', ['token']), 'tool', expanded);
+    vi.advanceTimersByTime(999); expect(expanded.has('tool')).toBe(true);
+    vi.advanceTimersByTime(1); expect(expanded.size).toBe(0); expect(changed).toHaveBeenCalledTimes(1);
+    expanded.add('tool'); lifecycle.observe(message('complete', ['token']), 'tool', expanded); vi.advanceTimersByTime(2000); expect(expanded.has('tool')).toBe(true);
+  });
+  it('manual control cancels automatic collapse and expansion', () => {
+    vi.useFakeTimers(); const changed = vi.fn(); const lifecycle = createActivityLifecycle(changed); const expanded = new Set<string>();
+    lifecycle.observe(message('running', ['token']), 'tool', expanded);
+    lifecycle.observe(message('complete', ['token']), 'tool', expanded); lifecycle.manual('tool');
+    vi.advanceTimersByTime(2000); expect(expanded.has('tool')).toBe(true); expect(changed).not.toHaveBeenCalled();
+    lifecycle.clear(); expanded.clear(); lifecycle.manual('tool'); lifecycle.observe(message('running', ['token']), 'tool', expanded); expect(expanded.size).toBe(0);
+  });
+  it('supports disabling automatics and cleans pending timers on clear/prune', () => {
+    vi.useFakeTimers(); const changed = vi.fn(); const lifecycle = createActivityLifecycle(changed); const expanded = new Set<string>();
+    lifecycle.observe(message('running', ['token']), 'tool', expanded, { autoExpand: false, autoCollapseDelay: false });
+    lifecycle.observe(message('complete', ['token']), 'tool', expanded, { autoCollapseDelay: false });
+    expect(expanded.size).toBe(0); expect(vi.getTimerCount()).toBe(0);
+    for (const cleanup of ['clear', 'prune'] as const) {
+      lifecycle.clear(); lifecycle.observe(message('running', ['token']), 'tool', expanded); lifecycle.observe(message('complete', ['token']), 'tool', expanded);
+      if (cleanup === 'clear') lifecycle.clear(); else lifecycle.prune(new Set());
+      vi.advanceTimersByTime(2000); expect(changed).not.toHaveBeenCalled();
+    }
+  });
+});

package/src/components/activity-row.ts

@@ -0,0 +1,136 @@
+import { Circle, Clock } from "lucide";
+import { renderIconNode } from "../utils/icon-node";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "../types";
+import { DEFAULT_TOOL_CALL_DISPLAY, DEFAULT_REASONING_DISPLAY, DEFAULTS_V5 } from "../defaults";
+import { createElement } from "../utils/dom";
+import { renderLucideIcon } from "../utils/icons";
+import { appendHeaderToggle } from "./expandable-bubble";
+
+export type ActivityKind = "tool" | "reasoning";
+
+/** Standalone builders and the full UI use the same versioned defaults. */
+export function activityDisplay(config: AgentWidgetConfig | undefined, kind: ActivityKind): AgentWidgetConfig {
+  const key = kind === "tool" ? "toolCallDisplay" : "reasoningDisplay";
+  return { ...config, features: { ...config?.features, [key]: {
+    ...(kind === "tool" ? DEFAULT_TOOL_CALL_DISPLAY : DEFAULT_REASONING_DISPLAY),
+    ...(config?.future?.v5Defaults === true ? DEFAULTS_V5.features?.[key] : {}),
+    ...config?.features?.[key],
+  } } };
+}
+
+export function activityVariant(config: AgentWidgetConfig | undefined, kind: ActivityKind): "card" | "row" {
+  const key = kind === "tool" ? "toolCallDisplay" : "reasoningDisplay";
+  return config?.features?.[key]?.variant ?? (config?.future?.v5Defaults ? "row" : "card");
+}
+
+export function activityDuration(ms: number | undefined): string {
+  const seconds = Math.max(0, Math.floor((ms ?? 0) / 1000));
+  if (seconds < 1) return "a moment";
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+}
+
+/** Reuses card content/render hooks while replacing only its visual chrome. */
+export function applyActivityRow(bubble: HTMLElement, message: AgentWidgetMessage, config: AgentWidgetConfig, kind: ActivityKind): HTMLElement {
+  if (activityVariant(config, kind) !== "row") return bubble;
+  bubble.className = `persona-message-bubble persona-${kind}-bubble persona-activity-row`;
+  bubble.dataset.activityKind = kind;
+  if (kind === "tool" && config.toolCall?.shadow === undefined) bubble.style.boxShadow = "var(--persona-tool-bubble-shadow, none)";
+  const header = bubble.querySelector<HTMLButtonElement>(":scope > button");
+  if (!header) return bubble;
+  header.className = "persona-activity-header";
+  const data = kind === "tool" ? message.toolCall : message.reasoning;
+  const active = data?.status !== "complete";
+  const approval = message.approval?.status ?? message.toolCall?.approvalStatus;
+  const state = approval === "denied" ? "denied" : approval === "pending" ? "awaiting-approval"
+    : message.toolCall?.success === false ? "error" : !active ? "done"
+    : data?.status === "pending" ? "pending" : "running";
+  bubble.dataset.activityState = state;
+  const icon = createElement("span", "persona-activity-icon");
+  icon.dataset.activityIcon = state;
+  const names = { pending: "circle", running: "loader-circle", done: "check", error: "x", denied: "x", "awaiting-approval": "clock" };
+  const customIcon = kind === "reasoning" ? config.features?.reasoningDisplay?.iconName : undefined;
+  const glyph = customIcon ? renderLucideIcon(customIcon, 16, "currentColor", 2)
+    : state === "pending" ? renderIconNode(Circle, 16, "currentColor", 2)
+    : state === "awaiting-approval" ? renderIconNode(Clock, 16, "currentColor", 2)
+    : renderLucideIcon(names[state], 16, "currentColor", 2);
+  if (glyph) icon.appendChild(glyph);
+  header.querySelector(".persona-reasoning-header-icon")?.remove();
+  const displayKey = kind === "tool" ? "toolCallDisplay" : "reasoningDisplay";
+  const visibility = config.features?.[displayKey]?.iconVisibility ??
+    (config.future?.v5Defaults ? "active" : "always");
+  if (visibility === "always" || (visibility === "active" && state !== "done")) header.prepend(icon);
+  if (kind === "tool" && data) {
+    const duration = createElement("span", "persona-activity-duration");
+    if (active && data.startedAt) duration.setAttribute("data-tool-elapsed", String(data.startedAt));
+    const elapsed = (kind === "tool" ? message.toolCall?.duration : undefined) ?? data.durationMs ?? (data.completedAt !== undefined && data.startedAt !== undefined ? data.completedAt - data.startedAt : undefined);
+    duration.textContent = elapsed === undefined ? "" : activityDuration(elapsed);
+    header.appendChild(duration);
+  }
+  const label = header.querySelector<HTMLElement>(":scope > div:not(.persona-ml-auto)");
+  label?.classList.add("persona-activity-label");
+  const meta = header.querySelector<HTMLElement>(".persona-ml-auto");
+  meta?.classList.add("persona-activity-chevron");
+  const body = bubble.querySelector<HTMLElement>(":scope > .persona-border-t");
+  body?.classList.add("persona-activity-body");
+  if (body) { body.id = `activity-details-${message.id}`; header.setAttribute("aria-controls", body.id); }
+  return bubble;
+}
+
+/** Per-widget lifecycle: one open and one delayed close; user intent is sticky. */
+export function createActivityLifecycle(onCollapse: (id: string, kind: ActivityKind) => void) {
+  const seen = new Set<string>();
+  const manual = new Set<string>();
+  const finished = new Set<string>();
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  const cancel = (id: string) => { clearTimeout(timers.get(id)); timers.delete(id); };
+  return {
+    observe(message: AgentWidgetMessage, kind: ActivityKind, expanded: Set<string>, options: { autoExpand?: boolean; autoCollapseDelay?: number | false } = {}) {
+      const data = kind === "tool" ? message.toolCall : message.reasoning;
+      if (!data || manual.has(message.id)) return;
+      if (!seen.has(message.id) && data.status !== "complete" && data.chunks?.some(Boolean)) {
+        seen.add(message.id);
+        if (options.autoExpand !== false) expanded.add(message.id);
+      }
+      if (seen.has(message.id) && data.status === "complete" && !finished.has(message.id)) {
+        finished.add(message.id);
+        if (options.autoCollapseDelay === false) return;
+        timers.set(message.id, setTimeout(() => {
+          timers.delete(message.id);
+          expanded.delete(message.id);
+          onCollapse(message.id, kind);
+        }, options.autoCollapseDelay ?? 1000));
+      }
+    },
+    manual(id: string) { manual.add(id); cancel(id); },
+    prune(ids: Set<string>) {
+      for (const id of new Set([...seen, ...manual, ...finished])) {
+        if (!ids.has(id)) { cancel(id); seen.delete(id); manual.delete(id); finished.delete(id); }
+      }
+    },
+    clear() { for (const id of timers.keys()) cancel(id); seen.clear(); manual.clear(); finished.clear(); },
+  };
+}
+
+/** A collapsible group uses the same accessible row and expansion contract. */
+export function createActivityGroup(message: AgentWidgetMessage, config: AgentWidgetConfig, expanded: boolean, label: string | HTMLElement): { bubble: HTMLElement; body: HTMLElement } {
+  const bubble = createElement("div", "");
+  bubble.id = `bubble-${message.id}`;
+  bubble.dataset.messageId = message.id;
+  const header = createElement("button", "") as HTMLButtonElement;
+  header.type = "button";
+  header.dataset.expandHeader = "true";
+  header.dataset.bubbleType = "tool";
+  header.setAttribute("aria-expanded", String(expanded));
+  const copy = createElement("div", "");
+  if (typeof label === "string") copy.textContent = label; else copy.appendChild(label);
+  appendHeaderToggle(header, copy, { expandable: true, expanded, iconColor: config.toolCall?.toggleTextColor || config.toolCall?.headerTextColor || "currentColor", metaGap: true });
+  const body = createElement("div", "persona-border-t");
+  body.id = `activity-details-${message.id}`;
+  body.style.display = expanded ? "" : "none";
+  header.setAttribute("aria-controls", body.id);
+  bubble.append(header, body);
+  applyActivityRow(bubble, message, { ...config, features: { ...config.features, toolCallDisplay: { ...config.features?.toolCallDisplay, variant: "row" } } }, "tool");
+  bubble.dataset.personaToolGroup = "true";
+  if (config.features?.toolCallDisplay?.loadingAnimation === "shimmer") bubble.dataset.activityGroupShimmer = "true";
+  return { bubble, body };
+}

package/src/components/approval-actions.test.ts

@@ -1,8 +1,7 @@
 // @vitest-environment jsdom
 
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createBuiltInApprovalPlugin } from "./approval-actions";
-import { approvalDetailsExpansionState } from "./approval-bubble";
 import type {
   AgentWidgetApproval,
   AgentWidgetConfig,
@@ -43,9 +42,10 @@ const makeMessage = (
 // Each widget owns its own plugin instance + teardown (state is per-instance).
 // Track teardowns so afterEach can release any leftover document listeners.
 let teardowns: Array<() => void> = [];
+let expansionState: Map<string, boolean>;
 
 const makePlugin = (): { plugin: AgentWidgetPlugin; teardown: () => void } => {
-  const handle = createBuiltInApprovalPlugin();
+  const handle = createBuiltInApprovalPlugin(expansionState);
   teardowns.push(handle.teardown);
   return handle;
 };
@@ -81,10 +81,13 @@ const click = (el: Element | null | undefined): void => {
 afterEach(() => {
   teardowns.forEach((t) => t());
   teardowns = [];
-  approvalDetailsExpansionState.clear();
   document.body.innerHTML = "";
 });
 
+beforeEach(() => {
+  expansionState = new Map<string, boolean>();
+});
+
 describe("built-in approval — flag off (default)", () => {
   it("renders a single Allow + Deny, no split control", () => {
     const { el } = render();
@@ -226,7 +229,7 @@ describe("built-in approval — parameters disclosure", () => {
     expect(pre?.hidden).toBe(true);
     click(el?.querySelector(".persona-approval-head"));
     expect(pre?.hidden).toBe(false);
-    expect(approvalDetailsExpansionState.get("msg-1")).toBe(true);
+    expect(expansionState.get("msg-1")).toBe(true);
   });
 
   it("detailsDisplay:'expanded' shows params up front", () => {

package/src/components/approval-actions.ts

@@ -34,7 +34,7 @@ import type {
   AgentWidgetApprovalConfig,
 } from "../types";
 import type { AgentWidgetPlugin } from "../plugins/types";
-import { humanizeToolName, approvalDetailsExpansionState } from "./approval-bubble";
+import { humanizeToolName } from "./approval-bubble";
 
 type Approval = NonNullable<AgentWidgetMessage["approval"]>;
 type Decide = (options?: { remember?: boolean }) => void;
@@ -103,10 +103,11 @@ const resolveApprovalConfig = (
 
 const isDetailsExpanded = (
   messageId: string,
+  expansionState: Map<string, boolean>,
   approvalConfig?: AgentWidgetApprovalConfig
 ): boolean => {
   const mode = approvalConfig?.detailsDisplay ?? "collapsed";
-  return approvalDetailsExpansionState.get(messageId) ?? mode === "expanded";
+  return expansionState.get(messageId) ?? mode === "expanded";
 };
 
 const kbd = (label: string): HTMLElement => {
@@ -173,6 +174,7 @@ const buildResolvedTrace = (approval: Approval): HTMLElement => {
 
 const buildPending = (
   state: InstanceState,
+  expansionState: Map<string, boolean>,
   message: AgentWidgetMessage,
   approval: Approval,
   approvalConfig: AgentWidgetApprovalConfig | undefined,
@@ -199,7 +201,7 @@ const buildPending = (
   const hasDescription = Boolean(approval.description) && detailsMode !== "hidden";
   const hasParams = approval.parameters != null && detailsMode !== "hidden";
   const hasDetails = hasDescription || hasParams;
-  const expanded = hasDetails && isDetailsExpanded(message.id, approvalConfig);
+  const expanded = hasDetails && isDetailsExpanded(message.id, expansionState, approvalConfig);
 
   // The card uses the whole header as the disclosure toggle (chevron-only, no
   // separate text button), but the legacy `showDetailsLabel`/`hideDetailsLabel`
@@ -351,7 +353,7 @@ const buildPending = (
         pre.hidden = !willOpen;
         head.setAttribute("aria-expanded", willOpen ? "true" : "false");
         head.setAttribute("aria-label", willOpen ? hideDetailsLabel : showDetailsLabel);
-        approvalDetailsExpansionState.set(message.id, willOpen);
+        expansionState.set(message.id, willOpen);
       }
       return;
     }
@@ -389,7 +391,9 @@ const buildPending = (
  * callbacks — both close over the SAME per-instance state, so destroying one
  * widget never disturbs another widget's open approvals on the same page.
  */
-export const createBuiltInApprovalPlugin = (): {
+export const createBuiltInApprovalPlugin = (
+  expansionState = new Map<string, boolean>()
+): {
   plugin: AgentWidgetPlugin;
   teardown: () => void;
 } => {
@@ -419,7 +423,16 @@ export const createBuiltInApprovalPlugin = (): {
       // re-render of an older card doesn't reorder it ahead of a newer one.
       detachMessage(state, message.id);
       const enableAlways = approvalConfig?.enableAlwaysAllow === true;
-      const card = buildPending(state, message, approval, approvalConfig, approve, deny, enableAlways);
+      const card = buildPending(
+        state,
+        expansionState,
+        message,
+        approval,
+        approvalConfig,
+        approve,
+        deny,
+        enableAlways
+      );
 
       if (enableAlways) {
         if (!state.pendingOrder.includes(message.id)) state.pendingOrder.push(message.id);