@runtypelabs/persona 3.17.0 → 3.18.0

package/dist/theme-editor.d.cts

@@ -217,6 +217,18 @@ interface MessageTokens {
     /** Border color between messages in the thread. */
     border?: TokenReference<'color'>;
 }
+/**
+ * Welcome / intro card rendered above the message list when no messages exist.
+ * Set `copy.showWelcomeCard: false` to hide it; use `layout.slots["body-top"]`
+ * to replace it wholesale.
+ */
+interface IntroCardTokens extends ComponentTokenSet {
+    background?: TokenReference<'color'>;
+    borderRadius?: TokenReference<'radius'>;
+    padding?: TokenReference<'spacing'>;
+    /** Box-shadow on the intro card (token ref or raw CSS, e.g. `none`). */
+    shadow?: string;
+}
 /** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
 interface CollapsibleWidgetTokens {
     /** Background for content areas. */
@@ -414,6 +426,8 @@ interface ComponentTokens {
     panel: PanelTokens;
     header: HeaderTokens;
     message: MessageTokens;
+    /** Welcome / intro card shown above the message list. */
+    introCard?: IntroCardTokens;
     /** Markdown surfaces (chat + artifact pane). */
     markdown?: MarkdownTokens;
     voice: VoiceTokens;
@@ -558,6 +572,61 @@ interface AgentWidgetPlugin {
         defaultRenderer: () => HTMLElement;
         config: AgentWidgetConfig;
     }) => HTMLElement | null;
+    /**
+     * Custom renderer for `ask_user_question` tool calls.
+     *
+     * When a plugin returns an `HTMLElement`, it is inserted into the transcript
+     * in place of the default (which is no transcript bubble — the built-in
+     * renders a sheet over the composer). The built-in composer-overlay sheet
+     * is suppressed so the plugin's UI fully owns the interaction.
+     *
+     * Return `null` to fall through to the built-in overlay sheet.
+     *
+     * The context gives you a pre-parsed `payload` (may be partial while the
+     * tool call is still streaming — check `complete`) and two callbacks:
+     * `resolve(answer)` resumes the paused LOCAL tool with the user's answer,
+     * and `dismiss()` cancels with the sentinel `"(dismissed)"`.
+     *
+     * @example
+     * ```typescript
+     * renderAskUserQuestion: ({ payload, resolve, dismiss }) => {
+     *   const prompt = payload.questions?.[0];
+     *   if (!prompt) return null;
+     *   const root = document.createElement("div");
+     *   root.textContent = prompt.question ?? "";
+     *   (prompt.options ?? []).forEach((option) => {
+     *     const btn = document.createElement("button");
+     *     btn.textContent = option.label;
+     *     btn.addEventListener("click", () => resolve(option.label));
+     *     root.appendChild(btn);
+     *   });
+     *   return root;
+     * }
+     * ```
+     */
+    renderAskUserQuestion?: (context: {
+        message: AgentWidgetMessage;
+        /**
+         * Parsed `{ questions: [...] }` payload. May be partial while the tool
+         * call is still streaming; see `complete`. `null` when no payload has
+         * arrived yet.
+         */
+        payload: Partial<AskUserQuestionPayload> | null;
+        /** `true` once the tool-call args have fully streamed in. */
+        complete: boolean;
+        /**
+         * Resume the paused LOCAL tool with the user's answer. Posts to the
+         * resume endpoint, pipes the SSE stream back into the session, and
+         * appends a user-visible answer bubble to the transcript.
+         */
+        resolve: (answer: string) => void;
+        /**
+         * Cancel the question. Resumes with the sentinel `"(dismissed)"` so the
+         * server doesn't sit in `waiting_for_local` forever. Idempotent.
+         */
+        dismiss: () => void;
+        config: AgentWidgetConfig;
+    }) => HTMLElement | null;
     /**
      * Custom renderer for approval bubbles
      * Return null to use default renderer
@@ -778,6 +847,31 @@ 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;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -825,6 +919,8 @@ type AgentWidgetActionHandler = (action: AgentWidgetParsedAction, context: Agent
 type AgentWidgetStoredState = {
     messages?: AgentWidgetMessage[];
     metadata?: Record<string, unknown>;
+    artifacts?: PersonaArtifactRecord[];
+    selectedArtifactId?: string | null;
 };
 interface AgentWidgetStorageAdapter {
     load?: () => AgentWidgetStoredState | null | Promise<AgentWidgetStoredState | null>;
@@ -1382,6 +1478,113 @@ type AgentWidgetFeatureFlags = {
     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.
+ */
+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.
+ */
+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. */
+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.
+ */
+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.
+ */
+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;
 };
 type SSEEventRecord = {
     id: string;
@@ -3121,6 +3324,17 @@ 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;
@@ -4191,6 +4405,10 @@ type Controller = {
     upsertArtifact: (manual: PersonaArtifactManualUpsert) => PersonaArtifactRecord | null;
     selectArtifact: (id: string) => void;
     clearArtifacts: () => void;
+    /** Read current artifacts (useful on init to rebuild host-side tab state after hydration). */
+    getArtifacts: () => PersonaArtifactRecord[];
+    /** Read the currently selected artifact id (paired with `getArtifacts`). */
+    getSelectedArtifactId: () => string | null;
     /**
      * Focus the chat input. Returns true if focus succeeded, false if panel is closed
      * (launcher mode) or textarea is unavailable.

package/dist/theme-editor.d.ts

@@ -217,6 +217,18 @@ interface MessageTokens {
     /** Border color between messages in the thread. */
     border?: TokenReference<'color'>;
 }
+/**
+ * Welcome / intro card rendered above the message list when no messages exist.
+ * Set `copy.showWelcomeCard: false` to hide it; use `layout.slots["body-top"]`
+ * to replace it wholesale.
+ */
+interface IntroCardTokens extends ComponentTokenSet {
+    background?: TokenReference<'color'>;
+    borderRadius?: TokenReference<'radius'>;
+    padding?: TokenReference<'spacing'>;
+    /** Box-shadow on the intro card (token ref or raw CSS, e.g. `none`). */
+    shadow?: string;
+}
 /** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
 interface CollapsibleWidgetTokens {
     /** Background for content areas. */
@@ -414,6 +426,8 @@ interface ComponentTokens {
     panel: PanelTokens;
     header: HeaderTokens;
     message: MessageTokens;
+    /** Welcome / intro card shown above the message list. */
+    introCard?: IntroCardTokens;
     /** Markdown surfaces (chat + artifact pane). */
     markdown?: MarkdownTokens;
     voice: VoiceTokens;
@@ -558,6 +572,61 @@ interface AgentWidgetPlugin {
         defaultRenderer: () => HTMLElement;
         config: AgentWidgetConfig;
     }) => HTMLElement | null;
+    /**
+     * Custom renderer for `ask_user_question` tool calls.
+     *
+     * When a plugin returns an `HTMLElement`, it is inserted into the transcript
+     * in place of the default (which is no transcript bubble — the built-in
+     * renders a sheet over the composer). The built-in composer-overlay sheet
+     * is suppressed so the plugin's UI fully owns the interaction.
+     *
+     * Return `null` to fall through to the built-in overlay sheet.
+     *
+     * The context gives you a pre-parsed `payload` (may be partial while the
+     * tool call is still streaming — check `complete`) and two callbacks:
+     * `resolve(answer)` resumes the paused LOCAL tool with the user's answer,
+     * and `dismiss()` cancels with the sentinel `"(dismissed)"`.
+     *
+     * @example
+     * ```typescript
+     * renderAskUserQuestion: ({ payload, resolve, dismiss }) => {
+     *   const prompt = payload.questions?.[0];
+     *   if (!prompt) return null;
+     *   const root = document.createElement("div");
+     *   root.textContent = prompt.question ?? "";
+     *   (prompt.options ?? []).forEach((option) => {
+     *     const btn = document.createElement("button");
+     *     btn.textContent = option.label;
+     *     btn.addEventListener("click", () => resolve(option.label));
+     *     root.appendChild(btn);
+     *   });
+     *   return root;
+     * }
+     * ```
+     */
+    renderAskUserQuestion?: (context: {
+        message: AgentWidgetMessage;
+        /**
+         * Parsed `{ questions: [...] }` payload. May be partial while the tool
+         * call is still streaming; see `complete`. `null` when no payload has
+         * arrived yet.
+         */
+        payload: Partial<AskUserQuestionPayload> | null;
+        /** `true` once the tool-call args have fully streamed in. */
+        complete: boolean;
+        /**
+         * Resume the paused LOCAL tool with the user's answer. Posts to the
+         * resume endpoint, pipes the SSE stream back into the session, and
+         * appends a user-visible answer bubble to the transcript.
+         */
+        resolve: (answer: string) => void;
+        /**
+         * Cancel the question. Resumes with the sentinel `"(dismissed)"` so the
+         * server doesn't sit in `waiting_for_local` forever. Idempotent.
+         */
+        dismiss: () => void;
+        config: AgentWidgetConfig;
+    }) => HTMLElement | null;
     /**
      * Custom renderer for approval bubbles
      * Return null to use default renderer
@@ -778,6 +847,31 @@ 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;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -825,6 +919,8 @@ type AgentWidgetActionHandler = (action: AgentWidgetParsedAction, context: Agent
 type AgentWidgetStoredState = {
     messages?: AgentWidgetMessage[];
     metadata?: Record<string, unknown>;
+    artifacts?: PersonaArtifactRecord[];
+    selectedArtifactId?: string | null;
 };
 interface AgentWidgetStorageAdapter {
     load?: () => AgentWidgetStoredState | null | Promise<AgentWidgetStoredState | null>;
@@ -1382,6 +1478,113 @@ type AgentWidgetFeatureFlags = {
     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.
+ */
+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.
+ */
+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. */
+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.
+ */
+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.
+ */
+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;
 };
 type SSEEventRecord = {
     id: string;
@@ -3121,6 +3324,17 @@ 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;
@@ -4191,6 +4405,10 @@ type Controller = {
     upsertArtifact: (manual: PersonaArtifactManualUpsert) => PersonaArtifactRecord | null;
     selectArtifact: (id: string) => void;
     clearArtifacts: () => void;
+    /** Read current artifacts (useful on init to rebuild host-side tab state after hydration). */
+    getArtifacts: () => PersonaArtifactRecord[];
+    /** Read the currently selected artifact id (paired with `getArtifacts`). */
+    getSelectedArtifactId: () => string | null;
     /**
      * Focus the chat input. Returns true if focus succeeded, false if panel is closed
      * (launcher mode) or textarea is unavailable.