@vellumai/assistant 0.6.2 → 0.6.4

package/src/config/bundled-skills/media-processing/__tests__/preprocess-audio.test.ts

@@ -0,0 +1,141 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mocks — must be declared before the subject import
+// ---------------------------------------------------------------------------
+
+let mockTranscribeResult: string = "";
+
+mock.module("../services/audio-transcribe.js", () => ({
+  transcribeSegmentAudio: async () => mockTranscribeResult,
+}));
+
+let spawnExitCode = 0;
+
+mock.module("../../../../util/spawn.js", () => ({
+  spawnWithTimeout: async () => ({
+    exitCode: spawnExitCode,
+    stdout: "",
+    stderr: "",
+  }),
+  FFMPEG_PALETTE_TIMEOUT_MS: 10_000,
+  FFMPEG_PREPROCESS_TIMEOUT_MS: 60_000,
+}));
+
+mock.module("../../../../memory/media-store.js", () => ({
+  getMediaAssetById: (id: string) => ({
+    id,
+    mediaType: "video",
+    filePath: "/tmp/videos/test.mp4",
+    durationSeconds: 30,
+  }),
+  getProcessingStagesForAsset: () => [],
+  createProcessingStage: () => ({ id: "stage-1" }),
+  updateProcessingStage: () => {},
+  deleteKeyframesForAsset: () => {},
+  insertKeyframesBatch: () => {},
+}));
+
+// Mock fs — readdir must return frame filenames to produce segments with frames
+let mockReaddirFiles: string[] = ["frame-000001.jpg", "frame-000002.jpg"];
+
+mock.module("node:fs/promises", () => ({
+  mkdir: async () => {},
+  readdir: async () => mockReaddirFiles,
+  readFile: async () => "[]",
+  rename: async () => {},
+  rm: async () => {},
+  writeFile: async () => {},
+}));
+
+mock.module("../../../../util/silently.js", () => ({
+  silentlyWithLog: async () => {},
+}));
+
+// ---------------------------------------------------------------------------
+// Subject import (after mocks)
+// ---------------------------------------------------------------------------
+
+import { preprocessForAsset } from "../services/preprocess.js";
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("preprocessForAsset — audio transcript enrichment", () => {
+  beforeEach(() => {
+    mockTranscribeResult = "";
+    spawnExitCode = 0;
+    mockReaddirFiles = ["frame-000001.jpg", "frame-000002.jpg"];
+  });
+
+  test("attaches transcript to segments when transcription returns text", async () => {
+    mockTranscribeResult = "Hello world, this is a transcript.";
+
+    const manifest = await preprocessForAsset("asset-1", {
+      includeAudio: true,
+      segmentDuration: 30,
+    });
+
+    expect(manifest.segments.length).toBeGreaterThan(0);
+    for (const seg of manifest.segments) {
+      expect(seg.transcript).toBe("Hello world, this is a transcript.");
+    }
+  });
+
+  test("omits transcript field when transcription returns empty string", async () => {
+    mockTranscribeResult = "";
+
+    const manifest = await preprocessForAsset("asset-1", {
+      includeAudio: true,
+      segmentDuration: 30,
+    });
+
+    expect(manifest.segments.length).toBeGreaterThan(0);
+    for (const seg of manifest.segments) {
+      expect(seg.transcript).toBeUndefined();
+    }
+  });
+
+  test("does not set transcript when includeAudio is false", async () => {
+    mockTranscribeResult = "Should not appear";
+
+    const manifest = await preprocessForAsset("asset-1", {
+      includeAudio: false,
+      segmentDuration: 30,
+    });
+
+    expect(manifest.segments.length).toBeGreaterThan(0);
+    for (const seg of manifest.segments) {
+      expect(seg.transcript).toBeUndefined();
+    }
+  });
+
+  test("does not set transcript when includeAudio is omitted", async () => {
+    mockTranscribeResult = "Should not appear";
+
+    const manifest = await preprocessForAsset("asset-1", {
+      segmentDuration: 30,
+    });
+
+    expect(manifest.segments.length).toBeGreaterThan(0);
+    for (const seg of manifest.segments) {
+      expect(seg.transcript).toBeUndefined();
+    }
+  });
+
+  test("does not throw when transcription returns empty for all segments", async () => {
+    mockTranscribeResult = "";
+
+    const manifest = await preprocessForAsset("asset-1", {
+      includeAudio: true,
+      segmentDuration: 15,
+    });
+
+    // Should complete successfully with segments but no transcripts
+    expect(manifest.segments.length).toBeGreaterThan(0);
+    expect(manifest.segments.every((s) => s.transcript === undefined)).toBe(
+      true,
+    );
+  });
+});

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

@@ -1,34 +1,50 @@
 /**
  * Per-segment audio transcription for the video processing pipeline.
- * Extracts audio for a time range and transcribes it via OpenAI Whisper API
- * or local whisper.cpp, returning the transcript text.
+ * Extracts audio for a time range and transcribes it via the configured
+ * STT service (resolved through `resolveBatchTranscriber`), returning the
+ * transcript text.
  */
 
 import { randomUUID } from "node:crypto";
-import { access, readFile, unlink } from "node:fs/promises";
+import { readFile, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { resolveBatchTranscriber } from "../../../../providers/speech-to-text/resolve.js";
+import type { BatchTranscriber } from "../../../../stt/types.js";
 import { spawnWithTimeout } from "../../../../util/spawn.js";
 
 const FFMPEG_TIMEOUT_MS = 60_000;
-const API_REQUEST_TIMEOUT_MS = 120_000;
-const LOCAL_CHUNK_TIMEOUT_MS = 120_000;
+const STT_REQUEST_TIMEOUT_MS = 120_000;
 
 /**
  * Transcribe the audio from a specific time range of a video file.
  * Returns the transcript text, or empty string on failure (graceful degradation).
+ *
+ * Accepts an optional pre-resolved `BatchTranscriber` to avoid repeated
+ * credential lookups when transcribing multiple segments in a loop. When
+ * omitted, resolves the transcriber on demand via `resolveBatchTranscriber()`.
+ *
+ * Returns empty string when no provider is configured, the provider call
+ * fails, or ffmpeg extraction fails — this preserves preprocess resilience.
  */
 export async function transcribeSegmentAudio(
   videoPath: string,
   startSeconds: number,
   durationSeconds: number,
-  mode: "api" | "local",
-  options?: { apiKey?: string },
+  transcriber?: BatchTranscriber | null,
 ): Promise<string> {
   const tmpWav = join(tmpdir(), `vellum-seg-audio-${randomUUID()}.wav`);
 
   try {
+    // Use the provided transcriber or resolve on demand.
+    // null = "already resolved, no provider"; only re-resolve when undefined (not passed).
+    const resolved =
+      transcriber === undefined ? await resolveBatchTranscriber() : transcriber;
+    if (!resolved) {
+      return "";
+    }
+
     // Extract audio for the time range as 16kHz mono WAV
     const extractResult = await spawnWithTimeout(
       [
@@ -56,10 +72,15 @@ export async function transcribeSegmentAudio(
       return "";
     }
 
-    if (mode === "api") {
-      return await transcribeViaApi(tmpWav, options?.apiKey);
-    }
-    return await transcribeViaLocal(tmpWav);
+    // Send extracted WAV through the provider-agnostic transcriber
+    const audioBuffer = await readFile(tmpWav);
+    const result = await resolved.transcribe({
+      audio: audioBuffer,
+      mimeType: "audio/wav",
+      signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
+    });
+
+    return result.text?.trim() ?? "";
   } catch {
     return "";
   } finally {
@@ -70,79 +91,3 @@ export async function transcribeSegmentAudio(
     }
   }
 }
-
-async function transcribeViaApi(
-  audioPath: string,
-  apiKey?: string,
-): Promise<string> {
-  if (!apiKey) return "";
-
-  const audioData = await readFile(audioPath);
-  const formData = new FormData();
-  formData.append(
-    "file",
-    new Blob([audioData], { type: "audio/wav" }),
-    "audio.wav",
-  );
-  formData.append("model", "whisper-1");
-
-  const response = await fetch(
-    "https://api.openai.com/v1/audio/transcriptions",
-    {
-      method: "POST",
-      headers: { Authorization: `Bearer ${apiKey}` },
-      body: formData,
-      signal: AbortSignal.timeout(API_REQUEST_TIMEOUT_MS),
-    },
-  );
-
-  if (!response.ok) return "";
-
-  const result = (await response.json()) as { text?: string };
-  return result.text?.trim() ?? "";
-}
-
-async function transcribeViaLocal(audioPath: string): Promise<string> {
-  // Check if whisper-cpp is available
-  const whichResult = await spawnWithTimeout(["which", "whisper-cpp"], 5_000);
-  if (whichResult.exitCode !== 0) return "";
-
-  // Resolve model path
-  const modelPath = await resolveWhisperModel();
-  if (!modelPath) return "";
-
-  const result = await spawnWithTimeout(
-    ["whisper-cpp", "-m", modelPath, "-f", audioPath, "--no-timestamps"],
-    LOCAL_CHUNK_TIMEOUT_MS,
-  );
-
-  if (result.exitCode !== 0) return "";
-
-  return result.stdout
-    .split("\n")
-    .map((l) => l.trim())
-    .filter((l) => l.length > 0)
-    .join(" ")
-    .trim();
-}
-
-async function resolveWhisperModel(): Promise<string | null> {
-  const homeDir = process.env.HOME ?? "/tmp";
-  const candidates = [
-    join(homeDir, ".vellum", "models", "ggml-base.en.bin"),
-    join(homeDir, ".vellum", "models", "ggml-base.bin"),
-    "/usr/local/share/whisper-cpp/models/ggml-base.en.bin",
-    "/opt/homebrew/share/whisper-cpp/models/ggml-base.en.bin",
-  ];
-
-  for (const p of candidates) {
-    try {
-      await access(p);
-      return p;
-    } catch {
-      /* next */
-    }
-  }
-
-  return null;
-}

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

@@ -18,6 +18,7 @@ import {
   type ProcessingStage,
   updateProcessingStage,
 } from "../../../../memory/media-store.js";
+import { resolveBatchTranscriber } from "../../../../providers/speech-to-text/resolve.js";
 import { silentlyWithLog } from "../../../../util/silently.js";
 import {
   FFMPEG_PALETTE_TIMEOUT_MS,
@@ -92,8 +93,6 @@ export interface PreprocessOptions {
   detectDeadTime?: boolean;
   shortEdge?: number;
   includeAudio?: boolean;
-  transcriptionMode?: "api" | "local";
-  openaiApiKey?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -453,6 +452,12 @@ export async function preprocessForAsset(
     const segments: Segment[] = [];
     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;
+
     const scaleFilter = `scale='if(gt(iw,ih),-1,${config.shortEdge})':'if(gt(iw,ih),${config.shortEdge},-1)'`;
 
     for (let i = 0; i < rawSegments.length; i++) {
@@ -529,8 +534,7 @@ export async function preprocessForAsset(
           asset.filePath,
           seg.startSeconds,
           seg.endSeconds - seg.startSeconds,
-          options.transcriptionMode ?? "local",
-          { apiKey: options.openaiApiKey },
+          transcriber,
         );
         if (transcript) {
           segment.transcript = transcript;

package/src/config/bundled-skills/media-processing/tools/extract-keyframes.ts

@@ -4,7 +4,6 @@ import {
   getKeyframesForAsset,
   getMediaAssetById,
 } from "../../../../memory/media-store.js";
-import { getProviderKeyAsync } from "../../../../security/secure-keys.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -26,13 +25,6 @@ export async function run(
   }
 
   const includeAudio = Boolean(input.include_audio);
-  const transcriptionMode =
-    (input.transcription_mode as "api" | "local") || undefined;
-
-  let openaiApiKey: string | undefined;
-  if (includeAudio && (!transcriptionMode || transcriptionMode === "api")) {
-    openaiApiKey = await getProviderKeyAsync("openai");
-  }
 
   const options: PreprocessOptions = {
     intervalSeconds: (input.interval_seconds as number) || undefined,
@@ -45,8 +37,6 @@ export async function run(
         : undefined,
     shortEdge: (input.short_edge as number) || undefined,
     includeAudio,
-    transcriptionMode,
-    openaiApiKey,
   };
 
   try {

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

@@ -17,15 +17,15 @@ You are a unified messaging assistant with access to multiple platforms (Gmail,
 
 ## External Identity
 
-When composing messages on behalf of your user to external recipients, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from USER.md. Don't volunteer that you are an AI unless directly asked.
+When composing messages on behalf of your user to external recipients, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from their user persona file (`users/<slug>.md`). Don't volunteer that you are an AI unless directly asked.
 
 For Email management (archive, label, triage, declutter), load the **gmail** or **outlook** skill. For email sequences, load the **sequences** skill.
 
 ## Email Routing Priority
 
-When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail or Outlook, not the assistant's AgentMail address.
+When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail or Outlook, not the assistant's @vellum.me address.
 
-Do not offer AgentMail as an option or mention it unless the user specifically asks. If Gmail and Outlookk are not connected, guide them through setup - do not suggest AgentMail as an alternative.
+Do not offer the assistant's own email as an option unless the user specifically asks. If Gmail and Outlook are not connected, guide them through setup.
 
 ## Communication Style
 

package/src/config/bundled-skills/messaging/tools/messaging-archive-by-sender.ts

@@ -8,9 +8,9 @@ export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  if (!context.triggeredBySurfaceAction) {
+  if (!context.triggeredBySurfaceAction && !context.batchAuthorizedByTask) {
     return err(
-      "This tool requires user confirmation via a surface action. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
+      "This tool requires either a surface action or a scheduled task run with this tool in required_tools. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
     );
   }
 

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

@@ -31,9 +31,16 @@ All tools above are Outlook-specific. For shared operations (send, read, search,
 
 ## Email Routing Priority
 
-When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email (Outlook)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Outlook, not the assistant's AgentMail address.
+When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email (Outlook)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Outlook, not the assistant's @vellum.me address.
 
-Do not offer AgentMail as an option or mention it unless the user specifically asks. If Outlook is not connected, guide them through Outlook setup - do not suggest AgentMail as an alternative.
+Do not offer the assistant's own email as an option unless the user specifically asks. If Outlook is not connected, guide them through Outlook setup.
+
+## Connection Setup
+
+### Outlook
+
+1. **Try connecting directly first.** Run `assistant oauth status outlook`. This will show whether or not the user had previously connected their Outlook/Microsoft account. If so, they are ready to go.
+2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
 
 ## Communication Style
 

package/src/config/bundled-skills/outlook/tools/outlook-unsubscribe.ts

@@ -23,9 +23,9 @@ export async function run(
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
   const account = input.account as string | undefined;
-  if (!context.triggeredBySurfaceAction) {
+  if (!context.triggeredBySurfaceAction && !context.batchAuthorizedByTask) {
     return err(
-      "This tool requires user confirmation via a surface action. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
+      "This tool requires either a surface action or a scheduled task run with this tool in required_tools. Present results in a selection table with action buttons and wait for the user to click before proceeding.",
     );
   }
 

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -21,11 +21,11 @@ You are helping the user set up and manage phone calls via Twilio. This skill co
 
 ## External Identity
 
-When speaking on behalf of your user during calls, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from USER.md. Don't volunteer that you are an AI unless directly asked.
+When speaking on behalf of your user during calls, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from their user persona file (`users/<slug>.md`). Don't volunteer that you are an AI unless directly asked.
 
 # Overview
 
-The calling system uses Twilio's ConversationRelay for both **outbound** and **inbound** voice calls with **ElevenLabs** providing the text-to-speech voice. After Twilio setup, the assistant configures ElevenLabs as the TTS provider and prompts the user to choose a voice from a curated list of supported options.
+The calling system uses Twilio's ConversationRelay for both **outbound** and **inbound** voice calls. The text-to-speech voice is provided by the globally configured TTS provider (set via `services.tts.provider`, default: ElevenLabs). After Twilio setup, the assistant prompts the user to choose a voice from a curated list of supported options.
 
 # Initial Setup
 

package/src/config/bundled-skills/phone-calls/references/CONFIG.md

@@ -2,24 +2,33 @@
 
 All call-related settings can be managed via `assistant config`:
 
-| Setting                                     | Description                                                                                                                   | Default                                                                                                  |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `calls.enabled`                             | Master switch for the calling feature                                                                                         | `false`                                                                                                  |
-| `calls.provider`                            | Voice provider (currently only `twilio`)                                                                                      | `twilio`                                                                                                 |
-| `calls.maxDurationSeconds`                  | Maximum call length in seconds                                                                                                | `3600` (1 hour)                                                                                          |
-| `calls.userConsultTimeoutSeconds`           | How long to wait for user answers                                                                                             | `120` (2 min)                                                                                            |
-| `calls.disclosure.enabled`                  | Whether the AI announces itself at call start                                                                                 | `true`                                                                                                   |
-| `calls.disclosure.text`                     | The disclosure message spoken at call start                                                                                   | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
-| `calls.model`                               | Override LLM model for call orchestration                                                                                     | _(uses default model)_                                                                                   |
-| `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection                                                                                      | `true`                                                                                                   |
-| `calls.callerIdentity.userNumber`           | E.164 phone number for user-number mode                                                                                       | _(empty)_                                                                                                |
-| `calls.voice.language`                      | Language code for TTS and transcription                                                                                       | `en-US`                                                                                                  |
-| `calls.voice.transcriptionProvider`         | Speech-to-text provider (`Deepgram`, `Google`)                                                                                | `Deepgram`                                                                                               |
-| `elevenlabs.voiceId`                        | ElevenLabs voice ID used by both in-app TTS and phone calls. Set during setup from the curated voice list. Defaults to Amelia | `ZF6FPAbjXT4488VcRRnw`                                                                                   |
-| `elevenlabs.voiceModelId`                   | Optional Twilio ConversationRelay model suffix. Leave empty to send bare `voiceId`                                            | _(empty)_                                                                                                |
-| `elevenlabs.speed`                          | Playback speed (`0.7` – `1.2`)                                                                                                | `1.0`                                                                                                    |
-| `elevenlabs.stability`                      | Voice stability (`0.0` – `1.0`)                                                                                               | `0.5`                                                                                                    |
-| `elevenlabs.similarityBoost`                | Voice similarity boost (`0.0` – `1.0`)                                                                                        | `0.75`                                                                                                   |
+| Setting                                     | Description                                                                                                                                                                                                                               | Default                                                                                                  |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `calls.enabled`                             | Master switch for the calling feature                                                                                                                                                                                                     | `true`                                                                                                   |
+| `calls.provider`                            | Voice provider (currently only `twilio`)                                                                                                                                                                                                  | `twilio`                                                                                                 |
+| `calls.maxDurationSeconds`                  | Maximum call length in seconds                                                                                                                                                                                                            | `3600` (1 hour)                                                                                          |
+| `calls.userConsultTimeoutSeconds`           | How long to wait for user answers                                                                                                                                                                                                         | `120` (2 min)                                                                                            |
+| `calls.disclosure.enabled`                  | Whether the AI announces itself at call start                                                                                                                                                                                             | `true`                                                                                                   |
+| `calls.disclosure.text`                     | The disclosure message spoken at call start                                                                                                                                                                                               | `"At the very beginning of the call, introduce yourself as an assistant calling on behalf of my human."` |
+| `calls.model`                               | Override LLM model for call orchestration                                                                                                                                                                                                 | _(uses default model)_                                                                                   |
+| `calls.callerIdentity.allowPerCallOverride` | Allow per-call caller identity selection                                                                                                                                                                                                  | `true`                                                                                                   |
+| `calls.callerIdentity.userNumber`           | E.164 phone number for user-number mode                                                                                                                                                                                                   | _(empty)_                                                                                                |
+| `calls.voice.language`                      | Language code for TTS and transcription                                                                                                                                                                                                   | `en-US`                                                                                                  |
+| `services.stt.provider`                     | STT provider for transcription and telephony. Determines the Twilio integration path at call setup time (Deepgram/Google use native ConversationRelay; OpenAI Whisper uses media-stream).                                                 | `deepgram`                                                                                               |
+| `services.tts.provider`                     | Active TTS provider for speech synthesis. Must be a provider ID from the catalog (`elevenlabs`, `fish-audio`, `deepgram`). New providers can be added via the catalog without code changes to call routing.                               | `elevenlabs`                                                                                             |
+| `services.tts.providers.<id>.*`             | Provider-specific settings block. Each catalog provider has its own settings namespace under `services.tts.providers.<id>`. See voice settings in the desktop/iOS app or run `assistant config list` for available settings per provider. | _(per-provider defaults)_                                                                                |
+
+## TTS provider call-path behavior
+
+Each TTS provider uses one of two call-path modes during phone calls:
+
+| Provider     | Call mode          | Description                                                                                                                                                           |
+| ------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `elevenlabs` | `native-twilio`    | Text tokens are forwarded to Twilio's ConversationRelay, which synthesizes audio via its built-in ElevenLabs integration.                                             |
+| `fish-audio` | `synthesized-play` | The assistant synthesizes audio server-side via Fish Audio's HTTP API and streams chunks to Twilio via play messages.                                                 |
+| `deepgram`   | `synthesized-play` | The assistant synthesizes audio server-side via Deepgram's HTTP API and streams chunks to Twilio via play messages. Uses the same API key as Deepgram speech-to-text. |
+
+Providers using `synthesized-play` add a small amount of latency compared to `native-twilio` because audio must be synthesized server-side before playback. The assistant handles chunk buffering and streaming automatically.
 
 ## Adjusting settings
 

package/src/config/bundled-skills/phone-calls/references/TROUBLESHOOTING.md

@@ -56,12 +56,12 @@ The system has a 30-second silence timeout. If nobody speaks for 30 seconds duri
 
 ## Call quality sounds off
 
-- Verify `elevenlabs.voiceId` is set to a valid ElevenLabs voice ID
+- Verify `services.tts.providers.elevenlabs.voiceId` is set to a valid ElevenLabs voice ID
 - Ask for the desired voice style again and try a different voice selection
 
 ## Twilio says "application error" right after answer
 
 - This often means ConversationRelay rejected voice configuration after TwiML fetch
-- Keep `elevenlabs.voiceModelId` empty first (bare `voiceId` mode)
+- Keep `services.tts.providers.elevenlabs.voiceModelId` empty first (bare `voiceId` mode)
 - If you set `voiceModelId`, try clearing it and retesting:
-  `assistant config set elevenlabs.voiceModelId ""`
+  `assistant config set services.tts.providers.elevenlabs.voiceModelId ""`

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "voice_config_update",
-      "description": "Update a voice configuration setting (TTS provider, TTS voice ID, Fish Audio reference ID, PTT activation key, conversation timeout). Changes take effect immediately.",
+      "description": "Update a voice configuration setting. Use tts_provider to switch the global TTS provider (valid providers: elevenlabs, fish-audio, deepgram — defined by the provider catalog). Use tts_voice_id to set the ElevenLabs voice ID, fish_audio_reference_id for Fish Audio voice reference. Deepgram uses the same API key as speech-to-text and requires no additional voice config. Changes persist to services.tts config and take effect immediately.",
       "category": "system",
       "risk": "low",
       "input_schema": {
@@ -18,10 +18,10 @@
               "tts_provider",
               "tts_voice_id"
             ],
-            "description": "The voice setting to change"
+            "description": "The voice setting to change. tts_provider selects the global TTS provider from the provider catalog (elevenlabs, fish-audio, deepgram). tts_voice_id sets the ElevenLabs voice. fish_audio_reference_id sets the Fish Audio voice reference. Deepgram uses its default model and shares the STT API key."
           },
           "value": {
-            "description": "The new value for the setting (type depends on setting)"
+            "description": "The new value for the setting. For tts_provider: a valid provider ID from the provider catalog (elevenlabs, fish-audio, deepgram). For tts_voice_id: an alphanumeric ElevenLabs voice ID. For fish_audio_reference_id: a Fish Audio voice reference ID. For conversation_timeout: seconds (5, 10, 15, 30, or 60). For activation_key: key identifier string."
           },
           "activity": {
             "type": "string",