@vellumai/plugin-api 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/index.d.ts

@@ -245,15 +245,15 @@ declare const AssistantActivityStateEventSchema: z.ZodObject<{
     reason: z.ZodEnum<{
         thinking_delta: "thinking_delta";
         generation_cancelled: "generation_cancelled";
+        tool_use_start: "tool_use_start";
+        message_complete: "message_complete";
         message_dequeued: "message_dequeued";
         first_text_delta: "first_text_delta";
-        tool_use_start: "tool_use_start";
         preview_start: "preview_start";
         tool_result_received: "tool_result_received";
         confirmation_requested: "confirmation_requested";
         confirmation_resolved: "confirmation_resolved";
         context_compacting: "context_compacting";
-        message_complete: "message_complete";
         error_terminal: "error_terminal";
     }>;
     requestId: z.ZodOptional<z.ZodString>;
@@ -304,8 +304,12 @@ declare const AssistantConfigSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         stt: z.ZodDefault<z.ZodObject<{
-            mode: z.ZodDefault<z.ZodLiteral<"your-own">>;
+            mode: z.ZodDefault<z.ZodEnum<{
+                managed: "managed";
+                "your-own": "your-own";
+            }>>;
             provider: z.ZodEnum<{
+                vellum: "vellum";
                 deepgram: "deepgram";
                 "google-gemini": "google-gemini";
                 "openai-whisper": "openai-whisper";
@@ -314,8 +318,12 @@ declare const AssistantConfigSchema: z.ZodObject<{
             providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
         }, z.core.$strip>>;
         tts: z.ZodDefault<z.ZodObject<{
-            mode: z.ZodDefault<z.ZodLiteral<"your-own">>;
+            mode: z.ZodDefault<z.ZodEnum<{
+                managed: "managed";
+                "your-own": "your-own";
+            }>>;
             provider: z.ZodDefault<z.ZodEnum<{
+                vellum: "vellum";
                 deepgram: "deepgram";
                 xai: "xai";
                 elevenlabs: "elevenlabs";
@@ -362,6 +370,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
                     sampleRate: z.ZodDefault<z.ZodNumber>;
                     bitRate: z.ZodDefault<z.ZodNumber>;
                 }, z.core.$strip>>;
+                vellum: z.ZodDefault<z.ZodObject<{}, z.core.$strip>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         "google-oauth": z.ZodDefault<z.ZodObject<{
@@ -526,9 +535,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
             fastConcurrency?: number | undefined;
             embedConcurrency?: number | undefined;
         }>>>;
-        worker: z.ZodDefault<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-        }, z.core.$strip>>;
         retention: z.ZodDefault<z.ZodObject<{
             keepRawForever: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>;
@@ -661,6 +667,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             minCooldownMs: z.ZodDefault<z.ZodNumber>;
             keepSupersededRuns: z.ZodDefault<z.ZodBoolean>;
             matchConversationProfile: z.ZodDefault<z.ZodBoolean>;
+            promptPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     monitoring: z.ZodDefault<z.ZodObject<{
@@ -671,11 +678,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
         pluginSourceScanIntervalMs: z.ZodDefault<z.ZodNumber>;
         baselineSnapshotIntervalMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
-    schedules: z.ZodDefault<z.ZodObject<{
-        worker: z.ZodDefault<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>>;
     migrations: z.ZodDefault<z.ZodObject<{
         worker: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -708,82 +710,6 @@ declare const AssistantConfigSchema: z.ZodObject<{
         retentionDays: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     llm: z.ZodDefault<z.ZodObject<{
-        default: z.ZodDefault<z.ZodObject<{
-            provider: z.ZodDefault<z.ZodEnum<{
-                anthropic: "anthropic";
-                openai: "openai";
-                gemini: "gemini";
-                fireworks: "fireworks";
-                openrouter: "openrouter";
-                ollama: "ollama";
-                "vercel-ai-gateway": "vercel-ai-gateway";
-                "openai-compatible": "openai-compatible";
-                minimax: "minimax";
-                atlascloud: "atlascloud";
-                together: "together";
-            }>>;
-            provider_connection: z.ZodOptional<z.ZodString>;
-            model: z.ZodDefault<z.ZodString>;
-            maxTokens: z.ZodDefault<z.ZodNumber>;
-            effort: z.ZodDefault<z.ZodEnum<{
-                low: "low";
-                medium: "medium";
-                high: "high";
-                none: "none";
-                xhigh: "xhigh";
-                max: "max";
-            }>>;
-            speed: z.ZodDefault<z.ZodEnum<{
-                standard: "standard";
-                fast: "fast";
-            }>>;
-            verbosity: z.ZodDefault<z.ZodEnum<{
-                low: "low";
-                medium: "medium";
-                high: "high";
-            }>>;
-            temperature: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
-            topP: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
-            thinking: z.ZodDefault<z.ZodObject<{
-                enabled: z.ZodDefault<z.ZodBoolean>;
-                streamThinking: z.ZodDefault<z.ZodBoolean>;
-                level: z.ZodOptional<z.ZodEnum<{
-                    low: "low";
-                    medium: "medium";
-                    high: "high";
-                    minimal: "minimal";
-                }>>;
-            }, z.core.$strip>>;
-            contextWindow: z.ZodDefault<z.ZodObject<{
-                enabled: z.ZodDefault<z.ZodBoolean>;
-                maxInputTokens: z.ZodDefault<z.ZodNumber>;
-                targetBudgetRatio: z.ZodDefault<z.ZodNumber>;
-                compactThreshold: z.ZodDefault<z.ZodNumber>;
-                summaryBudgetRatio: z.ZodDefault<z.ZodNumber>;
-                overflowRecovery: z.ZodDefault<z.ZodObject<{
-                    enabled: z.ZodDefault<z.ZodBoolean>;
-                    safetyMarginRatio: z.ZodDefault<z.ZodNumber>;
-                    maxAttempts: z.ZodDefault<z.ZodNumber>;
-                    interactiveLatestTurnCompression: z.ZodDefault<z.ZodEnum<{
-                        truncate: "truncate";
-                        summarize: "summarize";
-                        drop: "drop";
-                    }>>;
-                    nonInteractiveLatestTurnCompression: z.ZodDefault<z.ZodEnum<{
-                        truncate: "truncate";
-                        summarize: "summarize";
-                        drop: "drop";
-                    }>>;
-                }, z.core.$strip>>;
-            }, z.core.$strip>>;
-            openrouter: z.ZodDefault<z.ZodObject<{
-                only: z.ZodDefault<z.ZodArray<z.ZodString>>;
-            }, z.core.$strip>>;
-            logitBias: z.ZodOptional<z.ZodEnum<{
-                "suppress-cjk": "suppress-cjk";
-            }>>;
-            disableCache: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip>>;
         profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
             provider: z.ZodOptional<z.ZodEnum<{
                 anthropic: "anthropic";
@@ -1131,10 +1057,10 @@ declare const AssistantConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
         install: z.ZodDefault<z.ZodObject<{
             nodeManager: z.ZodDefault<z.ZodEnum<{
-                bun: "bun";
                 npm: "npm";
                 pnpm: "pnpm";
                 yarn: "yarn";
+                bun: "bun";
             }>>;
         }, z.core.$strip>>;
         allowBundled: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
@@ -1162,6 +1088,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
         turnCommitMaxWaitMs: z.ZodDefault<z.ZodNumber>;
         failureBackoffBaseMs: z.ZodDefault<z.ZodNumber>;
         failureBackoffMaxMs: z.ZodDefault<z.ZodNumber>;
+        maxFileSizeBytes: z.ZodDefault<z.ZodNumber>;
         interactiveGitTimeoutMs: z.ZodDefault<z.ZodNumber>;
         enrichmentQueueSize: z.ZodDefault<z.ZodNumber>;
         enrichmentConcurrency: z.ZodDefault<z.ZodNumber>;
@@ -1252,6 +1179,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             bargeInMinSpeechMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
         maxSessionDurationSeconds: z.ZodDefault<z.ZodNumber>;
+        archiveAudio: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     whatsapp: z.ZodDefault<z.ZodObject<{
         phoneNumber: z.ZodDefault<z.ZodString>;
@@ -1518,30 +1446,6 @@ export declare interface AssistantEventSubscription {
     readonly connectionId: string;
 }
 
-declare interface AssistantInboxEscalationResponse {
-    type: "assistant_inbox_escalation_response";
-    success: boolean;
-    error?: string;
-    /** List of escalations (returned on list). */
-    escalations?: Array<{
-        id: string;
-        runId: string;
-        conversationId: string;
-        channel: string;
-        requesterExternalUserId: string;
-        requesterChatId: string;
-        status: string;
-        requestSummary?: string;
-        createdAt: number;
-    }>;
-    /** Decision result (returned on decide). */
-    decision?: {
-        id: string;
-        status: string;
-        decidedAt: number;
-    };
-}
-
 /**
  * Managed skill authored by the assistant's retrospective. Identical shape to a
  * custom skill — it stays managed/deletable — but carries a distinct origin so
@@ -1911,6 +1815,12 @@ declare interface ClawhubSlimSkill extends SlimSkillBase {
 
 export declare const CLI_COMMAND_HELP: readonly CliCommandHelp[];
 
+declare interface CliArgumentHelp {
+    /** Commander argument spec, e.g. `"<channel>"` or `"[value]"`. */
+    name: string;
+    description: string;
+}
+
 /**
  * Fully declarative description of a top-level `assistant` CLI command and its
  * subcommands. Plain data by design — no action handlers — so plugins (e.g. the
@@ -1920,7 +1830,21 @@ export declare const CLI_COMMAND_HELP: readonly CliCommandHelp[];
  */
 declare interface CliCommandHelp {
     name: string;
+    /**
+     * Positional-argument spec appended to the name at registration, e.g.
+     * `"<command>"`. Use {@link commandSpec} to build the Commander registration
+     * string; `name` stays the bare command name so consumers (dedup, slugs,
+     * rendering) never parse argument syntax out of it.
+     */
+    args?: string;
     description: string;
+    /**
+     * Positional arguments that carry their own description, applied via
+     * Commander's `argument(name, description)` (rendered in the generated
+     * `Arguments:` help section). Use `args` instead when the positional needs
+     * no description.
+     */
+    arguments?: CliArgumentHelp[];
     /** Options declared directly on the top-level command. */
     options?: CliOptionHelp[];
     /** Extra help appended after the option list (`addHelpText("after", …)`). */
@@ -1962,15 +1886,30 @@ declare interface CliOptionHelp {
     /** When true, applied via `requiredOption` (missing → error) rather than `option`. */
     required?: boolean;
     /** Default value passed to `option(flags, description, defaultValue)`. */
-    defaultValue?: string;
+    defaultValue?: string | number | boolean;
+    /** Allowed values, applied via Commander's `Option.choices()` (invalid → error). */
+    choices?: readonly string[];
 }
 
 declare interface CliSubcommandHelp {
     name: string;
+    /** Positional-argument spec, e.g. `"<path>"` — see {@link CliCommandHelp.args}. */
+    args?: string;
     description: string;
+    /**
+     * Positional arguments that carry their own description, applied via
+     * Commander's `argument(name, description)` (rendered in the generated
+     * `Arguments:` help section). Use `args` instead when the positional needs
+     * no description.
+     */
+    arguments?: CliArgumentHelp[];
     options?: CliOptionHelp[];
     /** Extra help appended after the option list (`addHelpText("after", …)`). */
     helpText?: string;
+    /** When true, this subcommand runs when the parent is invoked without one. */
+    isDefault?: boolean;
+    /** Nested subcommand groups (e.g. `avatar character update`). */
+    subcommands?: CliSubcommandHelp[];
 }
 
 declare type CompactionCircuitClosedEvent = z.infer<typeof CompactionCircuitClosedEventSchema>;
@@ -2428,7 +2367,7 @@ declare interface ConversationSearchResultItem {
     matchingMessages: ConversationSearchMatchingMessage[];
 }
 
-declare type _ConversationsServerMessages = AuthResult | PongMessage | AssistantStatusMessage | GenerationCancelledEvent | GenerationHandoffEvent | ModelInfo | HistoryResponse | UndoComplete | UsageUpdateEvent | UsageProgressEvent | UsageResponse | ContextCompacted | CompactionCircuitOpenEvent | CompactionCircuitClosedEvent | ConversationErrorEvent | ConversationNoticeEvent | ConversationInfo | ConversationTitleUpdatedEvent | ConversationListResponse | ConversationsClearResponse | ConversationSearchResponse | MessageContentResponse | ConversationListInvalidatedEvent | ScheduleConversationCreated | OpenConversation;
+declare type _ConversationsServerMessages = AuthResult | PongMessage | AssistantStatusMessage | GenerationCancelledEvent | GenerationHandoffEvent | ModelInfo | HistoryResponse | UndoComplete | UsageUpdateEvent | UsageProgressEvent | UsageResponse | ContextCompacted | CompactionCircuitOpenEvent | CompactionCircuitClosedEvent | ConversationErrorEvent | ConversationNoticeEvent | ConversationInfo | ConversationTitleUpdatedEvent | ConversationListResponse | ConversationsClearResponse | ConversationSearchResponse | MessageContentResponse | ConversationListInvalidatedEvent | ScheduleConversationCreated | OpenConversationEvent;
 
 declare type ConversationTitleUpdatedEvent = z.infer<typeof ConversationTitleUpdatedEventSchema>;
 
@@ -2696,7 +2635,7 @@ declare const ErrorEventSchema: z.ZodObject<{
     conversationId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 
-export declare function extractTextFromStoredMessageContent(raw: string): string;
+export declare function extractTextFromStoredMessageContent(raw: string | ContentBlock[]): string;
 
 export declare interface FileContent {
     type: "file";
@@ -2919,8 +2858,8 @@ declare interface GuardianDecisionPrompt {
     conversationId: string;
     callSessionId: string | null;
     /**
-     * Canonical request kind (e.g. 'tool_approval', 'pending_question').
-     * Present when the prompt originates from the canonical guardian request
+     * Guardian request kind (e.g. 'tool_approval', 'pending_question').
+     * Present when the prompt originates from the guardian request
      * store. Absent for legacy-only prompts.
      */
     kind?: string;
@@ -3417,10 +3356,10 @@ declare interface HostFileWriteRequest {
 
 /**
  * Host proxy capabilities that an interface can support. The macOS client
- * supports all five; the chrome-extension interface only supports
+ * supports all of them; the chrome-extension interface only supports
  * host_browser (via the Chrome DevTools Protocol proxy).
  */
-declare type HostProxyCapability = "host_bash" | "host_file" | "host_cu" | "host_browser" | "host_app_control";
+declare type HostProxyCapability = "host_bash" | "host_file" | "host_cu" | "host_browser" | "host_app_control" | "host_ui_snapshot";
 
 declare interface HostTransferCancelRequest {
     type: "host_transfer_cancel";
@@ -3456,6 +3395,29 @@ declare interface HostTransferToSandboxRequest {
     sourcePath: string;
 }
 
+declare interface HostUiSnapshotCancelMessage {
+    type: "host_ui_snapshot_cancel";
+    requestId: string;
+}
+
+declare interface HostUiSnapshotRequestMessage {
+    type: "host_ui_snapshot_request";
+    requestId: string;
+    view: HostUiSnapshotView;
+    /**
+     * Validated workspace-theme tokens to apply on the stage. The daemon reads
+     * them from ui/theme.json at request time so the capture reflects the
+     * current file even before connected clients refetch. Absent when no valid
+     * theme exists — the stage renders the built-in base theme.
+     */
+    tokens?: Record<string, string>;
+}
+
+declare type _HostUiSnapshotServerMessages = HostUiSnapshotRequestMessage | HostUiSnapshotCancelMessage;
+
+/** Staged compositions the web client can render for capture. */
+declare type HostUiSnapshotView = "sampler" | "chat";
+
 declare type IdentityChangedEvent = z.infer<typeof IdentityChangedEventSchema>;
 
 declare const IdentityChangedEventSchema: z.ZodObject<{
@@ -3493,7 +3455,7 @@ declare interface ImageEmbeddingInput {
     mimeType: string;
 }
 
-declare type _InboxServerMessages = ContactsInviteResponse | AssistantInboxEscalationResponse;
+declare type _InboxServerMessages = ContactsInviteResponse;
 
 declare interface IngressConfigResponse {
     type: "ingress_config_response";
@@ -3594,7 +3556,7 @@ declare const InteractionResolvedEventSchema: z.ZodObject<{
     kind: z.ZodString;
 }, z.core.$strip>;
 
-declare const INTERFACE_IDS: readonly ["macos", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a"];
+declare const INTERFACE_IDS: readonly ["macos", "ios", "cli", "telegram", "phone", "web", "whatsapp", "slack", "email", "chrome-extension", "a2a", "route"];
 
 declare type InterfaceId = (typeof INTERFACE_IDS)[number];
 
@@ -3856,8 +3818,8 @@ declare const messageMetadataSchema: z.ZodObject<{
         platform: "platform";
         a2a: "a2a";
     }>>;
-    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension", string>>>;
-    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension", string>>>;
+    userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
+    assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
     client: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     subagentNotification: z.ZodOptional<z.ZodObject<{
         subagentId: z.ZodString;
@@ -3882,6 +3844,7 @@ declare const messageMetadataSchema: z.ZodObject<{
         trusted_contact: "trusted_contact";
         unverified_contact: "unverified_contact";
     }>>;
+    model: z.ZodOptional<z.ZodString>;
     provenanceSourceChannel: z.ZodOptional<z.ZodEnum<{
         vellum: "vellum";
         telegram: "telegram";
@@ -3960,8 +3923,13 @@ declare interface MessageRow {
     id: string;
     conversationId: string;
     role: string;
-    /** Resolved content — always inline JSON, never a raw `{ ref }`. */
-    content: string;
+    /**
+     * Typed content blocks, resolved at the row-fetch chokepoint by
+     * `resolveMessageContentBlocks`: inline JSON parses, file-backed
+     * `{ ref }` rows fold their delta file, and legacy plain strings arrive
+     * wrapped in a single text block.
+     */
+    content: ContentBlock[];
     createdAt: number;
     metadata: string | null;
     clientMessageId: string | null;
@@ -4129,22 +4097,15 @@ declare interface OpenBundleResponse {
     bundleSizeBytes: number;
 }
 
-/**
- * Server push — instructs the client to open and focus a conversation. If
- * the conversation isn't already present in the client's sidebar list (e.g.
- * it was just created via `POST /v1/conversations`), the client should stub
- * a sidebar entry using the provided `title` before navigating.
- */
-declare interface OpenConversation {
-    type: "open_conversation";
-    conversationId: string;
-    /** Optional conversation title; supplied when the client may not yet have the conversation in its list. */
-    title?: string;
-    /** Optional message ID to scroll to after focus. */
-    anchorMessageId?: string;
-    /** When `false`, the client should register the conversation in its sidebar (so it's visible and navigable) but must NOT switch focus to it. Omitting the field defaults to `true` for backward compatibility with existing single-target 'jump to conversation' callers. */
-    focus?: boolean;
-}
+declare type OpenConversationEvent = z.infer<typeof OpenConversationEventSchema>;
+
+declare const OpenConversationEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"open_conversation">;
+    conversationId: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    anchorMessageId: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 
 declare type OpenPanelEvent = z.infer<typeof OpenPanelEventSchema>;
 
@@ -4868,6 +4829,63 @@ export declare enum RiskLevel {
  */
 declare type RiskLevel_2 = "safe" | "low" | "medium" | "high" | "critical" | "unknown";
 
+/**
+ * Run a full conversation agent-loop turn: persist the user message, execute
+ * the agent loop (history, tools, compaction, injections), and return the
+ * assistant's full content-block response.
+ *
+ * When `conversationId` is omitted, a new conversation is created and its ID
+ * is returned in the result.
+ *
+ * Events are fanned out to SSE/event-hub subscribers via `broadcastMessage`
+ * (the same path the daemon's HTTP message route uses) while also being
+ * collected internally so the caller receives the final response content.
+ * For streaming use cases, subscribe to the conversation's events via the
+ * host event hub (`assistantEventHub`).
+ *
+ * If the conversation is currently processing another turn, the message is
+ * queued via `enqueueMessage` and the result carries `queued: true` with
+ * empty content -- the queued turn will execute automatically when the
+ * current turn finishes.
+ */
+export declare function runConversationTurn(options: RunConversationTurnOptions): Promise<RunConversationTurnResult>;
+
+export declare interface RunConversationTurnOptions {
+    /**
+     * Conversation to run the turn in. If omitted, a new conversation is
+     * created (its ID is generated with `uuidv7` and returned in the result).
+     */
+    conversationId?: string;
+    /**
+     * User message content blocks for this turn. Text blocks become the
+     * user message body; image/file blocks are resolved to inline
+     * attachments. Other block types (tool_use, tool_result, thinking) are
+     * ignored as they are not valid user input.
+     */
+    content: ContentBlock[];
+    /**
+     * LLM call-site for inference profile resolution. Defaults to
+     * `"mainAgent"` inside the agent loop when omitted.
+     */
+    callSite?: LLMCallSite;
+    /**
+     * Abort signal. When aborted, the conversation's internal abort
+     * controller fires, terminating the in-flight agent loop.
+     */
+    signal?: AbortSignal;
+}
+
+export declare interface RunConversationTurnResult {
+    /** The assistant's full content blocks for this turn (text, tool_use, etc.). */
+    content: ContentBlock[];
+    /** The user message row ID assigned by the persistence layer. */
+    userMessageId: string;
+    /** The conversation this turn ran in. */
+    conversationId: string;
+    /** True when the message was queued because the conversation was busy. */
+    queued?: boolean;
+}
+
 /**
  * Emitted when the compaction circuit breaker trips. After three consecutive
  * summary-LLM failures (with local fallback covering each), auto-compaction is
@@ -5005,7 +5023,8 @@ export declare interface SendMessageConfig {
      * LLM call-site identifier. `RetryProvider` resolves
      * provider/model/maxTokens/effort/speed/verbosity/temperature/thinking/
      * contextWindow via `resolveCallSiteConfig(callSite, config.llm)`, falling
-     * back to `llm.default` when no callSite-specific entry is present.
+     * back to the shipped call-site defaults when no callSite-specific entry
+     * is present.
      */
     callSite?: LLMCallSite;
     /**
@@ -5036,6 +5055,18 @@ export declare interface SendMessageConfig {
      * stripped before any provider wire request.
      */
     selectionSeed?: string;
+    /**
+     * Per-conversation prompt-cache key for providers with explicit prompt
+     * caching (sent as the OpenAI `prompt_cache_key` request param). Set by
+     * `RetryProvider` from `selectionSeed` (the durable conversation id) for
+     * the `openai` and `openrouter` providers — GPT-5.6+ requires the key for
+     * reliable breakpoint matching, and OpenAI's ~15 req/min-per-key routing
+     * guidance is satisfied by per-conversation ids. A non-wire field for
+     * every other provider client (the Anthropic client strips it, covering
+     * OpenRouter's `anthropic/*` delegation); the request param is omitted
+     * when absent.
+     */
+    promptCacheKey?: string;
     /**
      * Internal per-request HTTP headers for managed-proxy usage attribution.
      * Provider clients may pass these through SDK request options only when the
@@ -5097,7 +5128,7 @@ declare interface SensitiveOutputBinding {
 
 declare type SensitiveOutputKind = "invite_code";
 
-declare type ServerMessage = _ConversationsServerMessages | _MessagesServerMessages | _SurfacesServerMessages | _SkillsServerMessages | _AppsServerMessages | _IntegrationsServerMessages | _ComputerUseServerMessages | _ContactsServerMessages | _WorkItemsServerMessages | _SubagentsServerMessages | _DocumentsServerMessages | _DocumentCommentsServerMessages | _GuardianActionsServerMessages | _SyncInvalidationServerMessages | _HomeServerMessages | _HostAppControlServerMessages | _HostBashServerMessages | _HostBrowserServerMessages | _HostCuServerMessages | _HostFileServerMessages | _HostTransferServerMessages | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _DiagnosticsServerMessages | _InboxServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BackgroundToolsServerMessages | _BookmarksServerMessages | _WorkflowsServerMessages | DiskPressureStatusChangedEvent | HookEvent | SubagentEvent;
+declare type ServerMessage = _ConversationsServerMessages | _MessagesServerMessages | _SurfacesServerMessages | _SkillsServerMessages | _AppsServerMessages | _IntegrationsServerMessages | _ComputerUseServerMessages | _ContactsServerMessages | _SubagentsServerMessages | _DocumentsServerMessages | _DocumentCommentsServerMessages | _GuardianActionsServerMessages | _SyncInvalidationServerMessages | _HomeServerMessages | _HostAppControlServerMessages | _HostBashServerMessages | _HostBrowserServerMessages | _HostCuServerMessages | _HostFileServerMessages | _HostTransferServerMessages | _HostUiSnapshotServerMessages | _MemoryServerMessages | _WorkspaceServerMessages | _SchedulesServerMessages | _SettingsServerMessages | _DiagnosticsServerMessages | _InboxServerMessages | _NotificationsServerMessages | _UpgradesServerMessages | _AcpServerMessages | _BackgroundToolsServerMessages | _BookmarksServerMessages | _WorkflowsServerMessages | DiskPressureStatusChangedEvent | HookEvent | SubagentEvent;
 
 export declare interface ServerToolUseContent {
     type: "server_tool_use";
@@ -5427,7 +5458,7 @@ declare interface StopInputContext {
  * Parse failures fall back to returning the raw input trimmed (the
  * legacy-string path).
  */
-export declare function stringifyMessageContent(stored: string): string;
+export declare function stringifyMessageContent(stored: string | ContentBlock[]): string;
 
 declare interface SubagentDetailResponse {
     type: "subagent_detail_response";
@@ -5518,6 +5549,29 @@ declare type _SyncInvalidationServerMessages = SyncChangedEvent;
 /** Re-sync one persisted message into the conversation's disk view. */
 export declare function syncMessageToDisk(conversationId: string, messageId: string, createdAtMs: number): Promise<void>;
 
+/**
+ * Synthesize text to audio using the globally configured TTS provider.
+ *
+ * 1. Resolves the active provider and its config via `tts-config-resolver`.
+ * 2. Looks up the provider adapter in the registry.
+ * 3. Delegates to the adapter's `synthesize` method.
+ *
+ * Throws {@link TtsSynthesisError} when the provider is not registered
+ * or synthesis fails.
+ */
+export declare function synthesizeText(options: SynthesizeTextOptions): Promise<TtsSynthesisResult>;
+
+export declare interface SynthesizeTextOptions {
+    /** Text to speak. Sanitized internally — callers can pass raw model output. */
+    text: string;
+    /** Product surface requesting synthesis. */
+    useCase: TtsUseCase;
+    /** Optional voice override (provider-specific identifier). */
+    voiceId?: string;
+    /** Optional abort signal. */
+    signal?: AbortSignal;
+}
+
 declare interface TableCellValue {
     text: string;
     icon?: string;
@@ -5544,19 +5598,6 @@ declare interface TableSurfaceData {
     caption?: string;
 }
 
-/** Server push — broadcast when a task run creates a conversation. */
-declare interface TaskRunConversationCreated {
-    type: "task_run_conversation_created";
-    conversationId: string;
-    workItemId: string;
-    title: string;
-}
-
-/** Server push — lightweight invalidation signal: the task queue has been mutated, refetch your list. */
-declare interface TasksChanged {
-    type: "tasks_changed";
-}
-
 declare interface TelegramConfigResponse {
     type: "telegram_config_response";
     success: boolean;
@@ -6205,6 +6246,31 @@ declare const trustClassSchema: z.ZodEnum<{
     unverified_contact: "unverified_contact";
 }>;
 
+export declare class TtsSynthesisError extends Error {
+    readonly code: TtsSynthesisErrorCode;
+    constructor(code: TtsSynthesisErrorCode, message: string);
+}
+
+declare type TtsSynthesisErrorCode = "TTS_PROVIDER_NOT_CONFIGURED" | "TTS_SYNTHESIS_FAILED";
+
+/** Output of a completed TTS synthesis call. */
+export declare interface TtsSynthesisResult {
+    /** Complete audio buffer. */
+    audio: Buffer;
+    /** MIME type of the returned audio (e.g. `"audio/mpeg"`, `"audio/wav"`). */
+    contentType: string;
+}
+
+/**
+ * Describes the product surface that is requesting synthesis so providers
+ * can tailor format, latency, and quality trade-offs.
+ */
+declare type TtsUseCase = 
+/** Real-time phone call — prioritize low latency and streaming. */
+"phone-call"
+/** In-app message playback — buffer-oriented, higher quality acceptable. */
+| "message-playback";
+
 declare interface UiSurfaceComplete {
     type: "ui_surface_complete";
     conversationId: string;
@@ -6726,144 +6792,6 @@ declare interface WorkflowStarted {
     label?: string;
 }
 
-declare interface WorkItemApprovePermissionsResponse {
-    type: "work_item_approve_permissions_response";
-    id: string;
-    success: boolean;
-    error?: string;
-}
-
-declare interface WorkItemCancelResponse {
-    type: "work_item_cancel_response";
-    id: string;
-    success: boolean;
-    error?: string;
-}
-
-declare interface WorkItemDeleteResponse {
-    type: "work_item_delete_response";
-    id: string;
-    success: boolean;
-}
-
-declare interface WorkItemGetResponse {
-    type: "work_item_get_response";
-    item: {
-        id: string;
-        taskId: string;
-        title: string;
-        notes: string | null;
-        status: string;
-        priorityTier: number;
-        sortIndex: number | null;
-        lastRunId: string | null;
-        lastRunConversationId: string | null;
-        lastRunStatus: string | null;
-        sourceType: string | null;
-        sourceId: string | null;
-        createdAt: number;
-        updatedAt: number;
-    } | null;
-}
-
-declare interface WorkItemOutputResponse {
-    type: "work_item_output_response";
-    id: string;
-    success: boolean;
-    error?: string;
-    output?: {
-        title: string;
-        status: string;
-        runId: string | null;
-        conversationId: string | null;
-        completedAt: number | null;
-        summary: string;
-        highlights: string[];
-    };
-}
-
-declare interface WorkItemPreflightResponse {
-    type: "work_item_preflight_response";
-    id: string;
-    success: boolean;
-    error?: string;
-    permissions?: {
-        tool: string;
-        description: string;
-        riskLevel: "low" | "medium" | "high";
-        currentDecision: "allow" | "deny" | "prompt";
-    }[];
-}
-
-declare type WorkItemRunTaskErrorCode = "not_found" | "already_running" | "invalid_status" | "no_task" | "permission_required";
-
-declare interface WorkItemRunTaskResponse {
-    type: "work_item_run_task_response";
-    id: string;
-    lastRunId: string;
-    success: boolean;
-    error?: string;
-    /** Structured error code so the client can deterministically re-enable buttons or show contextual UI. */
-    errorCode?: WorkItemRunTaskErrorCode;
-}
-
-declare interface WorkItemsListResponse {
-    type: "work_items_list_response";
-    items: Array<{
-        id: string;
-        taskId: string;
-        title: string;
-        notes: string | null;
-        status: string;
-        priorityTier: number;
-        sortIndex: number | null;
-        lastRunId: string | null;
-        lastRunConversationId: string | null;
-        lastRunStatus: string | null;
-        sourceType: string | null;
-        sourceId: string | null;
-        createdAt: number;
-        updatedAt: number;
-    }>;
-}
-
-declare type _WorkItemsServerMessages = WorkItemsListResponse | WorkItemGetResponse | WorkItemUpdateResponse | WorkItemDeleteResponse | WorkItemRunTaskResponse | WorkItemOutputResponse | WorkItemPreflightResponse | WorkItemApprovePermissionsResponse | WorkItemCancelResponse | WorkItemStatusChanged | TaskRunConversationCreated | TasksChanged;
-
-/** Server push — broadcast when a work item status changes (e.g. running -> awaiting_review). */
-declare interface WorkItemStatusChanged {
-    type: "work_item_status_changed";
-    item: {
-        id: string;
-        taskId: string;
-        title: string;
-        status: string;
-        lastRunId: string | null;
-        lastRunConversationId: string | null;
-        lastRunStatus: string | null;
-        updatedAt: number;
-    };
-}
-
-declare interface WorkItemUpdateResponse {
-    type: "work_item_update_response";
-    item: {
-        id: string;
-        taskId: string;
-        title: string;
-        notes: string | null;
-        status: string;
-        priorityTier: number;
-        sortIndex: number | null;
-        lastRunId: string | null;
-        lastRunConversationId: string | null;
-        lastRunStatus: string | null;
-        sourceType: string | null;
-        sourceId: string | null;
-        createdAt: number;
-        updatedAt: number;
-    } | null;
-}
-
 declare interface WorkResultDiff {
     label?: string;
     before?: string;

package/index.js

@@ -3,6 +3,7 @@ const api = globalThis[Symbol.for("vellum.plugin-api")] ?? {};
 export const CLI_COMMAND_HELP = api.CLI_COMMAND_HELP;
 export const HOOKS = api.HOOKS;
 export const RiskLevel = api.RiskLevel;
+export const TtsSynthesisError = api.TtsSynthesisError;
 export const addMessage = api.addMessage;
 export const assistantEventHub = api.assistantEventHub;
 export const buildMessageExcerpt = api.buildMessageExcerpt;
@@ -25,8 +26,10 @@ export const listInstalledSkills = api.listInstalledSkills;
 export const parseMessageMetadata = api.parseMessageMetadata;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
 export const resolveUserName = api.resolveUserName;
+export const runConversationTurn = api.runConversationTurn;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
 export const stringifyMessageContent = api.stringifyMessageContent;
 export const syncMessageToDisk = api.syncMessageToDisk;
+export const synthesizeText = api.synthesizeText;
 export const updateMessageMetadata = api.updateMessageMetadata;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.10.8",
+  "version": "0.10.9-dev.202607152225.ec6fdbf",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",