@runtypelabs/persona 3.23.0 → 3.25.0

package/src/index.ts

@@ -1,409 +1,33 @@
-import {
-  initAgentWidget as initAgentWidgetFn,
-  type AgentWidgetInitHandle
-} from "./runtime/init";
-
-export type {
-  AgentWidgetConfig,
-  AgentWidgetFeatureFlags,
-  AgentWidgetArtifactsFeature,
-  AgentWidgetArtifactsLayoutConfig,
-  PersonaArtifactKind,
-  PersonaArtifactRecord,
-  PersonaArtifactManualUpsert,
-  ArtifactConfigPayload,
-  AgentWidgetInitOptions,
-  AgentWidgetMessage,
-  AgentWidgetLauncherConfig,
-  AgentWidgetDockConfig,
-  AgentWidgetEvent,
-  AgentWidgetStreamParser,
-  AgentWidgetStreamParserResult,
-  AgentWidgetRequestPayload,
-  // Context provider types (e.g. for config.contextProviders)
-  AgentWidgetContextProvider,
-  AgentWidgetContextProviderContext,
-  AgentWidgetCustomFetch,
-  AgentWidgetSSEEventParser,
-  AgentWidgetSSEEventResult,
-  AgentWidgetHeadersFunction,
-  // Multi-modal content types
-  TextContentPart,
-  ImageContentPart,
-  ContentPart,
-  MessageContent,
-  // Attachment config type
-  AgentWidgetAttachmentsConfig,
-  AgentWidgetComposerConfig,
-  // Layout types
-  AgentWidgetLayoutConfig,
-  AgentWidgetHeaderLayoutConfig,
-  AgentWidgetMessageLayoutConfig,
-  AgentWidgetAvatarConfig,
-  AgentWidgetTimestampConfig,
-  WidgetLayoutSlot,
-  SlotRenderer,
-  SlotRenderContext,
-  HeaderRenderContext,
-  MessageRenderContext,
-  // Markdown types
-  AgentWidgetMarkdownConfig,
-  AgentWidgetMarkdownOptions,
-  AgentWidgetMarkdownRendererOverrides,
-  // Message actions types
-  AgentWidgetMessageActionsConfig,
-  AgentWidgetMessageFeedback,
-  // Client token types
-  ClientSession,
-  ClientInitResponse,
-  ClientChatRequest,
-  ClientFeedbackRequest,
-  ClientFeedbackType,
-  // Message injection types
-  InjectMessageOptions,
-  InjectAssistantMessageOptions,
-  InjectUserMessageOptions,
-  InjectSystemMessageOptions,
-  InjectComponentDirectiveOptions,
-  // Loading indicator types
-  LoadingIndicatorRenderContext,
-  AgentWidgetLoadingIndicatorConfig,
-  // Idle indicator types
-  IdleIndicatorRenderContext,
-  // Agent execution types
-  AgentConfig,
-  AgentLoopConfig,
-  AgentToolsConfig,
-  AgentRequestOptions,
-  AgentExecutionState,
-  AgentMessageMetadata,
-  AgentWidgetAgentRequestPayload,
-  // Approval types
-  AgentWidgetApproval,
-  AgentWidgetApprovalConfig,
-  // WebMCP — page-discovered tool consumption
-  AgentWidgetWebMcpConfig,
-  ClientToolDefinition,
-  WebMcpConfirmHandler,
-  WebMcpConfirmInfo,
-  WebMcpToolResult,
-  // Event stream types
-  SSEEventRecord,
-  EventStreamConfig,
-  EventStreamBadgeColor,
-  EventStreamViewRenderContext,
-  EventStreamRowRenderContext,
-  EventStreamToolbarRenderContext,
-  EventStreamPayloadRenderContext,
-  // Controller event map
-  AgentWidgetControllerEventMap,
-  // Ask-user-question (built-in answer-pill sheet) types
-  AskUserQuestionPayload,
-  AskUserQuestionPrompt,
-  AskUserQuestionOption,
-  AgentWidgetAskUserQuestionFeature,
-  AgentWidgetAskUserQuestionStyles
-} from "./types";
-
-export {
-  ASK_USER_QUESTION_TOOL_NAME,
-  createAskUserQuestionBubble,
-  ensureAskUserQuestionSheet,
-  removeAskUserQuestionSheet,
-  isAskUserQuestionMessage,
-  parseAskUserQuestionPayload
-} from "./components/ask-user-question-bubble";
-
-export { initAgentWidgetFn as initAgentWidget };
-export {
-  createWidgetHostLayout,
-  type WidgetHostLayout,
-  type WidgetHostLayoutMode
-} from "./runtime/host-layout";
-export {
-  createAgentExperience,
-  type AgentWidgetController
-} from "./ui";
-export {
-  AgentWidgetSession,
-  type AgentWidgetSessionStatus
-} from "./session";
-export { AgentWidgetClient } from "./client";
-export type { SSEEventCallback } from "./client";
-export {
-  WebMcpBridge,
-  WEBMCP_TOOL_PREFIX,
-  isWebMcpToolName,
-  stripWebMcpPrefix
-} from "./webmcp-bridge";
-export { createLocalStorageAdapter } from "./utils/storage";
-export {
-  createActionManager,
-  defaultActionHandlers,
-  defaultJsonActionParser
-} from "./utils/actions";
-export {
-  markdownPostprocessor,
-  escapeHtml,
-  directivePostprocessor,
-  createMarkdownProcessor,
-  createMarkdownProcessorFromConfig,
-  createDirectivePostprocessor
-} from "./postprocessors";
-export type { MarkdownProcessorOptions } from "./postprocessors";
-export {
-  createDefaultSanitizer,
-  resolveSanitizer
-} from "./utils/sanitize";
-export type { SanitizeFunction } from "./utils/sanitize";
-export {
-  createPlainTextParser,
-  createJsonStreamParser,
-  createFlexibleJsonStreamParser,
-  createRegexJsonParser,
-  createXmlParser
-} from "./utils/formatting";
-export {
-  // Multi-modal content utilities
-  normalizeContent,
-  getDisplayText,
-  hasImages,
-  getImageParts,
-  createTextPart,
-  createImagePart,
-  fileToImagePart,
-  validateImageFile
-} from "./utils/content";
-export {
-  collectEnrichedPageContext,
-  formatEnrichedContext,
-  generateStableSelector,
-  defaultParseRules
-} from "./utils/dom-context";
-export type {
-  EnrichedPageElement,
-  DomContextOptions,
-  DomContextMode,
-  ParseOptionsConfig,
-  ParseRule,
-  RuleScoringContext,
-  FormatEnrichedContextOptions
-} from "./utils/dom-context";
-export {
-  AttachmentManager,
-  type PendingAttachment,
-  type AttachmentManagerConfig
-} from "./utils/attachment-manager";
-export {
-  generateMessageId,
-  generateUserMessageId,
-  generateAssistantMessageId
-} from "./utils/message-id";
-export { isDockedMountMode, resolveDockConfig } from "./utils/dock";
+/**
+ * npm package entry (`@runtypelabs/persona`).
+ *
+ * This is a thin barrel over `index-core.ts` (the shared public API) that adds
+ * back the **dev/config-tool-only** helpers — `generateCodeSnippet` and
+ * `createDemoCarousel`. Those are kept out of `index-core.ts` so the IIFE/CDN
+ * build (`index-global.ts`, which re-exports from `index-core.ts`) doesn't ship
+ * them: a running widget never needs them, only build-time/demo tooling does.
+ *
+ * Net effect: npm consumers get the full API (unchanged), while the script-tag
+ * `window.AgentWidget` global no longer exposes `generateCodeSnippet` /
+ * `createDemoCarousel`.
+ */
+
+// Full public API (everything except the two dev-only helpers below).
+export * from "./index-core";
+export { default } from "./index-core";
+
+// Dev / config-tool helper: generate install snippets from a widget config.
 export { generateCodeSnippet } from "./utils/code-generators";
-export type { CodeFormat, CodeGeneratorHooks, CodeGeneratorOptions } from "./utils/code-generators";
-export { VERSION } from "./version";
-export type { AgentWidgetInitHandle };
-
-// Plugin system exports
-export type { AgentWidgetPlugin } from "./plugins/types";
-export { pluginRegistry } from "./plugins/registry";
-
-// Stream animation plugin API — lets consumers register custom animations
-// that match the built-in surface (typewriter, pop-bubble) and subpath
-// modules (letter-rise, word-fade, wipe, glyph-cycle).
-export {
-  registerStreamAnimationPlugin,
-  unregisterStreamAnimationPlugin,
-  listRegisteredStreamAnimations,
-} from "./utils/stream-animation";
-export type {
-  StreamAnimationPlugin,
-  StreamAnimationContext,
-  AgentWidgetStreamAnimationBuffer,
-  AgentWidgetStreamAnimationBuiltinType,
-  AgentWidgetStreamAnimationType,
-  AgentWidgetStreamAnimationFeature,
-  AgentWidgetStreamAnimationPlaceholder,
-} from "./types";
-
-// Action system types — needed to type the `actionHandlers` / `actionParsers`
-// config options and to author custom handlers/parsers.
-export type {
-  AgentWidgetActionHandler,
-  AgentWidgetActionHandlerResult,
-  AgentWidgetActionParser,
-  AgentWidgetParsedAction,
-  AgentWidgetActionContext,
-  AgentWidgetActionEventPayload,
-} from "./types";
-
-// Dropdown utility exports
-export { createDropdownMenu } from "./utils/dropdown";
-export type { DropdownMenuItem, CreateDropdownOptions, DropdownMenuHandle } from "./utils/dropdown";
-
-// Icon utility exports
-export { renderLucideIcon } from "./utils/icons";
-export type { IconName } from "./utils/icons";
-
-// Button utility exports
-export { createIconButton, createLabelButton, createToggleGroup, createComboButton } from "./utils/buttons";
 export type {
-  CreateIconButtonOptions,
-  CreateLabelButtonOptions,
-  CreateToggleGroupOptions,
-  ToggleGroupItem,
-  ToggleGroupHandle,
-  CreateComboButtonOptions,
-  ComboButtonHandle
-} from "./utils/buttons";
+  CodeFormat,
+  CodeGeneratorHooks,
+  CodeGeneratorOptions
+} from "./utils/code-generators";
 
-// Demo carousel exports
+// Demo-only component: the examples' showcase carousel.
 export { createDemoCarousel } from "./components/demo-carousel";
 export type {
   DemoCarouselItem,
   DemoCarouselOptions,
   DemoCarouselHandle
 } from "./components/demo-carousel";
-
-// Theme system exports
-export {
-  createTheme,
-  resolveTokens,
-  themeToCssVariables,
-  applyThemeVariables,
-  getActiveTheme,
-  getColorScheme,
-  detectColorScheme,
-  createThemeObserver
-} from "./utils/theme";
-export {
-  DEFAULT_PALETTE,
-  DEFAULT_SEMANTIC,
-  DEFAULT_COMPONENTS,
-  validateTheme,
-  THEME_ZONES
-} from "./utils/tokens";
-export type { ThemeZone } from "./utils/tokens";
-export {
-  accessibilityPlugin,
-  animationsPlugin,
-  brandPlugin,
-  reducedMotionPlugin,
-  highContrastPlugin,
-  createPlugin
-} from "./utils/plugins";
-export type {
-  DeepPartial,
-  PersonaTheme,
-  PersonaThemePlugin,
-  CreateThemeOptions,
-  TokenReference,
-  ColorShade,
-  ColorPalette,
-  SpacingScale,
-  TypographyScale,
-  ShadowScale,
-  BorderScale,
-  RadiusScale,
-  SemanticColors,
-  SemanticSpacing,
-  SemanticTypography,
-  ComponentTokens,
-  ArtifactToolbarTokens,
-  ArtifactTabTokens,
-  ArtifactPaneTokens,
-  IconButtonTokens,
-  LabelButtonTokens,
-  ToggleGroupTokens,
-  ThemeValidationResult,
-  ThemeValidationError
-} from "./types/theme";
-
-// Component system exports
-export { componentRegistry } from "./components/registry";
-export type { ComponentRenderer, ComponentContext } from "./components/registry";
-export {
-  createComponentStreamParser,
-  isComponentDirectiveType
-} from "./utils/component-parser";
-export type { ComponentDirective } from "./utils/component-parser";
-export {
-  renderComponentDirective,
-  createComponentMiddleware,
-  hasComponentDirective,
-  extractComponentDirectiveFromMessage
-} from "./utils/component-middleware";
-
-// Default configuration exports
-export {
-  DEFAULT_WIDGET_CONFIG,
-  DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH,
-  DEFAULT_FLOATING_LAUNCHER_WIDTH,
-  mergeWithDefaults
-} from "./defaults";
-export {
-  PRESETS,
-  getPreset,
-  PRESET_SHOP,
-  PRESET_MINIMAL,
-  PRESET_FULLSCREEN
-} from "./presets";
-export type { WidgetPreset } from "./presets";
-
-// Layout system exports
-export {
-  buildHeader,
-  buildComposer,
-  attachHeaderToContainer
-} from "./components/panel";
-export type {
-  HeaderElements,
-  HeaderBuildContext,
-  ComposerElements,
-  ComposerBuildContext
-} from "./components/panel";
-export {
-  headerLayouts,
-  getHeaderLayout,
-  buildHeaderWithLayout,
-  buildDefaultHeader,
-  buildMinimalHeader
-} from "./components/header-layouts";
-export type {
-  HeaderLayoutContext,
-  HeaderLayoutRenderer
-} from "./components/header-layouts";
-export {
-  createStandardBubble,
-  createBubbleWithLayout,
-  createTypingIndicator,
-  createMessageActions,
-  renderLoadingIndicatorWithFallback
-} from "./components/message-bubble";
-export type {
-  MessageTransform,
-  MessageActionCallbacks,
-  LoadingIndicatorRenderer,
-  CreateStandardBubbleOptions
-} from "./components/message-bubble";
-export {
-  createCSATFeedback,
-  createNPSFeedback
-} from "./components/feedback";
-export type { CSATFeedbackOptions, NPSFeedbackOptions } from "./components/feedback";
-
-// Voice module exports
-export {
-  createVoiceProvider,
-  createBestAvailableVoiceProvider,
-  isVoiceSupported
-} from "./voice";
-export type {
-  VoiceProvider,
-  VoiceResult,
-  VoiceStatus,
-  VoiceConfig
-} from "./types";
-
-export default initAgentWidgetFn;

package/src/session.ts

@@ -2059,6 +2059,10 @@ export class AgentWidgetSession {
     // a tool with the same key resolved in the prior conversation.
     this.webMcpInflightKeys.clear();
     this.webMcpResolvedKeys.clear();
+    // A fresh conversation must resend the full WebMCP tool list on its next
+    // turn — drop the diff-only fingerprint cache (server keys by recordId, so
+    // a new conversation has no stored set to match).
+    this.client.resetClientToolsFingerprint();
     this.setStreaming(false);
     this.setStatus("idle");
     this.callbacks.onMessagesChanged([...this.messages]);

package/src/types.ts

@@ -2224,6 +2224,23 @@ export type ClientChatRequest = {
   context?: Record<string, unknown>;
   /** WebMCP page-discovered tools — same shape as `dispatch.clientTools[]`. */
   clientTools?: ClientToolDefinition[];
+  /**
+   * Diff-only / send-once: order-independent fingerprint of the client tool set.
+   * When the set is unchanged from the previous turn the widget sends this
+   * WITHOUT `clientTools` and the server reuses its stored set. On a cache miss
+   * the server replies `409 { error: 'client_tools_resend_required' }` and the
+   * widget retries once with the full `clientTools[]`.
+   */
+  clientToolsFingerprint?: string;
+};
+
+/**
+ * Body the server returns (HTTP 409) when it holds no stored tool set matching
+ * a fingerprint-only `/client/chat` turn. The widget retries once with the full
+ * `clientTools[]` (and the fingerprint).
+ */
+export type ClientToolsResendRequiredResponse = {
+  error: 'client_tools_resend_required';
 };
 
 /**

package/src/webmcp-bridge.test.ts

@@ -29,7 +29,9 @@ import {
   WebMcpBridge,
   isWebMcpToolName,
   stripWebMcpPrefix,
+  computeClientToolsFingerprint,
 } from "./webmcp-bridge";
+import type { ClientToolDefinition } from "./types";
 
 type MockClient = { requestUserInteraction: (cb: () => unknown) => Promise<unknown> };
 
@@ -427,3 +429,81 @@ describe("WebMcpBridge.executeToolCall", () => {
     expect(executeSpy).not.toHaveBeenCalled();
   });
 });
+
+describe("computeClientToolsFingerprint — diff-only / send-once", () => {
+  const tool = (over: Partial<ClientToolDefinition> = {}): ClientToolDefinition => ({
+    name: "search",
+    description: "Search the catalog",
+    parametersSchema: { type: "object", properties: { q: { type: "string" } } },
+    origin: "webmcp",
+    ...over,
+  });
+
+  it("returns a stable sentinel for an empty set", () => {
+    expect(computeClientToolsFingerprint([])).toBe(computeClientToolsFingerprint([]));
+    expect(computeClientToolsFingerprint([])).toBe("0:empty");
+  });
+
+  it("is deterministic for the same set", () => {
+    const a = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    const b = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    expect(a).toBe(b);
+  });
+
+  it("is order-independent (tool order does not matter)", () => {
+    const ab = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    const ba = computeClientToolsFingerprint([tool({ name: "b" }), tool({ name: "a" })]);
+    expect(ab).toBe(ba);
+  });
+
+  it("changes when a description changes", () => {
+    expect(computeClientToolsFingerprint([tool({ description: "x" })])).not.toBe(
+      computeClientToolsFingerprint([tool({ description: "y" })]),
+    );
+  });
+
+  it("changes when the schema changes", () => {
+    const base = computeClientToolsFingerprint([tool()]);
+    const changed = computeClientToolsFingerprint([
+      tool({ parametersSchema: { type: "object", properties: { q: { type: "number" } } } }),
+    ]);
+    expect(changed).not.toBe(base);
+  });
+
+  it("changes when a tool is added", () => {
+    const one = computeClientToolsFingerprint([tool({ name: "a" })]);
+    const two = computeClientToolsFingerprint([tool({ name: "a" }), tool({ name: "b" })]);
+    expect(two).not.toBe(one);
+  });
+
+  it("ignores pageOrigin (audit metadata, not part of the contract)", () => {
+    const withOrigin = computeClientToolsFingerprint([tool({ pageOrigin: "https://a.example" })]);
+    const without = computeClientToolsFingerprint([tool({ pageOrigin: undefined })]);
+    expect(withOrigin).toBe(without);
+  });
+
+  it("reflects annotations (they ride along to the server)", () => {
+    const plain = computeClientToolsFingerprint([tool()]);
+    const annotated = computeClientToolsFingerprint([
+      tool({ annotations: { readOnlyHint: true } }),
+    ]);
+    expect(annotated).not.toBe(plain);
+  });
+
+  it("stays within the server's 128-char wire bound for large tool sets", () => {
+    // The server validates `clientToolsFingerprint` as `z.string().max(128)`.
+    // A fingerprint that grew with the tool content would 400 the first turn.
+    const many = Array.from({ length: 50 }, (_, i) =>
+      tool({
+        name: `tool_${i}`,
+        description: `A fairly long description for tool number ${i} `.repeat(8),
+        parametersSchema: {
+          type: "object",
+          properties: { a: { type: "string" }, b: { type: "number" }, c: { type: "boolean" } },
+        },
+      }),
+    );
+    const fp = computeClientToolsFingerprint(many);
+    expect(fp.length).toBeLessThanOrEqual(128);
+  });
+});

package/src/webmcp-bridge.ts

@@ -86,6 +86,74 @@ const log = {
   },
 };
 
+/**
+ * Compute a stable, order-independent fingerprint of a `ClientToolDefinition[]`
+ * snapshot, for the diff-only / send-once dispatch path (client-token mode).
+ *
+ * The widget caches "the fingerprint of the tool set last sent in full" for the
+ * current session; an unchanged set on a follow-up turn lets it ship only the
+ * fingerprint instead of the whole array. Per-tool strings are sorted so tool
+ * ordering does not affect the result. `pageOrigin` is deliberately excluded —
+ * it is audit metadata, not part of the tool contract.
+ *
+ * This is a fast, non-cryptographic content key. The canonical per-tool content
+ * is hashed down to a short, fixed-length digest so the result fits the server's
+ * `clientToolsFingerprint` wire field (`z.string().max(128)`) regardless of how
+ * many tools the page registers — sending the raw concatenated content would
+ * overflow that bound and be rejected with a 400. The server stores and compares
+ * the widget's fingerprint verbatim, so cross-implementation byte-equality is NOT
+ * required — only self-consistency across this widget's turns.
+ */
+export function computeClientToolsFingerprint(
+  tools: ClientToolDefinition[],
+): string {
+  if (tools.length === 0) return "0:empty";
+  const parts = tools
+    .map((t) =>
+      [
+        t.name,
+        t.description ?? "",
+        t.parametersSchema ? JSON.stringify(t.parametersSchema) : "",
+        t.origin ?? "",
+        t.annotations ? JSON.stringify(t.annotations) : "",
+      ].join("\x1f"),
+    )
+    .sort();
+  return `${tools.length}:${hashFingerprintContent(parts.join("\x1e"))}`;
+}
+
+/**
+ * cyrb53 — a fast, well-distributed non-cryptographic string hash. Returns a
+ * 53-bit value (safe-integer range). Two independent seeds are combined by the
+ * caller for a ~106-bit digest, which makes accidental collisions across a
+ * single conversation's handful of tool-set variants infeasible.
+ */
+function cyrb53(str: string, seed: number): number {
+  let h1 = 0xdeadbeef ^ seed;
+  let h2 = 0x41c6ce57 ^ seed;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+}
+
+/**
+ * Compress the canonical tool-set content string into a short, fixed-length
+ * fingerprint (≤ ~24 chars) that fits the server's 128-char wire bound. Uses two
+ * seeded cyrb53 passes, base-36 encoded.
+ */
+function hashFingerprintContent(content: string): string {
+  const a = cyrb53(content, 0).toString(36);
+  const b = cyrb53(content, 0x9e3779b1).toString(36);
+  return `${a}.${b}`;
+}
+
 export class WebMcpBridge {
   private confirmHandler: WebMcpConfirmHandler | null;
   private readonly timeoutMs: number;