@vellumai/plugin-api 0.10.10 → 0.10.11-dev.202607212323.c5c49c0

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>;
@@ -295,33 +295,21 @@ declare const AssistantConfigSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>;
         "web-fetch": z.ZodDefault<z.ZodObject<{
-            mode: z.ZodDefault<z.ZodEnum<{
-                managed: "managed";
-                "your-own": "your-own";
-            }>>;
             provider: z.ZodDefault<z.ZodEnum<{
                 [x: string]: string;
             }>>;
         }, z.core.$strip>>;
         stt: z.ZodDefault<z.ZodObject<{
-            mode: z.ZodDefault<z.ZodEnum<{
-                managed: "managed";
-                "your-own": "your-own";
-            }>>;
-            provider: z.ZodEnum<{
+            provider: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodEnum<{
                 vellum: "vellum";
                 deepgram: "deepgram";
                 "google-gemini": "google-gemini";
                 "openai-whisper": "openai-whisper";
                 xai: "xai";
-            }>;
+            }>>;
             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.ZodEnum<{
-                managed: "managed";
-                "your-own": "your-own";
-            }>>;
             provider: z.ZodDefault<z.ZodEnum<{
                 vellum: "vellum";
                 deepgram: "deepgram";
@@ -370,7 +358,9 @@ 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>>;
+                vellum: z.ZodDefault<z.ZodObject<{
+                    model: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         "google-oauth": z.ZodDefault<z.ZodObject<{
@@ -717,13 +707,16 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 gemini: "gemini";
                 fireworks: "fireworks";
                 openrouter: "openrouter";
+                vellum: "vellum";
                 ollama: "ollama";
                 "vercel-ai-gateway": "vercel-ai-gateway";
                 "openai-compatible": "openai-compatible";
                 minimax: "minimax";
                 atlascloud: "atlascloud";
                 together: "together";
+                litellm: "litellm";
                 baseten: "baseten";
+                chatgpt: "chatgpt";
             }>>;
             model: z.ZodOptional<z.ZodString>;
             maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -839,6 +832,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
             skillCategoryInference: "skillCategoryInference";
             inference: "inference";
             vision: "vision";
+            voiceFrontDecision: "voiceFrontDecision";
             trustRuleSuggestion: "trustRuleSuggestion";
             homeGreeting: "homeGreeting";
             homeSuggestedPrompts: "homeSuggestedPrompts";
@@ -850,13 +844,16 @@ declare const AssistantConfigSchema: z.ZodObject<{
                 gemini: "gemini";
                 fireworks: "fireworks";
                 openrouter: "openrouter";
+                vellum: "vellum";
                 ollama: "ollama";
                 "vercel-ai-gateway": "vercel-ai-gateway";
                 "openai-compatible": "openai-compatible";
                 minimax: "minimax";
                 atlascloud: "atlascloud";
                 together: "together";
+                litellm: "litellm";
                 baseten: "baseten";
+                chatgpt: "chatgpt";
             }>>;
             model: z.ZodOptional<z.ZodString>;
             maxTokens: z.ZodOptional<z.ZodNumber>;
@@ -1180,6 +1177,21 @@ declare const AssistantConfigSchema: z.ZodObject<{
             maxTurnDurationMs: z.ZodDefault<z.ZodNumber>;
             bargeInMinSpeechMs: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
+        frontModel: z.ZodDefault<z.ZodObject<{
+            endpointDecisionTimeoutMs: z.ZodDefault<z.ZodNumber>;
+            endpointExtensionMs: z.ZodDefault<z.ZodNumber>;
+            endpointMaxExtensions: z.ZodDefault<z.ZodNumber>;
+            ackFirstDeltaTimeoutMs: z.ZodDefault<z.ZodNumber>;
+            ackGenerationTimeoutMs: z.ZodDefault<z.ZodNumber>;
+            llmAckText: z.ZodDefault<z.ZodBoolean>;
+            progress: z.ZodDefault<z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                opsThreshold: z.ZodDefault<z.ZodNumber>;
+                idleIntervalMs: z.ZodDefault<z.ZodNumber>;
+                minGapMs: z.ZodDefault<z.ZodNumber>;
+                generationTimeoutMs: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
         maxSessionDurationSeconds: z.ZodDefault<z.ZodNumber>;
         archiveAudio: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
@@ -1937,6 +1949,8 @@ declare interface ConfigChanged {
     type: "config_changed";
 }
 
+declare type ConfiguredProviderOptions = Pick<ResolveCallSiteOpts, "overrideProfile" | "forceOverrideProfile" | "selectionSeed">;
+
 declare type ConfirmationRequestEvent = z.infer<typeof ConfirmationRequestEventSchema>;
 
 declare const ConfirmationRequestEventSchema: z.ZodObject<{
@@ -2390,6 +2404,11 @@ declare interface CopyBlockSurfaceData {
     language?: string;
 }
 
+/** Create a live voice connection bound to the caller's `send` transport. */
+export declare function createLiveVoiceConnection(options: {
+    send: LiveVoiceFrameSender;
+}): LiveVoiceConnection;
+
 /**
  * Plugin-facing credential resolution.
  *
@@ -2805,10 +2824,7 @@ export declare function getAssistantName(): string | null;
  * `callSite` is required — see `resolveConfiguredProvider`. Returns `null`
  * when no providers are available.
  */
-export declare function getConfiguredProvider(callSite: LLMCallSite, opts?: {
-    overrideProfile?: string;
-    forceOverrideProfile?: boolean;
-}): Promise<Provider | null>;
+export declare function getConfiguredProvider(callSite: LLMCallSite, opts?: ConfiguredProviderOptions): Promise<Provider | null>;
 
 /** Look up a conversation row by id. */
 export declare function getConversation(id: string): Promise<ConversationRow | null>;
@@ -2842,6 +2858,34 @@ declare interface GetSigningIdentityRequest {
     requestId: string;
 }
 
+/**
+ * Returns the workspace root for user-facing state.
+ *
+ * When the VELLUM_WORKSPACE_DIR env var is set, returns that value (used in
+ * containerized deployments where the workspace is a separate volume).
+ * Otherwise falls back to ~/.vellum/workspace.
+ */
+export declare function getWorkspaceDir(): string;
+
+/**
+ * The subset of the Qdrant client the orphan sweep needs, narrowed to an
+ * interface so the sweep can be unit-tested with a fake client.
+ */
+declare interface GraphNodeSweepClient {
+    scrollByTargetType(targetType: string): Promise<Array<{
+        id: string;
+        payload: Record<string, unknown>;
+    }>>;
+    deleteByTarget(targetType: string, targetId: string): Promise<void>;
+}
+
+declare interface GraphNodeSweepResult {
+    /** Distinct `graph_node` target ids currently indexed in Qdrant. */
+    scanned: number;
+    /** Orphan target ids whose Qdrant points were deleted. */
+    deleted: number;
+}
+
 declare interface GuardianActionDecisionResponse {
     type: "guardian_action_decision_response";
     applied: boolean;
@@ -3621,6 +3665,34 @@ export declare function isConversationProcessing(id: string): Promise<boolean>;
  */
 export declare function isMaxTokensStopReason(stopReason: string | null | undefined): boolean;
 
+/**
+ * A user-role message carrying only tool results — local `tool_result` or
+ * server `web_search_tool_result` — not a fresh prompt.
+ */
+export declare function isToolResultMessage(message: Message): boolean;
+
+/**
+ * Whether a provider error message indicates the model can't accept image
+ * input. Providers wrap raw upstream rejections in their own prose (e.g.
+ * `Anthropic API error (400): …`, `Gemini API error (…): …`), so the classifier
+ * matches the full {@link VISION_NOT_SUPPORTED_PATTERNS} set rather than any
+ * single normalized phrase.
+ */
+export declare function isVisionNotSupportedError(message: string): boolean;
+
+/**
+ * Index of the last user message carrying `tool_result` blocks — the
+ * "current turn" boundary {@link stripOldMediaBlocks} keeps intact while
+ * stripping media from older tool results. Returns -1 when no user message
+ * has tool results.
+ *
+ * Targets the last user message with tool_results (not just the last user
+ * message) because a plain-text user message may follow the tool-result turn;
+ * using the last user message unconditionally would leave the most recent tool
+ * screenshots unprotected from stripping.
+ */
+export declare function lastToolResultUserMessageIndex(history: Message[]): number;
+
 /**
  * The remote skill catalog, fetched via the shared catalog cache. Entries
  * whose declared feature flag is disabled are reported with
@@ -3661,6 +3733,209 @@ declare interface ListSurfaceData {
     selectionMode: "single" | "multiple" | "none";
 }
 
+declare const _LIVE_VOICE_SERVER_FRAME_TYPES: readonly ["ready", "busy", "speech_started", "utterance_end", "utterance_discarded", "stt_partial", "stt_final", "thinking", "assistant_text_delta", "tts_audio", "tts_done", "turn_cancelled", "metrics", "archived", "error"];
+
+declare const LIVE_VOICE_TURN_DETECTION_MODES: readonly ["manual", "server_vad"];
+
+declare interface LiveVoiceArchivedServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "archived";
+    readonly conversationId: string;
+    readonly sessionId: string;
+    readonly turnId?: string;
+    readonly role?: "user" | "assistant";
+    readonly attachmentId?: string;
+    readonly attachmentIds?: string[];
+    readonly warning?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+
+declare interface LiveVoiceAssistantTextDeltaServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "assistant_text_delta";
+    readonly text: string;
+}
+
+declare interface LiveVoiceBusyServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "busy";
+    readonly activeSessionId: string;
+}
+
+export declare interface LiveVoiceConnection {
+    /**
+     * The active session id once a `start` frame has been accepted, else
+     * `undefined`. Read-only — the connection assigns it on `start` and clears
+     * it on `end`, teardown, or a session that the manager no longer knows.
+     */
+    readonly sessionId: string | undefined;
+    /**
+     * Handle one inbound transport message — a JSON text frame or a binary
+     * audio chunk. Never rejects: protocol and handler failures are reported
+     * back to the client as `error` frames.
+     */
+    handleMessage(message: string | ArrayBuffer | ArrayBufferView): Promise<void>;
+    /**
+     * Release the session bound to this connection when the transport closes.
+     * Idempotent — a no-op when no session is active.
+     */
+    release(reason?: LiveVoiceSessionCloseReason): void;
+}
+
+declare interface LiveVoiceErrorServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "error";
+    readonly code: LiveVoiceProtocolErrorCode;
+    readonly message: string;
+    /**
+     * True when the session continues past the error (e.g. a transient
+     * transcriber blip or one failed TTS segment). Absent (including on frames
+     * from older daemons) means the error is terminal for the session.
+     */
+    readonly recoverable?: boolean;
+}
+
+/**
+ * Sends one fully-sequenced server frame to the client over the caller's
+ * transport. The frame is a plain object; the caller is responsible for wire
+ * encoding (e.g. `JSON.stringify` for a text WebSocket).
+ */
+export declare type LiveVoiceFrameSender = (frame: LiveVoiceServerFrame) => void;
+
+declare interface LiveVoiceMetricsServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "metrics";
+    readonly event?: string;
+    readonly sessionId?: string;
+    readonly conversationId?: string;
+    readonly turnId: string;
+    readonly metrics?: unknown;
+    readonly sttMs: number | null;
+    readonly llmFirstDeltaMs: number | null;
+    readonly ttsFirstAudioMs: number | null;
+    /** End-of-speech (utterance_end, or ptt_release in manual mode) to first TTS audio. */
+    readonly roundTripMs: number | null;
+    readonly totalMs: number | null;
+    /**
+     * Semantic-endpointing "hold" decisions taken during the turn. Present only
+     * when the endpoint decider was consulted (otherwise the field is absent,
+     * keeping frames unchanged).
+     */
+    readonly endpointHoldCount?: number;
+    /** Worst endpoint-decision latency observed during the turn. */
+    readonly endpointDecisionMaxLatencyMs?: number;
+    /** Which floor-holding ack actually spoke during the turn, if any. */
+    readonly ackSpoken?: "first_delta" | "tool_use";
+    /**
+     * Spoken progress narrations during the turn. Present only when at least
+     * one progress update spoke (otherwise the field is absent, keeping frames
+     * unchanged).
+     */
+    readonly progressUpdatesSpoken?: number;
+}
+
+declare const LiveVoiceProtocolErrorCode: {
+    readonly InvalidJson: "invalid_json";
+    readonly InvalidFrame: "invalid_frame";
+    readonly UnknownType: "unknown_type";
+    readonly MissingRequiredField: "missing_required_field";
+    readonly InvalidField: "invalid_field";
+    readonly InvalidAudioPayload: "invalid_audio_payload";
+    /**
+     * Session startup was rejected because the daemon cannot run both audio
+     * legs (STT/TTS providers or credentials are unresolved). The error
+     * `message` names the offending provider(s) and missing credential(s).
+     */
+    readonly CredentialsUnavailable: "credentials_unavailable";
+};
+
+declare type LiveVoiceProtocolErrorCode = (typeof LiveVoiceProtocolErrorCode)[keyof typeof LiveVoiceProtocolErrorCode];
+
+declare interface LiveVoiceReadyServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "ready";
+    readonly sessionId: string;
+    readonly conversationId: string;
+    /**
+     * Echoes the turn-detection mode the session is actually running, so
+     * clients can detect a daemon that ignored a requested mode. Absent
+     * (older daemons) means "manual".
+     */
+    readonly turnDetection?: LiveVoiceTurnDetectionMode;
+}
+
+export declare type LiveVoiceServerFrame = LiveVoiceReadyServerFrame | LiveVoiceBusyServerFrame | LiveVoiceSpeechStartedServerFrame | LiveVoiceUtteranceEndServerFrame | LiveVoiceUtteranceDiscardedServerFrame | LiveVoiceSttPartialServerFrame | LiveVoiceSttFinalServerFrame | LiveVoiceThinkingServerFrame | LiveVoiceAssistantTextDeltaServerFrame | LiveVoiceTtsAudioServerFrame | LiveVoiceTtsDoneServerFrame | LiveVoiceTurnCancelledServerFrame | LiveVoiceMetricsServerFrame | LiveVoiceArchivedServerFrame | LiveVoiceErrorServerFrame;
+
+declare interface LiveVoiceServerFrameBase {
+    readonly type: LiveVoiceServerFrameType;
+    readonly seq: number;
+}
+
+declare type LiveVoiceServerFrameType = (typeof _LIVE_VOICE_SERVER_FRAME_TYPES)[number];
+
+export declare type LiveVoiceSessionCloseReason = "client_end" | "error" | "websocket_close" | "transport_closed" | "manager_shutdown";
+
+/**
+ * Emitted when the server VAD detects user speech. The client MUST
+ * immediately stop local TTS playback — this doubles as the flush-tail-audio
+ * signal (the in-app analog of the phone stack's buffered-audio clear).
+ */
+declare interface LiveVoiceSpeechStartedServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "speech_started";
+}
+
+declare interface LiveVoiceSttFinalServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "stt_final";
+    readonly text: string;
+}
+
+declare interface LiveVoiceSttPartialServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "stt_partial";
+    readonly text: string;
+}
+
+declare interface LiveVoiceThinkingServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "thinking";
+    readonly turnId: string;
+}
+
+declare interface LiveVoiceTtsAudioServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "tts_audio";
+    readonly mimeType: string;
+    readonly sampleRate: number;
+    readonly dataBase64: string;
+}
+
+declare interface LiveVoiceTtsDoneServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "tts_done";
+    readonly turnId: string;
+}
+
+/**
+ * Emitted when an in-flight assistant turn is aborted by barge-in. The client
+ * must drop any buffered tts_audio for that turn; no tts_done will follow.
+ */
+declare interface LiveVoiceTurnCancelledServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "turn_cancelled";
+    readonly turnId: string;
+}
+
+declare type LiveVoiceTurnDetectionMode = (typeof LIVE_VOICE_TURN_DETECTION_MODES)[number];
+
+/**
+ * Emitted only in server_vad mode when the closed utterance produced no
+ * usable speech: it is dropped without an assistant turn and the client
+ * should return to listening.
+ */
+declare interface LiveVoiceUtteranceDiscardedServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "utterance_discarded";
+}
+
+/**
+ * Emitted when the server VAD closes the utterance and the turn's
+ * transcription begins (plays the role ptt_release plays in manual mode).
+ */
+declare interface LiveVoiceUtteranceEndServerFrame extends LiveVoiceServerFrameBase {
+    readonly type: "utterance_end";
+    readonly reason: "silence" | "max-duration";
+}
+
 export declare type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
 
 /**
@@ -3707,6 +3982,7 @@ declare const LLMCallSiteEnum: z.ZodEnum<{
     skillCategoryInference: "skillCategoryInference";
     inference: "inference";
     vision: "vision";
+    voiceFrontDecision: "voiceFrontDecision";
     trustRuleSuggestion: "trustRuleSuggestion";
     homeGreeting: "homeGreeting";
     homeSuggestedPrompts: "homeSuggestedPrompts";
@@ -3866,9 +4142,9 @@ declare const messageMetadataSchema: z.ZodObject<{
         subagentId: z.ZodString;
         label: z.ZodString;
         status: z.ZodEnum<{
-            completed: "completed";
             failed: "failed";
             aborted: "aborted";
+            completed: "completed";
             running: "running";
         }>;
         error: z.ZodOptional<z.ZodString>;
@@ -3909,8 +4185,8 @@ declare const messageMetadataSchema: z.ZodObject<{
         startedAt: z.ZodNumber;
         status: z.ZodEnum<{
             cancelled: "cancelled";
-            completed: "completed";
             failed: "failed";
+            completed: "completed";
         }>;
         exitCode: z.ZodNullable<z.ZodNumber>;
         output: z.ZodString;
@@ -4665,6 +4941,13 @@ export declare interface ProviderResponse {
     model: string;
     /** Provider that actually produced this response, which may differ from a wrapper provider name. */
     actualProvider?: string;
+    /**
+     * Base URL the provider's HTTP client actually resolved to for this request,
+     * read from the live SDK client instance rather than re-derived from config.
+     * Lets diagnostics observe the true routing target (e.g. a misrouted host)
+     * instead of inferring it. Absent for providers that don't surface it.
+     */
+    resolvedEndpoint?: string;
     usage: {
         /** Total input tokens (input_tokens + cache_creation + cache_read). */
         inputTokens: number;
@@ -4714,6 +4997,18 @@ declare interface PublishPageResponse {
     errorCode?: string;
 }
 
+/**
+ * Remove every previously-refused exchange from a working history: for each
+ * assistant message that is exactly the refusal fallback, drop it together with
+ * the contiguous run back to (and including) the nearest genuine user prompt.
+ * That excises the flagged prompt (and any tool exchange in that run) so the
+ * provider never replays it. Returns a new array; the input is untouched.
+ */
+export declare function quarantineRefusedExchanges(messages: Message[]): {
+    messages: Message[];
+    droppedExchanges: number;
+};
+
 declare type QuestionRequestEvent = z.infer<typeof QuestionRequestEventSchema>;
 
 declare const QuestionRequestEventSchema: z.ZodObject<{
@@ -4785,6 +5080,19 @@ export declare interface RedactedThinkingContent {
     data: string;
 }
 
+/**
+ * User-facing text a refusal turn is rewritten into (single source of truth for
+ * both the producer — the empty-response plugin's `post-model-call` hook — and
+ * the detector below).
+ *
+ * DETECTION COUPLING: `isRefusalFallbackMessage` matches this string exactly,
+ * so it doubles as the quarantine marker for already-persisted transcripts.
+ * Editing the wording silently stops the sweep from recognizing conversations
+ * poisoned under the old wording (re-introducing the dead-end for that cohort).
+ * If the copy must change, keep matching the historical variants too.
+ */
+export declare const REFUSAL_FALLBACK_TEXT = "Sorry \u2014 I wasn't able to generate a response to that. Please try rephrasing or asking in a different way.";
+
 declare type RelationshipStateUpdatedEvent = z.infer<typeof RelationshipStateUpdatedEventSchema>;
 
 declare const RelationshipStateUpdatedEventSchema: z.ZodObject<{
@@ -4792,6 +5100,99 @@ declare const RelationshipStateUpdatedEventSchema: z.ZodObject<{
     updatedAt: z.ZodString;
 }, z.core.$strip>;
 
+declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
+
+/**
+ * Resolves a fully-specified `LLMConfigBase` for a given call site.
+ *
+ * Selection is a single-winner chain (see `selectWinningProfile`): the
+ * highest-precedence rung that names a usable, complete profile wins, and the
+ * resolved config is composed as code-owned schema defaults + the winning
+ * profile's fragment + the call site's own tuning tweak. No profile ever
+ * contributes a field to another profile — `deepMerge` here only lets nested
+ * tweaks (e.g. `thinking.enabled`) combine leaf-wise with the winner rather
+ * than wholesale-replacing sibling fields.
+ *
+ * Precedence of the selection chain (high → low):
+ *   1. `opts.overrideProfile` (per-turn / per-conversation pin)
+ *   2. `llm.activeProfile` — `mainAgent` only, since it IS that call site's
+ *      user-facing chat-model selection
+ *   3. `llm.callSites[callSite].profile` (the call site's named profile)
+ *   4. `CALL_SITE_DEFAULTS[callSite].profile` intent resolved through
+ *      `llm.defaultProvider`
+ *   5. balanced intent through `llm.defaultProvider` — the code-owned anchor
+ *      for profileless call sites, or when nothing above is usable
+ *
+ * A winner must carry its own `provider` AND `model`: the base layer's schema
+ * default identity never stands in for a selected profile. The anchor is
+ * code-owned and resolved through `llm.defaultProvider`, never through
+ * user-mutable state.
+ *
+ * `temperature`/`top_p` come only from the winner (or an explicit call-site
+ * tweak); `logitBias` only ever from the winner. These are provider-coupled, so
+ * a shadowed profile can never leak its sampling onto a different provider.
+ *
+ * `opts.forceOverrideProfile` is a no-op here: the override profile already
+ * sits at the top of the chain for every call site.
+ *
+ * Profile names are resolved against the effective profile catalog
+ * (code-defined defaults + workspace `llm.profiles`; see `getEffectiveProfile`).
+ * A "mix" profile is expanded to one of its arms by a seeded weighted pick (see
+ * `resolveProfileFragment` and `opts.selectionSeed`), uniformly wherever a name
+ * is dereferenced. Missing references silently fall through (no throw) so the
+ * resolver stays pure; schema validation catches unknown static references at
+ * config-load time.
+ *
+ * Nested objects (`thinking`, `contextWindow`, and
+ * `contextWindow.overflowRecovery`) are deep-merged so partial tweaks at any
+ * nesting level merge into — rather than replace — the corresponding base
+ * value.
+ *
+ * Pure & synchronous: no I/O, no async work. (Random selection only occurs for
+ * mix profiles when no `selectionSeed` is supplied; with a seed the pick is
+ * deterministic.)
+ */
+declare interface ResolveCallSiteOpts {
+    overrideProfile?: string;
+    /**
+     * Float `overrideProfile` above the call-site layers for non-main-agent call
+     * sites. Retained for API compatibility; under single-winner selection the
+     * override already sits at the top of the chain, so this is effectively a
+     * no-op. Inert when `overrideProfile` is absent or references a missing
+     * profile.
+     */
+    forceOverrideProfile?: boolean;
+    /**
+     * Per-conversation seed for expanding `mix` profiles. The chosen constituent
+     * is a deterministic function of `selectionSeed` + the mix profile's own
+     * name, so every `resolveCallSiteConfig` call for the same conversation picks
+     * the SAME arm (stable across turns, retries, and restarts). Pass the
+     * conversation id. When absent, the resolver falls back to a fresh random
+     * pick per call — acceptable only for one-shot/background call sites that
+     * resolve config exactly once per invocation.
+     */
+    selectionSeed?: string;
+    /**
+     * Invoked once for each mix profile the resolver expands, reporting which
+     * constituent was chosen. Used by A/B-eval recording (usage attribution).
+     */
+    onMixSelected?: (info: {
+        mixProfile: string;
+        chosenProfile: string;
+    }) => void;
+    /**
+     * Invoked once per chain rung that named a profile the resolver could not
+     * use, before resolution continues to the next rung. Fallback is silent to
+     * the call but must be visible in logs — callers on user-facing paths should
+     * log at warn.
+     */
+    onResolutionFallback?: (info: {
+        callSite: LLMCallSite;
+        requested: string;
+        reason: ResolutionFallbackReason;
+    }) => void;
+}
+
 /**
  * Resolve a credential reference to its plaintext value.
  *
@@ -4925,6 +5326,15 @@ export declare interface RunConversationTurnOptions {
      * controller fires, terminating the in-flight agent loop.
      */
     signal?: AbortSignal;
+    /**
+     * Conversation type for newly created conversations. When omitted,
+     * defaults to `"standard"` (visible in the sidebar). Set to
+     * `"background"` for plugin-driven conversations that should not
+     * appear in the sidebar's Recents grouping.
+     *
+     * Ignored when `conversationId` references an existing conversation.
+     */
+    conversationType?: "standard" | "background";
 }
 
 export declare interface RunConversationTurnResult {
@@ -5107,6 +5517,13 @@ export declare interface SendMessageConfig {
      * stripped before any provider wire request.
      */
     selectionSeed?: string;
+    /**
+     * Id of the user conversation that causally triggered this call, stamped by
+     * call sites so `UsageTrackingProvider` can attribute the usage-ledger event
+     * to the conversation (and, at flush time, its turn). A resolution/routing-
+     * time concern only; stripped before any provider wire request.
+     */
+    conversationId?: string;
     /**
      * Per-conversation prompt-cache key for providers with explicit prompt
      * caching (sent as the OpenAI `prompt_cache_key` request param). Set by
@@ -5588,6 +6005,34 @@ declare type SurfaceData = CardSurfaceData | ChoiceSurfaceData | CopyBlockSurfac
 
 declare type _SurfacesServerMessages = UiSurfaceShow | UiSurfaceUpdate | UiSurfaceDismiss | UiSurfaceComplete | UiSurfaceUndoResult;
 
+/**
+ * Delete `graph_node` Qdrant points whose backing `memory_graph_nodes` row no
+ * longer exists.
+ *
+ * `embedAndUpsert` treats the `memory_embeddings` cache write as best-effort: on
+ * a cache-write failure it logs and still upserts the Qdrant point, so a node
+ * can end up with a `graph_node` point but no cache row. Migration 340 discovers
+ * orphans only through cache rows, so those cacheless points survive its sweep;
+ * once migration 323 hard-deletes their backing nodes they keep consuming
+ * `searchGraphNodes` top-K slots (the query hydrates hits from
+ * `memory_graph_nodes` and silently drops rows that are gone).
+ *
+ * This enumerates the authoritative set of indexed `graph_node` points straight
+ * from Qdrant — the only place cacheless points are recorded — and deletes any
+ * whose `target_id` has no row in `memory_graph_nodes`. Membership is
+ * existence-based, matching migration 340: a soft-deleted node keeps its row
+ * (`fidelity = 'gone'`) and therefore its point.
+ *
+ * Idempotent: a second run finds no orphans. Deletion is by Qdrant payload
+ * (`target_type` + `target_id`) via `deleteByTarget`, so it removes cacheless
+ * points a cache lookup could never surface. Both the initial scroll and each
+ * delete go through the Qdrant circuit breaker: an already-open circuit surfaces
+ * as `QdrantCircuitOpenError` so the caller (the memory worker) defers the sweep
+ * instead of spending its bounded retries, and a transient failure propagates
+ * for retry on a later cycle.
+ */
+export declare function sweepOrphanedGraphNodePoints(qdrant: GraphNodeSweepClient): Promise<GraphNodeSweepResult>;
+
 declare type SyncChangedEvent = z.infer<typeof SyncChangedEventSchema>;
 
 declare const SyncChangedEventSchema: z.ZodObject<{
@@ -6007,8 +6452,27 @@ export declare interface ToolExecutionResult {
     content: string;
     /** When true, the agent loop treats `content` as an error and may surface it / retry. */
     isError: boolean;
+    /**
+     * Stable, machine-readable classification for an error result (e.g.
+     * `acp_claude_oauth_missing`). Threaded to the client on the `tool_result`
+     * event so surfaces can render a structured affordance for a known failure
+     * instead of re-parsing the human `content` string. Only meaningful when
+     * `isError` is true.
+     */
+    errorCode?: string;
     /** Optional short status message for client display (e.g. `"truncated"`, `"timed out"`). */
     status?: string;
+    /**
+     * Typed side channel from the app-builder executors to their post-execution
+     * side-effect hooks (`daemon/tool-side-effects.ts`): the exact app id the
+     * executor operated on. `app_id` is optional for the fallback tools
+     * (`app_update`, `app_refresh`, `app_generate_icon`) — when the model omits
+     * it the skill script resolves the conversation's active app — so hooks read
+     * this authoritative id instead of re-parsing the LLM-facing `content`
+     * payload, whose shape must stay decoupled from daemon logic (see
+     * assistant/AGENTS.md § Post-execution hooks). Set only by the app_* executors.
+     */
+    resolvedAppId?: string;
     /**
      * When true, the agent loop should yield control back to the user after
      * returning this result — tool results are pushed to history and the loop
@@ -6250,6 +6714,7 @@ declare const ToolResultEventSchema: z.ZodObject<{
             mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    errorCode: z.ZodOptional<z.ZodString>;
     completedAt: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 

package/index.js

@@ -4,11 +4,13 @@ export const CLI_COMMAND_HELP = api.CLI_COMMAND_HELP;
 export const CredentialResolutionError = api.CredentialResolutionError;
 export const HOOKS = api.HOOKS;
 export const INTERNAL_NUDGE_OUTPUT_SUPPRESSION = api.INTERNAL_NUDGE_OUTPUT_SUPPRESSION;
+export const REFUSAL_FALLBACK_TEXT = api.REFUSAL_FALLBACK_TEXT;
 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;
+export const createLiveVoiceConnection = api.createLiveVoiceConnection;
 export const deleteConversation = api.deleteConversation;
 export const doesSupportVision = api.doesSupportVision;
 export const embedAndUpsert = api.embedAndUpsert;
@@ -19,13 +21,18 @@ export const getConversation = api.getConversation;
 export const getConversationDirPath = api.getConversationDirPath;
 export const getMessages = api.getMessages;
 export const getModelProfiles = api.getModelProfiles;
+export const getWorkspaceDir = api.getWorkspaceDir;
 export const hasLexicalTokens = api.hasLexicalTokens;
 export const isConversationProcessing = api.isConversationProcessing;
 export const isMaxTokensStopReason = api.isMaxTokensStopReason;
+export const isToolResultMessage = api.isToolResultMessage;
+export const isVisionNotSupportedError = api.isVisionNotSupportedError;
+export const lastToolResultUserMessageIndex = api.lastToolResultUserMessageIndex;
 export const listCatalogSkills = api.listCatalogSkills;
 export const listConversations = api.listConversations;
 export const listInstalledSkills = api.listInstalledSkills;
 export const parseMessageMetadata = api.parseMessageMetadata;
+export const quarantineRefusedExchanges = api.quarantineRefusedExchanges;
 export const resolveCredential = api.resolveCredential;
 export const resolveMediaSourceData = api.resolveMediaSourceData;
 export const resolveUserName = api.resolveUserName;
@@ -33,6 +40,7 @@ export const runConversationTurn = api.runConversationTurn;
 export const searchMessageIdsLexical = api.searchMessageIdsLexical;
 export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
 export const stringifyMessageContent = api.stringifyMessageContent;
+export const sweepOrphanedGraphNodePoints = api.sweepOrphanedGraphNodePoints;
 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.10",
+  "version": "0.10.11-dev.202607212323.c5c49c0",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",