@runtypelabs/persona 3.16.0 → 3.18.0

package/src/types.ts

@@ -205,6 +205,31 @@ export type AgentMessageMetadata = {
    * or `prompt` step inside the nested flow). Stable key for that step.
    */
   parentStepId?: string;
+  /**
+   * Set to `true` on a tool-variant message produced from a `step_await`
+   * event (`awaitReason: "local_tool_required"`). Signals to UI code that
+   * the tool call is a LOCAL tool and the server is paused waiting for a
+   * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
+   */
+  awaitingLocalTool?: boolean;
+  /**
+   * Set to `true` once the user has picked / typed / dismissed an answer for
+   * an `ask_user_question` tool call, so renderers stop re-mounting the
+   * answer-pill sheet for this tool call on subsequent render passes.
+   */
+  askUserQuestionAnswered?: boolean;
+  /**
+   * In-progress answers for a multi-question `ask_user_question` payload,
+   * keyed by question text. Persisted across refresh so the user lands back
+   * where they were if the page reloads mid-flow. Cleared once
+   * `askUserQuestionAnswered` flips to `true`.
+   */
+  askUserQuestionAnswers?: Record<string, string | string[]>;
+  /**
+   * Current page index for a multi-question `ask_user_question` payload's
+   * paginated stepper. Persists alongside `askUserQuestionAnswers`.
+   */
+  askUserQuestionIndex?: number;
 };
 
 export type AgentWidgetRequestMiddlewareContext = {
@@ -270,6 +295,8 @@ export type AgentWidgetActionHandler = (
 export type AgentWidgetStoredState = {
   messages?: AgentWidgetMessage[];
   metadata?: Record<string, unknown>;
+  artifacts?: PersonaArtifactRecord[];
+  selectedArtifactId?: string | null;
 };
 
 export interface AgentWidgetStorageAdapter {
@@ -680,6 +707,167 @@ export type AgentWidgetReasoningDisplayFeature = {
   loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
 
+/**
+ * Reveal animation applied to assistant message text while it is streaming.
+ *
+ * Built-in types always available:
+ * - `none` — text appears as tokens arrive (default).
+ * - `typewriter` — characters fade in with a blinking caret.
+ * - `pop-bubble` — the bubble scales in; text streams normally afterward.
+ * - `letter-rise` — per-char translateY + fade reveal.
+ * - `word-fade` — per-word blur + translateY fade-in.
+ *
+ * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
+ * - `wipe`, `glyph-cycle`.
+ *
+ * Custom types are allowed — register a plugin with any string name and
+ * reference it by that name in `type`.
+ */
+export type AgentWidgetStreamAnimationBuiltinType =
+  | "none"
+  | "typewriter"
+  | "word-fade"
+  | "letter-rise"
+  | "glyph-cycle"
+  | "wipe"
+  | "pop-bubble";
+
+export type AgentWidgetStreamAnimationType =
+  | AgentWidgetStreamAnimationBuiltinType
+  | (string & {});
+
+/**
+ * Placeholder shown inside a streaming assistant bubble before the first token arrives.
+ * - `none` — use the default typing-dots indicator (existing behavior).
+ * - `skeleton` — shimmer bars, replaced by streaming content once it starts.
+ */
+export type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
+
+/**
+ * How much of the accumulated streaming content to display while tokens are
+ * still arriving. Trimming to a boundary means in-progress words or lines
+ * stay hidden until they complete — useful for animations that benefit from
+ * unit-complete reveals (e.g. wipe, glyph-cycle).
+ * - `none` — show every character as it arrives (default).
+ * - `word` — trim to the last whitespace boundary.
+ * - `line` — trim to the last newline boundary.
+ */
+export type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
+
+/**
+ * Context passed to plugin lifecycle hooks. Carries the live DOM references
+ * and resolved animation settings for the currently-streaming message.
+ */
+export type StreamAnimationContext = {
+  /** The `.persona-message-content` element owning the streamed text. */
+  container: HTMLElement;
+  /** The outer message bubble element. */
+  bubble: HTMLElement;
+  /** ID of the streaming message. */
+  messageId: string;
+  /** Read-only reference to the message being streamed. */
+  message: AgentWidgetMessage;
+  /** Effective `speed` from `streamAnimation.speed`. */
+  speed: number;
+  /** Effective `duration` from `streamAnimation.duration`. */
+  duration: number;
+};
+
+/**
+ * Pluggable stream animation. Third-party packages and inline registrations
+ * implement this interface to add custom reveal effects.
+ *
+ * Lifecycle:
+ * - When the widget mounts and detects a plugin (either passed via config or
+ *   auto-registered in the IIFE bundle), it injects `styles` once into the
+ *   widget's style host.
+ * - For each streaming assistant message whose `type` matches `name`, the
+ *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
+ *   and — if `useCaret` is true — appends a blinking caret.
+ * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
+ *   and `data-preserve-animation` to safely mutate per-char or per-word spans
+ *   without idiomorph clobbering in-flight work.
+ */
+export type StreamAnimationPlugin = {
+  /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
+  name: string;
+  /** Class added to `.persona-message-content` while streaming. */
+  containerClass?: string;
+  /** Class added to the bubble element (e.g. a one-shot scale animation). */
+  bubbleClass?: string;
+  /** Wrap mode applied to text nodes during streaming. @default "none" */
+  wrap?: "none" | "char" | "word";
+  /**
+   * HTML tags whose descendant text is skipped during wrapping. Defaults to
+   * `["pre", "code", "a", "script", "style"]` — useful for keeping code
+   * blocks legible and link click-targets intact. Plugins that want to
+   * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
+   * the list.
+   */
+  skipTags?: string[];
+  /** Append a blinking caret after the last rendered char/word. */
+  useCaret?: boolean;
+  /** CSS string injected into the widget style host on first activation. */
+  styles?: string;
+  /**
+   * Optional custom buffering strategy. Returns the portion of `content`
+   * that should be rendered during streaming. Use this for buffering
+   * schemes beyond the built-in `word` / `line` strategies.
+   */
+  bufferContent?: (content: string, message: AgentWidgetMessage) => string;
+  /**
+   * Fires once when the plugin is first activated inside a widget instance.
+   * Use this to set up MutationObservers or other long-lived listeners.
+   * Return an optional cleanup function that runs on widget destroy.
+   */
+  onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
+  /** Fires after each render that reaches the live DOM. */
+  onAfterRender?: (ctx: StreamAnimationContext) => void;
+  /** Fires when a streamed message's `streaming` flag flips to false. */
+  onStreamComplete?: (ctx: StreamAnimationContext) => void;
+  /**
+   * Report whether the plugin still has in-flight animation work for a
+   * message. When `true`, the widget keeps rendering the message in its
+   * "streaming-animated" mode even after `message.streaming` flips false —
+   * preventing the final non-animated render from yanking the rug out from
+   * under unfinished per-char cycles or reveals.
+   */
+  isAnimating?: (message: AgentWidgetMessage) => boolean;
+};
+
+export type AgentWidgetStreamAnimationFeature = {
+  /** Reveal animation to apply while streaming. @default "none" */
+  type?: AgentWidgetStreamAnimationType;
+  /** Pre-first-token placeholder. @default "none" */
+  placeholder?: AgentWidgetStreamAnimationPlaceholder;
+  /**
+   * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
+   * and per-unit plugin animations. Each arriving character/word animates from
+   * invisible to visible over this duration, independent of its position — the
+   * streaming cadence itself provides the visible stagger.
+   * @default 120
+   */
+  speed?: number;
+  /**
+   * Total duration of container-level animations (`pop-bubble` and custom
+   * plugin animations), in milliseconds.
+   * @default 1800
+   */
+  duration?: number;
+  /**
+   * Trim the accumulated streaming content to a word or line boundary before
+   * rendering. Hides in-progress units until they complete.
+   * @default "none"
+   */
+  buffer?: AgentWidgetStreamAnimationBuffer;
+  /**
+   * Extra animation plugins available to this widget instance. Keys are
+   * plugin names; the matching plugin activates when `type` is set to that
+   * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
+   */
+  plugins?: Record<string, StreamAnimationPlugin>;
+};
+
 export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
@@ -694,6 +882,120 @@ export type AgentWidgetFeatureFlags = {
   eventStream?: EventStreamConfig;
   /** Optional artifact sidebar (split pane / mobile drawer) */
   artifacts?: AgentWidgetArtifactsFeature;
+  /** Reveal animation for streaming assistant text. */
+  streamAnimation?: AgentWidgetStreamAnimationFeature;
+  /**
+   * Built-in interactive answer-pill sheet shown when the assistant invokes
+   * the `ask_user_question` tool. Slides up over the composer with tappable
+   * pills + optional free-text input.
+   */
+  askUserQuestion?: AgentWidgetAskUserQuestionFeature;
+};
+
+/**
+ * Single selectable option in an `ask_user_question` prompt.
+ * Mirrors Anthropic's AskUserQuestion schema.
+ */
+export type AskUserQuestionOption = {
+  /** Pill label (required). */
+  label: string;
+  /** Optional long-form description (shown as a subtitle on tap-hover). */
+  description?: string;
+  /** Optional rich preview — reserved for future rendering; ignored in v1. */
+  preview?: string;
+};
+
+/**
+ * A single question in an `ask_user_question` tool call.
+ * The tool may carry 1–8 prompts. When more than one is supplied, the built-in
+ * renderer paginates them as a "Question N of M" stepper with Back / Next /
+ * Submit-all controls; single-question payloads render without stepper chrome.
+ */
+export type AskUserQuestionPrompt = {
+  /** The question text shown to the user. */
+  question: string;
+  /** Optional short header label (≤12 chars) used as a compact group title. */
+  header?: string;
+  /** 2–4 selectable options. */
+  options: AskUserQuestionOption[];
+  /** When true, the user can pick multiple options and submit together. Default false. */
+  multiSelect?: boolean;
+  /** When true, a free-text "Other…" pill expands to an input. Default true. */
+  allowFreeText?: boolean;
+};
+
+/** Parsed payload of an `ask_user_question` tool call. */
+export type AskUserQuestionPayload = {
+  /** 1–8 questions. Anything beyond the renderer's cap is truncated with a console warning. */
+  questions: AskUserQuestionPrompt[];
+};
+
+/**
+ * Style overrides for the answer-pill sheet. All values are raw CSS strings
+ * and are plumbed through as CSS custom properties on the sheet root.
+ */
+export type AgentWidgetAskUserQuestionStyles = {
+  sheetBackground?: string;
+  sheetBorder?: string;
+  sheetShadow?: string;
+  pillBackground?: string;
+  pillBackgroundSelected?: string;
+  pillTextColor?: string;
+  pillTextColorSelected?: string;
+  pillBorderRadius?: string;
+  customInputBackground?: string;
+};
+
+/**
+ * Feature config for the built-in `ask_user_question` answer-pill sheet.
+ * When a tool call with the name `ask_user_question` arrives, the widget
+ * renders an interactive sheet over the composer in place of the generic
+ * tool bubble.
+ */
+export type AgentWidgetAskUserQuestionFeature = {
+  /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
+  enabled?: boolean;
+  /** Slide-in animation duration in ms. Defaults to 180. */
+  slideInMs?: number;
+  /** Label for the free-text pill. Defaults to "Other…". */
+  freeTextLabel?: string;
+  /** Placeholder text in the free-text input. Defaults to "Type your answer…". */
+  freeTextPlaceholder?: string;
+  /** Button label for submitting multi-select / free-text answers. Defaults to "Send". */
+  submitLabel?: string;
+  /** Button label advancing to the next question in grouped (paginated) payloads. Defaults to "Next". */
+  nextLabel?: string;
+  /** Button label moving back to the previous question in grouped payloads. Defaults to "Back". */
+  backLabel?: string;
+  /** Button label submitting all answers from the final page of a grouped payload. Defaults to "Submit all". */
+  submitAllLabel?: string;
+  /**
+   * In grouped (multi-question) mode, auto-advance to the next page after a
+   * single-select pill pick or free-text submit on intermediate pages.
+   * Defaults to `true`. The final page never auto-submits — users always
+   * confirm with an explicit "Submit all" click. Multi-select pages always
+   * require an explicit Next regardless of this setting.
+   */
+  groupedAutoAdvance?: boolean;
+  /**
+   * Visual layout for the option list.
+   * - `"rows"` (default) — full-width stacked rows with always-visible
+   *   descriptions, right-edge number badges (single-select) or checkboxes
+   *   (multi-select), and an always-visible inline "Other" input.
+   * - `"pills"` — legacy compact pill list with horizontal wrap; description
+   *   surfaces as a tooltip and the "Other…" pill expands on click.
+   */
+  layout?: "rows" | "pills";
+  /**
+   * Button label for skipping the current question in grouped payloads.
+   * Defaults to "Skip". On intermediate pages Skip advances without recording
+   * an answer; on the final page Skip submits the partial answer record
+   * (skipped questions absent from the resolved object). For single-question
+   * payloads Skip behaves like dismiss.
+   */
+  skipLabel?: string;
+  /** Style overrides for the sheet and pills. */
+  styles?: AgentWidgetAskUserQuestionStyles;
 };
 
 export type SSEEventRecord = {
@@ -996,6 +1298,10 @@ export type AgentWidgetSendButtonConfig = {
   backgroundColor?: string;
   textColor?: string;
   size?: string;
+  /** Lucide icon name shown while a response is streaming. Clicking the button in this state aborts the stream. Default: "square". */
+  stopIconName?: string;
+  /** Tooltip text shown while streaming. Default: "Stop generating". */
+  stopTooltipText?: string;
 };
 
 /** Optional composer UI state for custom `renderComposer` implementations. */
@@ -2608,11 +2914,21 @@ export type AgentWidgetConfig = {
     welcomeSubtitle?: string;
     inputPlaceholder?: string;
     sendButtonLabel?: string;
+    /** Button label shown in text mode while a response is streaming. Default: "Stop". */
+    stopButtonLabel?: string;
     /**
      * When false, the welcome / intro card is not shown above the message list.
      * @default true
      */
     showWelcomeCard?: boolean;
+    /**
+     * Per-stop-reason copy for the inline notice rendered on assistant
+     * bubbles when the runtime reports a non-natural stop (e.g. the agent
+     * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
+     * optional — keys you omit fall back to the built-in defaults. Set a
+     * key to an empty string to suppress the notice for that reason.
+     */
+    stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
   };
   /**
    * Semantic design tokens (`palette`, `semantic`, `components`).
@@ -2646,6 +2962,17 @@ export type AgentWidgetConfig = {
   autoFocusInput?: boolean;
   launcher?: AgentWidgetLauncherConfig;
   initialMessages?: AgentWidgetMessage[];
+  /**
+   * Artifacts to hydrate into the pane at init. Typically populated from
+   * `storageAdapter.load()` alongside `initialMessages` so the artifact pane
+   * survives a page refresh.
+   */
+  initialArtifacts?: PersonaArtifactRecord[];
+  /**
+   * Which artifact id (if any) should be selected in the pane at init. Paired
+   * with `initialArtifacts`.
+   */
+  initialSelectedArtifactId?: string | null;
   suggestionChips?: string[];
   suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
   debug?: boolean;
@@ -3121,6 +3448,28 @@ export type AgentWidgetApproval = {
 
 export type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
 
+/**
+ * Per-turn / per-step stop reason emitted by the runtime on
+ * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
+ * owned by the upstream Runtype API — do not extend without coordination.
+ *
+ * - `end_turn` — natural completion (no affordance needed)
+ * - `max_tool_calls` — agent loop tripped the configured tool-call ceiling
+ * - `length` — provider hit max output tokens
+ * - `content_filter` — provider content filter intervened
+ * - `error` — provider/runtime error (prefer existing error rendering)
+ * - `unknown` — explicitly reported but uninformative
+ *
+ * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
+ */
+export type StopReasonKind =
+  | 'end_turn'
+  | 'max_tool_calls'
+  | 'length'
+  | 'content_filter'
+  | 'error'
+  | 'unknown';
+
 /**
  * Represents a message in the chat conversation.
  *
@@ -3207,6 +3556,17 @@ export type AgentWidgetMessage = {
    * Contains execution context like iteration number and turn ID.
    */
   agentMetadata?: AgentMessageMetadata;
+  /**
+   * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+   * (agent-loop path) or the last `step_complete` for a prompt step
+   * (dispatch / flow path). Absent when the API did not report a value.
+   *
+   * When set to a non-natural value (`max_tool_calls`, `length`,
+   * `content_filter`, `error`), the widget renders an inline notice on
+   * the assistant bubble. See `config.copy.stopReasonNotice` to override
+   * the default copy.
+   */
+  stopReason?: StopReasonKind;
 };
 
 // ============================================================================