@vellumai/assistant 0.11.3 → 0.11.4-staging.2

package/src/config/__tests__/profile-materialization.test.ts

@@ -1,4 +1,17 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, mock, test } from "bun:test";
+
+// Entry-name folds are gated on the named row existing with an agreeing
+// kind, so the tests control the row store directly.
+const connectionRows = new Map<string, { name: string; provider: string }>([
+  ["anthropic-personal", { name: "anthropic-personal", provider: "anthropic" }],
+]);
+mock.module("../../persistence/db-connection.js", () => ({
+  getDb: () => ({}),
+}));
+mock.module("../../providers/inference/connections.js", () => ({
+  getConnection: (_db: unknown, name: string) =>
+    connectionRows.get(name) ?? null,
+}));
 
 import { VELLUM_MANAGED_CONNECTION_NAME } from "../../providers/vellum-model-routing.js";
 import { completeCustomProfile } from "../profile-materialization.js";
@@ -28,8 +41,10 @@ describe("completeCustomProfile", () => {
       model: "claude-fable-5",
     });
     expect(completed.model).toBe("claude-fable-5");
-    expect(completed.provider).toBe("anthropic");
-    expect(completed.provider_connection).toBe("anthropic-personal");
+    // The default's explicit binding is inherited IN the provider value
+    // (the entries-model representation), never as a stamped binding.
+    expect(completed.provider).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
     expect(completed.maxTokens).toBe(64000);
     expect(completed.effort).toBe("max");
     expect(completed.speed).toBe("standard");
@@ -78,12 +93,12 @@ describe("completeCustomProfile", () => {
     expect(completed.contextWindow?.overflowRecovery?.enabled).toBe(true);
   });
 
-  test("keeps the inherited provider when it serves the profile's model", () => {
+  test("inherits the default's binding as the entry name when the provider serves the model", () => {
     const completed = completeCustomProfile(fullDefault, {
       model: "claude-fable-5",
     });
-    expect(completed.provider).toBe("anthropic");
-    expect(completed.provider_connection).toBe("anthropic-personal");
+    expect(completed.provider).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
   });
 
   test("stamps the catalog owner for a model the default provider does not serve, and drops the default's connection", () => {
@@ -123,36 +138,77 @@ describe("completeCustomProfile", () => {
     expect(completed.provider_connection).toBeUndefined();
   });
 
-  test("inherits the vellum managed connection across a provider change, but only onto managed-routable providers", () => {
+  test("a managed default's binding becomes the routing identity, never a stamped field", () => {
     const managedDefault = LLMConfigBase.parse({
       ...fullDefault,
       provider_connection: VELLUM_MANAGED_CONNECTION_NAME,
     });
     const implied = completeCustomProfile(managedDefault, { model: "gpt-5.5" });
-    expect(implied.provider).toBe("openai");
-    expect(implied.provider_connection).toBe(VELLUM_MANAGED_CONNECTION_NAME);
+    expect(implied.provider).toBe("vellum");
+    expect(implied.provider_connection).toBeUndefined();
 
     const explicit = completeCustomProfile(managedDefault, {
       provider: "openai",
       model: "gpt-5.4",
     });
-    expect(explicit.provider_connection).toBe(VELLUM_MANAGED_CONNECTION_NAME);
+    expect(explicit.provider).toBe("vellum");
+    expect(explicit.provider_connection).toBeUndefined();
+  });
 
-    // The vellum connection can't route a non-managed provider; baking it in
-    // would fail dispatch's mismatch path instead of auto-resolving.
-    const nonRoutable = completeCustomProfile(managedDefault, {
-      provider: "openrouter",
-      model: "minimax/minimax-m3",
+  test("inherits the binding as the entry name even for a model unknown to the catalog", () => {
+    const completed = completeCustomProfile(fullDefault, {
+      model: "totally-custom-model",
     });
-    expect(nonRoutable.provider_connection).toBeUndefined();
+    expect(completed.provider).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
   });
 
-  test("keeps the inherited provider for a model unknown to the catalog", () => {
-    const completed = completeCustomProfile(fullDefault, {
+  test("a dangling default binding passes through as the legacy field", () => {
+    const dangling = LLMConfigBase.parse({
+      ...fullDefault,
+      provider_connection: "deleted-row",
+    });
+    const completed = completeCustomProfile(dangling, {
+      model: "claude-fable-5",
+    });
+    // Folding an unverifiable binding would hide it from the collapse
+    // migration's dangling recovery; the legacy field keeps it visible.
+    expect(completed.provider).toBe("anthropic");
+    expect(completed.provider_connection).toBe("deleted-row");
+  });
+
+  test("a kind-disagreeing default binding passes through as the legacy field", () => {
+    connectionRows.set("mislabeled", {
+      name: "mislabeled",
+      provider: "openai",
+    });
+    try {
+      const mismatched = LLMConfigBase.parse({
+        ...fullDefault,
+        provider_connection: "mislabeled",
+      });
+      const completed = completeCustomProfile(mismatched, {
+        model: "claude-fable-5",
+      });
+      expect(completed.provider).toBe("anthropic");
+      expect(completed.provider_connection).toBe("mislabeled");
+    } finally {
+      connectionRows.delete("mislabeled");
+    }
+  });
+
+  test("a managed default binding is not inherited when the identity cannot serve the model", () => {
+    const managedDefault = LLMConfigBase.parse({
+      ...fullDefault,
+      provider_connection: VELLUM_MANAGED_CONNECTION_NAME,
+    });
+    const completed = completeCustomProfile(managedDefault, {
       model: "totally-custom-model",
     });
+    // Dispatch auto-resolves by vendor instead of pinning an unservable
+    // managed route.
     expect(completed.provider).toBe("anthropic");
-    expect(completed.provider_connection).toBe("anthropic-personal");
+    expect(completed.provider_connection).toBeUndefined();
   });
 
   test("passes mix profiles through untouched", () => {

package/src/config/bundled-skills/acp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acp
-description: Spawn external coding agents via the Agent Client Protocol (ACP)
+description: Set up, authenticate, and run external coding agents (Claude Code, Codex) via the Agent Client Protocol
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🔗"
@@ -8,13 +8,12 @@ metadata:
     display-name: "ACP"
     category: "development"
     activation-hints:
-      - "User asks to use Claude Code or Codex to do something"
-      - "User wants to delegate a coding task to Claude Code, Codex, or another ACP agent"
-      - "User wants to hand a coding task to another agent and check on it later"
-      - "User wants to spawn an external coding agent that runs autonomously and streams results back"
-      - "User mentions ACP, claude-agent-acp, codex-acp, or running multiple coding agents in parallel"
+      - "User wants to set up, install, configure, authenticate, or connect Claude Code or Codex"
+      - "User asks to use Claude Code or Codex, or delegate a coding task to an ACP agent"
+      - "User wants an agent to work autonomously and report back later"
+      - "User mentions ACP, claude-agent-acp, or codex-acp"
     avoid-when:
-      - "Task is small enough to do inline with the assistant's own tools - no need for an external agent"
+      - "The task is small enough to do inline"
 ---
 
 ACP agent orchestration - spawn external coding agents (Claude Code, Codex) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.

package/src/config/bundled-skills/document-editor/SKILL.md

@@ -33,9 +33,9 @@ Write and edit long-form documents using the built-in rich text editor. Document
 
 This is the default path when the user asks you to write something.
 
-1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble. Anything you pass as `initial_content` is saved right then, so the first `document_update` must start with the next chunk rather than repeating it.
 2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, _italic_, code blocks, tables, lists, blockquotes as appropriate.
-3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. When you are streaming into the document you just created, `surface_id` is optional — omit it and pass only `content`, and the update targets that document. The user experiences real-time content appearing as you write.
+3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. Each append carries ONLY that chunk: content already in the document is committed, and resending it would print it twice. When you are streaming into the document you just created, `surface_id` is optional: omit it and pass only `content`, and the update targets that document. The user experiences real-time content appearing as you write.
 
 ### Recovering from a failed update
 

package/src/config/bundled-skills/document-editor/TOOLS.json

@@ -33,7 +33,7 @@
           },
           "initial_content": {
             "type": "string",
-            "description": "Initial Markdown content to populate the editor (optional)"
+            "description": "Initial Markdown content to populate the editor (optional). It is saved as soon as the document is created, so the first document_update append must start with the NEXT chunk, never with this text again."
           }
         }
       },
@@ -54,7 +54,7 @@
           },
           "content": {
             "type": "string",
-            "description": "Markdown content to set or append"
+            "description": "Markdown content to set or append. In append mode, send only the new chunk: whatever is already in the document, including document_create's initial_content, is committed and must not be resent."
           },
           "mode": {
             "type": "string",

package/src/config/bundled-skills/media-processing/services/preprocess.ts

@@ -19,6 +19,7 @@ import {
   updateProcessingStage,
 } from "../../../../persistence/media-store.js";
 import { resolveBatchTranscriber } from "../../../../providers/speech-to-text/resolve.js";
+import type { BatchTranscriber } from "../../../../stt/types.js";
 import { silentlyWithLog } from "../../../../util/silently.js";
 import {
   FFMPEG_PALETTE_TIMEOUT_MS,
@@ -459,10 +460,19 @@ export async function preprocessForAsset(
     const allFramePaths: string[] = [];
 
     // Resolve the STT transcriber once for all segments to avoid repeated
-    // credential lookups in the per-segment loop.
-    const transcriber = options.includeAudio
-      ? await resolveBatchTranscriber()
-      : null;
+    // credential lookups in the per-segment loop. A resolver failure degrades
+    // to transcript-less segments like an absent provider does, reporting the
+    // reason on the progress stream rather than killing the whole run.
+    let transcriber: BatchTranscriber | null = null;
+    if (options.includeAudio) {
+      try {
+        transcriber = await resolveBatchTranscriber();
+      } catch (err) {
+        onProgress?.(
+          `Audio transcription unavailable: ${(err as Error).message}\n`,
+        );
+      }
+    }
 
     const scaleFilter = `scale='if(gt(iw,ih),-1,${config.shortEdge})':'if(gt(iw,ih),${config.shortEdge},-1)'`;
 

package/src/config/bundled-skills/settings/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "voice_config_update",
-      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, google-gemini, openai-whisper, xai. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (daemon route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 50 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT. Changes persist to services.stt / services.tts config and take effect immediately.",
+      "description": "Update a voice configuration setting. Use tts_provider / stt_provider to switch the active TTS / STT provider. Provider \"vellum\" is Vellum-managed speech (billed to your organization; requires a Vellum platform connection via 'assistant platform connect'); any other provider uses the user's own API key. Valid TTS providers come from the provider catalog (vellum, elevenlabs, fish-audio, deepgram, xai); valid STT providers: vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai. deepgram-flux is streaming-only: it serves live speech (voice mode, dictation) but cannot transcribe audio files or voice messages, so do not recommend it when the user wants file transcription. Use tts_voice_id to change the voice; it targets whichever TTS provider is currently active. For elevenlabs, pass an ElevenLabs voice ID. For vellum (managed), pass a managed voice model ID: this may be an ElevenLabs voice ID (managed speech serves the same ElevenLabs voices) or a Deepgram Aura model ID (e.g. aura-2-thalia-en); only rate-carded voices synthesize, so prefer models from the managed catalog (assistant route GET tts/managed-voices, also used by the web voice picker). For deepgram, pass a Deepgram Aura model ID. Use fish_audio_reference_id for Fish Audio voice reference. Use stt_language to set the spoken language for speech recognition: one of the 50 base language codes on the verified Deepgram nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or \"multi\" for code-switching mid-sentence across its 10-language roster (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch; e.g. Hinglish); plain language names like \"tamil\" or \"multilingual\" are accepted and normalized. Accepted values follow the configured STT provider: vellum-managed and deepgram accept the full roster plus \"multi\"; xai accepts only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) and rejects \"multi\" and the extended codes (both are verified for Deepgram nova-3 only); google-gemini / openai-whisper auto-detect natively and deepgram-flux runs an English-only model, so the value persists but is ignored while they are active. Deepgram uses the same API key for TTS and STT, and deepgram-flux shares it too. Changes persist to services.stt / services.tts config and take effect immediately.",
       "category": "system",
       "risk": "low",
       "input_schema": {
@@ -20,10 +20,10 @@
               "tts_provider",
               "tts_voice_id"
             ],
-            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it). Deepgram shares one API key across TTS and STT."
+            "description": "The voice setting to change. tts_provider / stt_provider select the active provider for each service (\"vellum\" = Vellum-managed speech; anything else = the user's own API key). tts_voice_id sets the voice for the currently active TTS provider (ElevenLabs voice ID for elevenlabs; a managed voice model ID for vellum, meaning an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en; a Deepgram Aura model ID for deepgram; voice ID for xai). fish_audio_reference_id sets the Fish Audio voice reference. stt_language sets the spoken language for speech recognition (vellum-managed/deepgram: the full roster plus \"multi\"; xai: only the 10 multilingual-roster codes, with \"multi\" and the extended codes rejected; google-gemini and openai-whisper auto-detect and ignore it; deepgram-flux is English-only and ignores it). Deepgram shares one API key across TTS and STT, and deepgram-flux uses that same key."
           },
           "value": {
-            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, google-gemini, openai-whisper, xai. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 50 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
+            "description": "The new value for the setting. For tts_provider: one of vellum, elevenlabs, fish-audio, deepgram, xai. For stt_provider: one of vellum, deepgram, deepgram-flux, google-gemini, openai-whisper, xai; deepgram-flux serves live speech only and cannot transcribe files. For tts_voice_id: a voice ID for the active TTS provider: an alphanumeric ElevenLabs voice ID (elevenlabs), a managed voice model ID which may be an ElevenLabs voice ID or a Deepgram Aura model ID like aura-2-thalia-en (vellum), or a Deepgram Aura model ID (deepgram). For fish_audio_reference_id: a Fish Audio voice reference ID. For stt_language: one of the 50 base codes on the nova-3 monolingual roster (e.g. en, es, hi, ta, zh, ko), or multi (code-switching across its 10-language roster); language names like \"hindi\", \"tamil\", or \"multilingual\" are also accepted and normalized; when the configured STT provider is xai, only the 10 multilingual-roster codes (en, es, fr, de, hi, ru, pt, ja, it, nl) are accepted. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
           }
         }
       },

package/src/config/bundled-skills/settings/tools/navigate-settings-tab.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import type { ToolContext } from "../../../../tools/types.js";
+import { run } from "./navigate-settings-tab.js";
+
+let sentMessages: Array<{ type: string; [key: string]: unknown }> = [];
+
+function makeContext(overrides?: Partial<ToolContext>): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "conv-xyz",
+    trustClass: "guardian",
+    sendToClient: (msg) => {
+      sentMessages.push(msg);
+    },
+    ...overrides,
+  };
+}
+
+describe("navigate_settings_tab tool", () => {
+  beforeEach(() => {
+    sentMessages = [];
+  });
+
+  test("navigates to the Voice tab and hints the inline picker", async () => {
+    const result = await run({ tab: "Voice" }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages).toEqual([{ type: "navigate_settings", tab: "Voice" }]);
+    expect(result.content).toStartWith("Opened settings to the Voice tab.");
+    expect(result.content).toContain(
+      'ui_show { surface_type: "voice_picker", data: {} }',
+    );
+  });
+
+  test("leaves a non-Voice tab's result unchanged", async () => {
+    const result = await run({ tab: "Billing" }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages).toEqual([
+      { type: "navigate_settings", tab: "Billing" },
+    ]);
+    expect(result.content).toBe("Opened settings to the Billing tab.");
+    expect(result.content).not.toContain("voice_picker");
+  });
+
+  test("resolves legacy tab aliases without hinting", async () => {
+    const result = await run({ tab: "Archived Conversations" }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(sentMessages).toEqual([
+      { type: "navigate_settings", tab: "Archive" },
+    ]);
+    expect(result.content).toBe("Opened settings to the Archive tab.");
+    expect(result.content).not.toContain("voice_picker");
+  });
+
+  test("rejects an unknown tab without navigating", async () => {
+    const result = await run({ tab: "Telepathy" }, makeContext());
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('unknown tab "Telepathy"');
+    expect(sentMessages).toEqual([]);
+  });
+});

package/src/config/bundled-skills/settings/tools/navigate-settings-tab.ts

@@ -2,6 +2,7 @@ import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
+import { voicePickerHint } from "./shared.js";
 
 const SETTINGS_TABS = [
   "General",
@@ -23,6 +24,10 @@ const LEGACY_TAB_ALIASES: Record<string, SettingsTab> = {
   "Archived Conversations": "Archive",
 };
 
+const VOICE_TAB_PICKER_HINT = voicePickerHint(
+  "which puts the picker in the conversation without navigating away. Navigating here is right only when the user explicitly asked to open Settings.",
+);
+
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -45,8 +50,9 @@ export async function run(
     });
   }
 
+  const opened = `Opened settings to the ${tab} tab.`;
   return {
-    content: `Opened settings to the ${tab} tab.`,
+    content: tab === "Voice" ? `${opened} ${VOICE_TAB_PICKER_HINT}` : opened,
     isError: false,
   };
 }

package/src/config/bundled-skills/settings/tools/shared.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared helpers for the settings skill's tool executors.
+ */
+
+/**
+ * Steer the model back to the inline voice picker.
+ *
+ * Both settings tools a "change my voice" request can land on (the Voice tab
+ * navigation and a managed `tts_voice_id` write) end by naming the picker, so
+ * the invocation itself lives here: one edit keeps both tools teaching the same
+ * call. Each caller supplies its own tail, because the reason the picker is
+ * better differs by the tool the model just reached for.
+ */
+export function voicePickerHint(tail: string): string {
+  return `Next time the user wants to change or hear a voice, prefer \`ui_show { surface_type: "voice_picker", data: {} }\`, ${tail}`;
+}

package/src/config/bundled-skills/settings/tools/voice-config-update.ts

@@ -19,6 +19,7 @@ import {
 } from "../../../loader.js";
 import { VALID_CONVERSATION_TIMEOUTS } from "../../../schemas/elevenlabs.js";
 import { VALID_STT_PROVIDERS } from "../../../schemas/stt.js";
+import { voicePickerHint } from "./shared.js";
 
 /**
  * Valid voice config settings and their UserDefaults key mappings.
@@ -187,6 +188,19 @@ const STT_LANGUAGE_ALIASES: Record<
   "code-switching": "multi",
 };
 
+/**
+ * Same steer `navigate_settings_tab` puts on the Voice tab, applied to the
+ * strongest competing affordance: this tool's description coaches the model to
+ * read the managed catalog and set `tts_voice_id` itself, which is exactly the
+ * "assistant names voices in prose" outcome the inline picker exists to
+ * replace. Managed only, because that is the catalog the picker renders. The
+ * write still happens and the result stays non-error; this only redirects the
+ * next request.
+ */
+const MANAGED_VOICE_PICKER_HINT = voicePickerHint(
+  "which lets them hear and pick from the managed catalog in the conversation. Set the id here only when the user named a specific voice.",
+);
+
 function validateSetting(
   setting: string,
   value: unknown,
@@ -530,10 +544,14 @@ export async function run(
     AUTO_DETECT_STT_PROVIDERS.has(activeSttProviderId)
       ? ` Note: the configured STT provider (${activeSttProviderId}) auto-detects the spoken language natively and ignores this setting.`
       : "";
+  const pickerNote =
+    setting === "tts_voice_id" && activeTtsProviderId === "vellum"
+      ? ` ${MANAGED_VOICE_PICKER_HINT}`
+      : "";
   return {
     content: `${friendlyName} updated to ${JSON.stringify(
       validation.coerced,
-    )}.${broadcastNote}${autoDetectNote}`,
+    )}.${broadcastNote}${autoDetectNote}${pickerNote}`,
     isError: false,
   };
 }

package/src/config/bundled-skills/transcribe/tools/transcribe-media.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { BatchTranscriber } from "../../../../stt/types.js";
+import { SttError } from "../../../../stt/types.js";
 import type { ToolContext } from "../../../../tools/types.js";
 
 // ---------------------------------------------------------------------------
@@ -8,9 +9,15 @@ import type { ToolContext } from "../../../../tools/types.js";
 // ---------------------------------------------------------------------------
 
 let mockTranscriber: BatchTranscriber | null = null;
+let mockResolveError: Error | null = null;
 
 mock.module("../../../../providers/speech-to-text/resolve.js", () => ({
-  resolveBatchTranscriber: async () => mockTranscriber,
+  resolveBatchTranscriber: async () => {
+    if (mockResolveError) {
+      throw mockResolveError;
+    }
+    return mockTranscriber;
+  },
 }));
 
 // Track calls to spawnWithTimeout so we can simulate ffmpeg/ffprobe results.
@@ -103,6 +110,7 @@ function makeMockTranscriber(
 describe("transcribe_media tool", () => {
   beforeEach(() => {
     mockTranscriber = null;
+    mockResolveError = null;
     spawnResults = {};
     accessiblePaths = new Set();
     mockFileContents = {};
@@ -119,6 +127,19 @@ describe("transcribe_media tool", () => {
         "No speech-to-text provider is configured",
       );
     });
+
+    test("surfaces a resolver error verbatim rather than the not-configured copy", async () => {
+      const reason =
+        'Deepgram Flux is streaming-only. Batch transcription requires the deepgram provider: set services.stt.provider to "deepgram".';
+      mockResolveError = new SttError("provider-error", reason, {
+        userFacing: true,
+      });
+
+      const result = await run({ file_path: "/tmp/test.mp3" }, makeContext());
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toBe(reason);
+    });
   });
 
   describe("input validation", () => {

package/src/config/bundled-skills/transcribe/tools/transcribe-media.ts

@@ -234,8 +234,15 @@ export async function run(
     };
   }
 
-  // Resolve the configured STT provider
-  const transcriber = await resolveBatchTranscriber();
+  // Resolve the configured STT provider. A typed resolver error already names
+  // the mismatch (e.g. a streaming-only provider) and its fix, so it reaches
+  // the model verbatim rather than as the "nothing configured" copy below.
+  let transcriber: BatchTranscriber | null;
+  try {
+    transcriber = await resolveBatchTranscriber();
+  } catch (err) {
+    return { content: (err as Error).message, isError: true };
+  }
   if (!transcriber) {
     return {
       content:

package/src/config/call-site-defaults.ts

@@ -121,22 +121,21 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
     effort: "low",
     thinking: { enabled: false },
   },
-  // Endpoint decisions gate live-voice turn-end latency, and `cost-optimized`'s
-  // upstream cannot fit any usable decision budget (~1s+ per forced tool call).
+  // Progress narration only helps when it arrives before the next real output.
   // `latency-optimized` is the latency-class profile (see
   // default-profile-catalog.ts): managed installs get the pinned latency model,
   // BYOK installs resolve their own provider's latency model through the intent
   // table rather than a model id they may hold no credential for. The profile
   // is user-facing ("Speed"), so a user edit to it moves this call site too.
-  voiceFrontDecision: {
+  voiceProgressNarration: {
     profile: "latency-optimized",
     effort: "low",
     thinking: { enabled: false },
   },
   // The front-door leg fronts EVERY unified live-voice turn and its leading
   // tokens ARE the endpointing/triage verdict, so both TTFT variance and
-  // judgment quality gate the whole call. Same latency class as the endpoint
-  // decider: live drives showed the cost-optimized upstream with multi-second
+  // judgment quality gate the whole call. Live drives showed the
+  // cost-optimized upstream with multi-second
   // cross-session TTFT tails and over-escalation of small talk under open-task
   // context pressure.
   voiceFrontDoor: {