@runtypelabs/persona 4.13.0 → 4.15.0

package/src/suggest-replies-tool.test.ts

@@ -6,6 +6,7 @@ import {
   SUGGEST_REPLIES_TOOL_NAME,
   latestAgentSuggestions,
   parseSuggestRepliesPayload,
+  resolveFollowUpsFeature,
 } from "./suggest-replies-tool";
 import {
   ASK_USER_QUESTION_CLIENT_TOOL,
@@ -26,14 +27,27 @@ describe("SUGGEST_REPLIES_CLIENT_TOOL definition", () => {
     expect(SUGGEST_REPLIES_CLIENT_TOOL.annotations?.readOnlyHint).toBe(true);
   });
 
-  it("bounds suggestions to 1-4 short strings", () => {
+  it("bounds suggestions to semantic-only object items", () => {
     const suggestions =
       SUGGEST_REPLIES_PARAMETERS_SCHEMA.properties.suggestions;
     expect(suggestions.minItems).toBe(1);
     expect(suggestions.maxItems).toBe(SUGGEST_REPLIES_MAX);
-    expect(suggestions.items.maxLength).toBe(60);
+    expect(suggestions.items.type).toBe("object");
+    expect(suggestions.items.required).toEqual(["label"]);
+    expect(suggestions.items.additionalProperties).toBe(false);
     expect(SUGGEST_REPLIES_PARAMETERS_SCHEMA.required).toEqual(["suggestions"]);
   });
+
+  it("advertises no oneOf union and no presentation fields", () => {
+    const items = SUGGEST_REPLIES_PARAMETERS_SCHEMA.properties.suggestions
+      .items as Record<string, unknown>;
+    expect(items.oneOf).toBeUndefined();
+    expect(Object.keys(items.properties as Record<string, unknown>)).toEqual([
+      "label",
+      "prompt",
+      "description",
+    ]);
+  });
 });
 
 describe("parseSuggestRepliesPayload", () => {
@@ -55,6 +69,44 @@ describe("parseSuggestRepliesPayload", () => {
     ).toEqual(["A", "B"]);
   });
 
+  it("parses rich items while dropping malformed objects", () => {
+    expect(
+      parseSuggestRepliesPayload({
+        suggestions: [
+          {
+            label: " Pricing ",
+            prompt: " Tell me about pricing ",
+            description: " Compare plans ",
+          },
+          { label: "   " },
+          { nope: true },
+        ],
+      }),
+    ).toEqual([
+      {
+        label: "Pricing",
+        prompt: "Tell me about pricing",
+        description: "Compare plans",
+      },
+    ]);
+  });
+
+  it("strips presentation fields a model may send anyway", () => {
+    expect(
+      parseSuggestRepliesPayload({
+        suggestions: [
+          {
+            id: "pricing",
+            label: "Pricing",
+            icon: "dollar-sign",
+            behavior: "fill",
+            emphasis: "primary",
+          },
+        ],
+      }),
+    ).toEqual([{ label: "Pricing" }]);
+  });
+
   it("truncates past the cap with a console warning", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
     const result = parseSuggestRepliesPayload({
@@ -145,6 +197,172 @@ describe("latestAgentSuggestions", () => {
   });
 });
 
+describe("resolveFollowUpsFeature", () => {
+  const cfg = (config: Partial<AgentWidgetConfig>): AgentWidgetConfig =>
+    config as AgentWidgetConfig;
+
+  it("defaults to enabled and not exposed", () => {
+    expect(resolveFollowUpsFeature(undefined)).toEqual({
+      enabled: true,
+      expose: false,
+    });
+    expect(resolveFollowUpsFeature(cfg({}))).toEqual({
+      enabled: true,
+      expose: false,
+    });
+  });
+
+  it("reads each key from suggestions.followUps", () => {
+    expect(
+      resolveFollowUpsFeature(
+        cfg({ suggestions: { followUps: { expose: true } } }),
+      ),
+    ).toEqual({ enabled: true, expose: true });
+    expect(
+      resolveFollowUpsFeature(
+        cfg({ suggestions: { followUps: { enabled: false } } }),
+      ),
+    ).toEqual({ enabled: false, expose: false });
+  });
+
+  it("falls back per key to the deprecated features.suggestReplies alias", () => {
+    expect(
+      resolveFollowUpsFeature(
+        cfg({
+          features: { suggestReplies: { enabled: true, expose: true } },
+          suggestions: { followUps: { variant: "card" } },
+        }),
+      ),
+    ).toEqual({ enabled: true, expose: true });
+    // New home supplies `expose`, alias still supplies `enabled`.
+    expect(
+      resolveFollowUpsFeature(
+        cfg({
+          features: { suggestReplies: { enabled: false } },
+          suggestions: { followUps: { expose: true } },
+        }),
+      ),
+    ).toEqual({ enabled: false, expose: false });
+  });
+
+  it("does not silently re-enable when only presentation keys are added", () => {
+    expect(
+      resolveFollowUpsFeature(
+        cfg({
+          features: { suggestReplies: { enabled: false } },
+          suggestions: { followUps: { variant: "card" } },
+        }),
+      ),
+    ).toEqual({ enabled: false, expose: false });
+  });
+
+  it("lets suggestions.followUps win on conflict", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    expect(
+      resolveFollowUpsFeature(
+        cfg({
+          features: { suggestReplies: { enabled: false, expose: false } },
+          suggestions: { followUps: { enabled: true, expose: true } },
+        }),
+      ),
+    ).toEqual({ enabled: true, expose: true });
+    expect(
+      resolveFollowUpsFeature(
+        cfg({
+          features: { suggestReplies: { enabled: true, expose: true } },
+          suggestions: { followUps: { enabled: false } },
+        }),
+      ),
+    ).toEqual({ enabled: false, expose: false });
+    warn.mockRestore();
+  });
+
+  it("forces expose off when enabled resolves false", () => {
+    expect(
+      resolveFollowUpsFeature(
+        cfg({
+          suggestions: { followUps: { enabled: false, expose: true } },
+        }),
+      ),
+    ).toEqual({ enabled: false, expose: false });
+  });
+
+});
+
+describe("resolveFollowUpsFeature conflict warnings", () => {
+  const cfg = (config: Partial<AgentWidgetConfig>): AgentWidgetConfig =>
+    config as AgentWidgetConfig;
+
+  // The dedupe Set is module-level, so a shared conflict signature would let
+  // one test mask another. Each case gets a fresh module.
+  const freshResolve = async () => {
+    vi.resetModules();
+    return (await import("./suggest-replies-tool")).resolveFollowUpsFeature;
+  };
+
+  it("warns once per key without debug", async () => {
+    const resolve = await freshResolve();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    const production = cfg({
+      features: { suggestReplies: { enabled: true, expose: false } },
+      suggestions: { followUps: { enabled: false, expose: true } },
+    });
+    resolve(production);
+    resolve(production);
+    expect(warn).toHaveBeenCalledTimes(2);
+    expect(warn.mock.calls.map((call) => String(call[0]))).toEqual([
+      expect.stringContaining("suggestions.followUps.enabled"),
+      expect.stringContaining("suggestions.followUps.expose"),
+    ]);
+
+    warn.mockRestore();
+  });
+
+  it("warns with debug on too", async () => {
+    const resolve = await freshResolve();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    const debug = cfg({
+      debug: true,
+      features: { suggestReplies: { enabled: true, expose: false } },
+      suggestions: { followUps: { enabled: false, expose: true } },
+    });
+    resolve(debug);
+    resolve(debug);
+    expect(warn).toHaveBeenCalledTimes(2);
+
+    warn.mockRestore();
+  });
+
+  it("stays silent when a rebuilt config object repeats the same conflict", async () => {
+    const resolve = await freshResolve();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const conflicting = () =>
+      cfg({
+        features: { suggestReplies: { enabled: true } },
+        suggestions: { followUps: { enabled: false } },
+      });
+
+    // `controller.update()` rebuilds the config object on every call.
+    resolve(conflicting());
+    resolve(conflicting());
+    resolve(conflicting());
+    expect(warn).toHaveBeenCalledTimes(1);
+
+    // A different conflict is still a distinct developer error.
+    resolve(
+      cfg({
+        features: { suggestReplies: { expose: true } },
+        suggestions: { followUps: { expose: false } },
+      }),
+    );
+    expect(warn).toHaveBeenCalledTimes(2);
+
+    warn.mockRestore();
+  });
+});
+
 describe("builtInClientToolsForDispatch - suggest_replies gating", () => {
   it("returns nothing by default (expose is opt-in)", () => {
     expect(builtInClientToolsForDispatch(undefined)).toEqual([]);
@@ -173,6 +391,19 @@ describe("builtInClientToolsForDispatch - suggest_replies gating", () => {
     ).toEqual([]);
   });
 
+  it("reads expose from suggestions.followUps too", () => {
+    expect(
+      builtInClientToolsForDispatch({
+        suggestions: { followUps: { expose: true } },
+      } as AgentWidgetConfig),
+    ).toEqual([SUGGEST_REPLIES_CLIENT_TOOL]);
+    expect(
+      builtInClientToolsForDispatch({
+        suggestions: { followUps: { expose: true, enabled: false } },
+      } as AgentWidgetConfig),
+    ).toEqual([]);
+  });
+
   it("composes with ask_user_question, ask first", () => {
     expect(
       builtInClientToolsForDispatch({

package/src/suggest-replies-tool.ts

@@ -2,14 +2,13 @@
  * Built-in `suggest_replies` client tool.
  *
  * The widget can advertise this tool to the agent on every dispatch via
- * `clientTools[]` (set `features.suggestReplies.expose: true`): the same
+ * `clientTools[]` (set `suggestions.followUps.expose: true`): the same
  * wire surface as `ask_user_question` and WebMCP page tools. When the model
- * calls it, the execution pauses with a `step_await`
- * (`awaitReason: "local_tool_required"`); unlike `ask_user_question`, the
- * widget resolves it FIRE-AND-FORGET: it renders the suggestions as tappable
- * chips above the composer and immediately resumes the execution with a
- * canned "shown" result, so the agent's turn completes without waiting on the
- * user. Tapping a chip sends its text verbatim as the user's next message.
+ * calls it, the execution pauses with a `step_await` (a local-tool pause
+ * carries no `awaitReason`; that discriminator is internal). Unlike
+ * `ask_user_question`, the widget resolves it FIRE-AND-FORGET: it renders the
+ * configured follow-up surface and immediately resumes the execution with a
+ * canned "shown" result, so the turn completes without waiting on the user.
  *
  * Chip visibility is DERIVED state, not imperative show/hide: the chips of
  * the last `suggest_replies` tool message with no user message after it are
@@ -21,6 +20,7 @@
 import type {
   AgentWidgetConfig,
   AgentWidgetMessage,
+  AgentWidgetSuggestion,
   ClientToolDefinition,
 } from "./types";
 
@@ -30,9 +30,10 @@ export const SUGGEST_REPLIES_TOOL_NAME = "suggest_replies";
 export const SUGGEST_REPLIES_MAX = 4;
 
 /**
- * JSON Schema for the tool's parameters. Mirrors what
- * {@link parseSuggestRepliesPayload} hydrates the chips from, so the schema
- * the model is held to and the shape the renderer expects can never drift.
+ * JSON Schema for the tool's parameters. The model owns semantics only: id,
+ * icon, behavior, and emphasis are presentation, and hosts set them with the
+ * `transformSuggestions` plugin hook. A single object type is used because
+ * strict structured-output modes reject or flatten `oneOf`.
  */
 export const SUGGEST_REPLIES_PARAMETERS_SCHEMA = {
   type: "object",
@@ -43,7 +44,16 @@ export const SUGGEST_REPLIES_PARAMETERS_SCHEMA = {
       maxItems: SUGGEST_REPLIES_MAX,
       description:
         "1-4 short, distinct follow-up replies, phrased in the user's voice.",
-      items: { type: "string", minLength: 1, maxLength: 60 },
+      items: {
+        type: "object",
+        properties: {
+          label: { type: "string", minLength: 1, maxLength: 80 },
+          prompt: { type: "string", minLength: 1, maxLength: 500 },
+          description: { type: "string", minLength: 1, maxLength: 160 },
+        },
+        required: ["label"],
+        additionalProperties: false,
+      },
     },
   },
   required: ["suggestions"],
@@ -52,7 +62,7 @@ export const SUGGEST_REPLIES_PARAMETERS_SCHEMA = {
 
 /**
  * The `ClientToolDefinition` shipped on `dispatch.clientTools[]` when
- * `features.suggestReplies.expose` is on. Exported so integrators who prefer
+ * `suggestions.followUps.expose` is on. Exported so integrators who prefer
  * declaring the tool server-side (a flow's `runtimeTools`) can reuse the same
  * description and schema instead of hand-writing them.
  */
@@ -60,12 +70,15 @@ export const SUGGEST_REPLIES_CLIENT_TOOL: ClientToolDefinition = {
   name: SUGGEST_REPLIES_TOOL_NAME,
   description:
     "Offer the user tappable quick-reply suggestions for their next message. " +
-    "Call at most once per turn, as the LAST action after your reply text is " +
-    "complete. Each suggestion is sent verbatim as the user's next message, " +
-    'so phrase suggestions in the user\'s voice (e.g. "Tell me more about ' +
-    'pricing"). Keep them short and distinct. The result only confirms the ' +
-    "suggestions were shown: do not add further commentary after calling " +
-    "this tool; end your turn.",
+    "Call at most once per turn, as the last action after your reply text is " +
+    "complete. Give each suggestion a `label` with the short visible text, an " +
+    "optional `prompt` with the fuller text placed as the user's message " +
+    "(defaults to the label), and an optional `description` with one line of " +
+    "supporting copy. Suggestions are sent as the user's next message, so " +
+    'phrase prompts in the user\'s voice (e.g. "Tell me more about pricing"). ' +
+    "Keep them short and distinct. The result only confirms the suggestions " +
+    "were shown: do not add further commentary after calling this tool; end " +
+    "your turn.",
   parametersSchema: SUGGEST_REPLIES_PARAMETERS_SCHEMA,
   origin: "sdk",
   annotations: { readOnlyHint: true },
@@ -90,11 +103,15 @@ export const isSuggestRepliesMessage = (
   message.toolCall?.name === SUGGEST_REPLIES_TOOL_NAME;
 
 /**
- * Tolerant parse of a `suggest_replies` tool call's args into chip labels:
- * accepts a JSON string or object, coerces items to trimmed strings, drops
- * empties, and truncates past the renderer cap with a console warning.
+ * Tolerant parse of a `suggest_replies` tool call's args into suggestion
+ * items. Plain strings stay strings for older flows that emit
+ * `suggestions: string[]`; objects keep only label, prompt, and description,
+ * so a model that ignores `additionalProperties` cannot set presentation.
+ * Hosts add id, icon, behavior, and emphasis via `transformSuggestions`.
  */
-export const parseSuggestRepliesPayload = (args: unknown): string[] => {
+export const parseSuggestRepliesPayload = (
+  args: unknown
+): AgentWidgetSuggestion[] => {
   let parsed: unknown = args;
   if (typeof parsed === "string") {
     try {
@@ -106,17 +123,32 @@ export const parseSuggestRepliesPayload = (args: unknown): string[] => {
   const raw = (parsed as { suggestions?: unknown } | null | undefined)
     ?.suggestions;
   if (!Array.isArray(raw)) return [];
-  const chips = raw
-    .filter((item): item is string => typeof item === "string")
-    .map((item) => item.trim())
-    .filter((item) => item.length > 0);
-  if (chips.length > SUGGEST_REPLIES_MAX) {
+  const suggestions = raw.flatMap<AgentWidgetSuggestion>((item) => {
+    if (typeof item === "string") {
+      const value = item.trim();
+      return value ? [value] : [];
+    }
+    if (!item || typeof item !== "object") return [];
+    const value = item as Record<string, unknown>;
+    if (typeof value.label !== "string" || !value.label.trim()) return [];
+    const suggestion: Exclude<AgentWidgetSuggestion, string> = {
+      label: value.label.trim(),
+    };
+    if (typeof value.prompt === "string" && value.prompt.trim()) {
+      suggestion.prompt = value.prompt.trim();
+    }
+    if (typeof value.description === "string" && value.description.trim()) {
+      suggestion.description = value.description.trim();
+    }
+    return [suggestion];
+  });
+  if (suggestions.length > SUGGEST_REPLIES_MAX) {
     console.warn(
-      `[persona] suggest_replies: ${chips.length} suggestions exceeds the cap of ${SUGGEST_REPLIES_MAX}; extra suggestions dropped.`,
+      `[persona] suggest_replies: ${suggestions.length} suggestions exceeds the cap of ${SUGGEST_REPLIES_MAX}; extra suggestions dropped.`,
     );
-    return chips.slice(0, SUGGEST_REPLIES_MAX);
+    return suggestions.slice(0, SUGGEST_REPLIES_MAX);
   }
-  return chips;
+  return suggestions;
 };
 
 /**
@@ -127,7 +159,7 @@ export const parseSuggestRepliesPayload = (args: unknown): string[] => {
  */
 export const latestAgentSuggestions = (
   messages: AgentWidgetMessage[],
-): string[] | null => {
+): AgentWidgetSuggestion[] | null => {
   for (let i = messages.length - 1; i >= 0; i--) {
     const message = messages[i];
     if (message.role === "user") return null;
@@ -138,15 +170,59 @@ export const latestAgentSuggestions = (
   return null;
 };
 
+export type ResolvedFollowUpsFeature = {
+  /** Widget renders follow-up chips and auto-resumes the tool call. */
+  enabled: boolean;
+  /** Tool ships on `dispatch.clientTools[]`. */
+  expose: boolean;
+};
+
+// Keyed on the conflict itself, not the config object: `controller.update()`
+// rebuilds the config on every call, so an object-keyed dedupe re-warns
+// forever. Trade-off: two widgets with the identical conflict warn once total
+// per page load.
+const conflictWarnings = new Set<string>();
+
+/** Always warns, debug or not: a config conflict is a developer error. */
+const warnConflict = (
+  key: "enabled" | "expose",
+  legacyValue: boolean,
+  newValue: boolean,
+): void => {
+  const signature = `${key}:${legacyValue}:${newValue}`;
+  if (conflictWarnings.has(signature)) return;
+  conflictWarnings.add(signature);
+  console.warn(
+    `[persona] suggestions.followUps.${key} and features.suggestReplies.${key} disagree; suggestions.followUps.${key} wins.`,
+  );
+};
+
 /**
- * Gate for advertising the tool: `expose` opts it into the agent's catalog,
- * and `enabled !== false` guarantees the widget will actually auto-resolve
- * and render chips for it: exposing the tool with the feature disabled
- * would park the execution on a generic tool bubble with no resume coming.
+ * Single source of truth for the follow-ups capability flags. Resolution is
+ * per key so a `features.suggestReplies` embed that adds presentation-only
+ * `suggestions.followUps` keys is not silently re-enabled. `expose` is forced
+ * off when `enabled` resolves false: advertising the tool without the widget
+ * auto-resolving it parks the execution on a generic tool bubble.
  */
-export const shouldExposeSuggestReplies = (
+export const resolveFollowUpsFeature = (
   config: AgentWidgetConfig | undefined,
-): boolean => {
-  const feature = config?.features?.suggestReplies;
-  return feature?.expose === true && feature.enabled !== false;
+): ResolvedFollowUpsFeature => {
+  const followUps = config?.suggestions?.followUps;
+  const legacy = config?.features?.suggestReplies;
+  const warnIfConflicting = (key: "enabled" | "expose"): void => {
+    const newValue = followUps?.[key];
+    const legacyValue = legacy?.[key];
+    if (newValue === undefined || legacyValue === undefined) return;
+    if (newValue === legacyValue) return;
+    warnConflict(key, legacyValue, newValue);
+  };
+  if (config) {
+    warnIfConflicting("enabled");
+    warnIfConflicting("expose");
+  }
+  const enabled = followUps?.enabled ?? legacy?.enabled ?? true;
+  const expose = enabled
+    ? followUps?.expose ?? legacy?.expose ?? false
+    : false;
+  return { enabled, expose };
 };

package/src/theme-editor/index.ts

@@ -43,6 +43,8 @@ export {
   COMPONENT_COLOR_SECTIONS,
   CONFIGURE_SECTIONS,
   CONFIGURE_SUB_GROUPS,
+  STREAM_AND_ARTIFACTS_SUB_GROUP,
+  ARTIFACT_DISPLAY_PREFERENCE_SECTION,
   ALL_TABS,
   scopeSection,
   findSection,
@@ -90,6 +92,9 @@ export type {
   TranscriptStreamFrame,
   BuildTranscriptStreamFramesOptions,
 } from './preview-utils';
+// Type-only: the full preview implementation stays in
+// `@runtypelabs/persona/theme-editor/preview`.
+export type { CompareMode, PreviewShellMode } from './preview';
 
 // Role mappings (Interface Roles editor)
 export {

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import type { AgentWidgetConfig } from '../types';
+import { getActiveTheme, themeToCssVariables } from '../utils/theme';
+import { BUILT_IN_PRESETS, getThemeEditorPreset } from './presets';
+
+describe('theme editor presets', () => {
+  it('offers the paired Persona default before the single-scheme presets', () => {
+    const preset = getThemeEditorPreset('persona-default');
+
+    expect(BUILT_IN_PRESETS[0]).toBe(preset);
+    expect(preset).toMatchObject({
+      name: 'Persona Default',
+      tags: ['light', 'dark', 'adaptive'],
+      preview: { surface: '#ffffff' },
+      darkPreview: { surface: '#1f2937' },
+    });
+    expect(preset?.darkTheme).toBeDefined();
+  });
+
+  it('resolves the paired default to distinct light and dark surfaces', () => {
+    const preset = getThemeEditorPreset('persona-default')!;
+    const config = {
+      theme: preset.theme,
+      darkTheme: preset.darkTheme,
+    } as AgentWidgetConfig;
+
+    const light = themeToCssVariables(getActiveTheme({ ...config, colorScheme: 'light' }));
+    const dark = themeToCssVariables(getActiveTheme({ ...config, colorScheme: 'dark' }));
+
+    expect(light).toMatchObject({
+      '--persona-surface': '#f9fafb',
+      '--persona-background': '#f9fafb',
+      '--persona-text': '#111827',
+      '--persona-border': '#e5e7eb',
+    });
+    expect(dark).toMatchObject({
+      '--persona-surface': '#1f2937',
+      '--persona-background': '#111827',
+      '--persona-text': '#f3f4f6',
+      '--persona-border': '#374151',
+    });
+  });
+});