@runtypelabs/persona 4.21.1 → 4.22.1

package/dist/artifacts-ui.d.cts

@@ -621,7 +621,11 @@ interface ColorPalette {
     warning: ColorShade;
     error: ColorShade;
     info: ColorShade;
-    [key: string]: ColorShade;
+    /** Event-stream tool badge family. */
+    purple?: ColorShade;
+    /** Event-stream agent badge family. */
+    teal?: ColorShade;
+    [key: string]: ColorShade | undefined;
 }
 interface SpacingScale {
     0: string;
@@ -1193,6 +1197,38 @@ interface ToolBubbleTokens {
 interface ReasoningBubbleTokens {
     shadow: string;
 }
+/** One event-stream badge chip: fill + text pair. The chip border derives
+ * from `foreground` at ~31% alpha. */
+interface EventStreamBadgePairTokens {
+    background: TokenReference<'color'>;
+    foreground: TokenReference<'color'>;
+}
+/**
+ * Event-stream inspector badge chips (`features.eventStream`), one pair per
+ * unified event family. Materialized into every theme and emitted as
+ * `--persona-event-badge-<family>-{bg,fg}`, with scheme-appropriate defaults:
+ * light themes pair a 100-tone fill with a 700-tone text, the built-in dark
+ * layer flips to a 900-tone fill with a 300-tone text. `badge.default` colors
+ * event types no family matches.
+ */
+interface EventStreamTokens {
+    badge: {
+        /** `flow_*` events. */
+        flow: EventStreamBadgePairTokens;
+        /** `step_*` events. */
+        step: EventStreamBadgePairTokens;
+        /** `reasoning_*` events. */
+        reasoning: EventStreamBadgePairTokens;
+        /** `tool_*` events. */
+        tool: EventStreamBadgePairTokens;
+        /** `agent_*` events. */
+        agent: EventStreamBadgePairTokens;
+        /** `error` / `execution_error` events. */
+        error: EventStreamBadgePairTokens;
+        /** Any event type no other family matches. */
+        default: EventStreamBadgePairTokens;
+    };
+}
 /** Scrollbar appearance shared by every scroller in the widget. */
 interface ScrollbarTokens {
     /** Thumb color. @default semantic.colors.border */
@@ -1541,6 +1577,8 @@ interface ComponentTokens {
     attachment: AttachmentTokens;
     toolBubble: ToolBubbleTokens;
     reasoningBubble: ReasoningBubbleTokens;
+    /** Event-stream inspector badge chips. */
+    eventStream?: EventStreamTokens;
     composer: ComposerChromeTokens;
     /** Shared motion timing for composer chrome animation. */
     motion?: MotionTokens;
@@ -1658,6 +1696,11 @@ type RuntypeExecutionStreamEvent = ({
     iteration?: number;
     role: "user" | "assistant" | "system";
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     turnIndex?: number;
     type: "turn_start";
 }) | ({
@@ -1692,12 +1735,61 @@ type RuntypeExecutionStreamEvent = ({
     role: "user" | "assistant" | "system";
     seq: number;
     stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     tokens?: {
         input: number;
         output: number;
     };
     type: "turn_complete";
 }) | {
+    executionId: string;
+    id: string;
+    iteration?: number;
+    model?: string;
+    ordinal: number;
+    provider?: string;
+    seq: number;
+    startedAt?: string;
+    stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    turnId?: string;
+    type: "model_call_start";
+} | {
+    completedAt?: string;
+    cost?: number;
+    durationMs?: number;
+    executionId: string;
+    finishReason?: string;
+    id: string;
+    iteration?: number;
+    model?: string;
+    ordinal: number;
+    provider?: string;
+    responseModel?: string;
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    success?: boolean;
+    tokens?: {
+        cacheRead?: number;
+        cacheWrite?: number;
+        input: number;
+        output: number;
+    };
+    turnId?: string;
+    type: "model_call_complete";
+} | {
     executionId: string;
     id: string;
     index?: number;
@@ -1706,6 +1798,11 @@ type RuntypeExecutionStreamEvent = ({
     seq: number;
     startedAt?: string;
     stepType?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     totalSteps?: number;
     type: "step_start";
 } | ({
@@ -1733,6 +1830,11 @@ type RuntypeExecutionStreamEvent = ({
     seq: number;
     stepType?: string;
     stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     success?: boolean;
     tokensUsed?: number;
     type: "step_complete";
@@ -1755,6 +1857,11 @@ type RuntypeExecutionStreamEvent = ({
     role?: "user" | "assistant" | "system";
     seq: number;
     stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     turnId?: string;
     type: "text_start";
 }) | {
@@ -1762,11 +1869,21 @@ type RuntypeExecutionStreamEvent = ({
     executionId: string;
     id: string;
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     type: "text_delta";
 } | {
     executionId: string;
     id: string;
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     text?: string;
     type: "text_complete";
 } | ({
@@ -1775,18 +1892,33 @@ type RuntypeExecutionStreamEvent = ({
     parentToolCallId?: string;
     scope?: "turn" | "loop";
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     type: "reasoning_start";
 }) | {
     delta: string;
     executionId: string;
     id: string;
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     type: "reasoning_delta";
 } | ({
     executionId: string;
     id: string;
     scope?: "turn" | "loop";
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     text?: string;
     type: "reasoning_complete";
 }) | ({
@@ -1879,6 +2011,11 @@ type RuntypeExecutionStreamEvent = ({
     seq: number;
     startedAt?: string;
     stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     toolCallId: string;
     toolName: string;
     toolType: string;
@@ -1887,6 +2024,11 @@ type RuntypeExecutionStreamEvent = ({
     delta: string;
     executionId: string;
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     toolCallId: string;
     type: "tool_input_delta";
 } | {
@@ -1894,6 +2036,11 @@ type RuntypeExecutionStreamEvent = ({
     hiddenParameterNames?: Array<string>;
     parameters: Record<string, unknown>;
     seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     toolCallId: string;
     toolName?: string;
     type: "tool_input_complete";
@@ -1911,6 +2058,11 @@ type RuntypeExecutionStreamEvent = ({
     result?: unknown;
     seq: number;
     stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
     success: boolean;
     toolCallId: string;
     toolCost?: number;
@@ -1990,6 +2142,19 @@ type RuntypeExecutionStreamEvent = ({
     recoverable?: boolean;
     seq: number;
     type: "error";
+}) | ({
+    epoch: number;
+    executionId: string;
+    kind: "compaction";
+    outcome?: "ok" | "failed" | "gap" | "skipped";
+    phase: "start" | "complete";
+    reason: "threshold" | "overflow" | "manual" | "surface_policy" | "provider_mismatch";
+    seq: number;
+    strategy: "provider_native" | "summary";
+    tier: number;
+    tokensAfter?: number;
+    tokensBefore?: number;
+    type: "context_notice";
 }) | {
     executionId: string;
     seq: number;
@@ -2921,6 +3086,14 @@ type ClientToolDefinition = {
         readOnlyHint?: boolean;
         untrustedContentHint?: boolean;
     };
+    /**
+     * Hoisted copy of `annotations.untrustedContentHint`. This is the field the
+     * server actually acts on (`InlineClientToolSchema`): it spotlights the
+     * tool's output before the model reads it, so instructions embedded in
+     * page-provided content (reviews, comments, emails) are not treated as
+     * instructions. `annotations` itself is trace/dashboard metadata only.
+     */
+    untrustedContentHint?: boolean;
 };
 /**
  * Information passed to the confirm-bubble handler before a `webmcp:*` tool
@@ -3041,15 +3214,15 @@ type AgentMessageMetadata = {
      */
     parentStepId?: string;
     /**
-     * Set to `true` on a tool-variant message produced from a `step_await`
+     * Set to `true` on a tool-variant message produced from an `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;
     /**
-     * The provider per-call id (`toolu_…`) carried on the `step_await` /
-     * `flow_await` events for a LOCAL tool (core#3878). Present only when the
+     * The provider per-call id (`toolu_…`) carried on the `await`
+     * event for a LOCAL tool (core#3878). Present only when the
      * server emits it. Two PARALLEL calls to the same tool in one turn share a
      * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
      * so this is the key the widget batches a single `/resume` on: preferred
@@ -4112,6 +4285,16 @@ type AgentWidgetToolCallDisplayFeature = {
      * @default "stack"
      */
     groupedMode?: "stack" | "summary";
+    /**
+     * What happens to a tool call row once it completes.
+     *
+     * - `"kept"` (default): the finished row stays in the transcript.
+     * - `"removed"`: no row is rendered at all, so the transcript gap closes with
+     *   it. The tool call stays on the message and in `getMessages()`.
+     *
+     * @default "kept"
+     */
+    completedVisibility?: AgentWidgetToolCallCompletedVisibility;
     /**
      * When false, tool call bubbles show only the collapsed summary with no
      * expand/collapse toggle. Users see tool awareness without full details.
@@ -4129,6 +4312,8 @@ type AgentWidgetToolCallDisplayFeature = {
      */
     loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
+/** See `features.toolCallDisplay.completedVisibility`. */
+type AgentWidgetToolCallCompletedVisibility = "kept" | "removed";
 type AgentWidgetReasoningDisplayFeature = {
     /**
      * When true, active collapsed reasoning rows can render a lightweight preview block.
@@ -4174,13 +4359,26 @@ type AgentWidgetReasoningDisplayFeature = {
      * - `"kept"` (default): the finished row stays in the transcript.
      * - `"removed"`: no row is rendered at all, so the transcript gap closes with
      *   it. The reasoning text stays on the message and in `getMessages()`.
+     * - `"removed-when-short"`: behaves as `"removed"` when the completed trace
+     *   is short (see `shortThinkThreshold`), and as `"kept"` otherwise.
      *
      * @default "kept"
      */
     completedVisibility?: AgentWidgetReasoningCompletedVisibility;
+    /**
+     * Thresholds used by `completedVisibility: "removed-when-short"` to decide
+     * whether a completed trace counts as short. Duration is checked first when
+     * the reasoning reports one; the character count is a fallback for traces
+     * with no reported duration.
+     * @default { durationMs: 15000, chars: 1200 }
+     */
+    shortThinkThreshold?: {
+        durationMs?: number;
+        chars?: number;
+    };
 };
 /** See `features.reasoningDisplay.completedVisibility`. */
-type AgentWidgetReasoningCompletedVisibility = "kept" | "removed";
+type AgentWidgetReasoningCompletedVisibility = "kept" | "removed" | "removed-when-short";
 /**
  * Reveal animation applied to assistant message text while it is streaming.
  *
@@ -5174,7 +5372,7 @@ type EventStreamConfig = {
     /**
      * Custom badge color mappings by event type prefix or exact type.
      * Keys are matched as exact match first, then prefix match (keys ending with "_").
-     * @example { "flow_": { bg: "#dcfce7", text: "#166534" }, "error": { bg: "#fecaca", text: "#991b1b" } }
+     * @example { "execution_": { bg: "#dcfce7", text: "#166534" }, "error": { bg: "#fecaca", text: "#991b1b" } }
      */
     badgeColors?: Record<string, EventStreamBadgeColor>;
     /**
@@ -6595,9 +6793,13 @@ interface VoiceProvider {
      * `isFinal=false` is a live interim update (user partials, or assistant deltas
      * on providers that stream them); `isFinal=true` finalizes that role's text.
      * On the realtime `runtype` path, interim updates fire for the `user` only and
-     * the `assistant` arrives as a single final.
+     * the `assistant` arrives as a single final. Providers with overlapping turns
+     * must include the same turnId on user and assistant finals; without IDs,
+     * providers must discard cancelled output before emitting the next user final.
      */
-    onTranscript?(callback: (role: 'user' | 'assistant', text: string, isFinal: boolean) => void): void;
+    onTranscript?(callback: (role: 'user' | 'assistant', text: string, isFinal: boolean, metadata?: {
+        turnId?: string;
+    }) => void): void;
     /** Register a callback for per-turn latency metrics (realtime path). */
     onMetrics?(callback: (metrics: VoiceMetrics) => void): void;
     /**
@@ -8910,16 +9112,16 @@ type AgentWidgetConfig = {
      *
      * @example
      * ```typescript
-     * // For Runtype API format
+     * // For a custom backend (Runtype unified events are handled natively)
      * config: {
      *   parseSSEEvent: (data) => {
-     *     if ((data.type === 'step_delta' || data.type === 'step_chunk') && (data.delta || data.chunk)) {
-     *       return { text: data.delta ?? data.chunk };
+     *     if (data.type === 'token' && typeof data.value === 'string') {
+     *       return { text: data.value };
      *     }
-     *     if (data.type === 'flow_complete') {
+     *     if (data.type === 'done') {
      *       return { done: true };
      *     }
-     *     if (data.type === 'step_error') {
+     *     if (data.type === 'failure') {
      *       return { error: data.error };
      *     }
      *     return null; // Ignore other events
@@ -9110,7 +9312,7 @@ type AgentWidgetReasoning = {
     /**
      * Reasoning channel scope (wire spec). `"turn"` is ordinary per-turn
      * thinking; `"loop"` is a cross-iteration agent reflection (the fold that
-     * replaced the legacy `agent_reflection` event). Absent for legacy streams.
+     * replaced the legacy `agent_reflection` event). Optional when the stream does not specify a scope.
      */
     scope?: "turn" | "loop";
     startedAt?: number;
@@ -9124,6 +9326,9 @@ type AgentWidgetToolCall = {
     args?: unknown;
     chunks?: string[];
     result?: unknown;
+    /** Whether the tool succeeded; failure does not necessarily end the execution. */
+    success?: boolean;
+    error?: string;
     duration?: number;
     startedAt?: number;
     completedAt?: number;
@@ -9154,7 +9359,7 @@ type AgentWidgetApproval = {
 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
+ * `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)
@@ -9285,7 +9490,7 @@ type AgentWidgetMessage = {
      */
     agentMetadata?: AgentMessageMetadata;
     /**
-     * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+     * Per-turn stop reason reported by the runtime on `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.
      *