@vellumai/assistant 0.6.3 → 0.6.5

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
 
@@ -177,7 +177,7 @@ Medium and high risk tools require a confidence score between 0 and 1:
 
 When a user asks to declutter, clean up, or organize their email:
 
-- **Gmail connected**: Load the **gmail** skill, which has the full decluttering workflow with `gmail_sender_digest`, `gmail_archive`, `gmail_unsubscribe`, and `gmail_filters`.
+- **Gmail connected**: Load the **gmail** skill, which has the full decluttering workflow with sender-digest scanning, batch archiving, unsubscribe support, and filter management.
 - **Non-Gmail email connected**: Use the generic tools (`messaging_sender_digest`, `messaging_archive_by_sender`) - they work with any provider that supports these operations. Skip unsubscribe and filter offers since they are Gmail-specific.
 - **Nothing connected**: Ask which email provider they use. If it's Gmail, go straight into the Gmail connection flow. For other providers, let the user know only Gmail is supported right now and offer to set up Gmail instead. Don't present a menu of options or explain what OAuth is.
 
@@ -195,4 +195,4 @@ When a user asks to declutter, clean up, or organize their email:
 
 ### Query-Based Archiving
 
-Unlike Gmail's `gmail_archive` (which supports `scan_id` + `sender_ids`), `messaging_archive_by_sender` is query-based. Build `from:<email>` queries from the sender digest results to target specific senders. Include the same date/category filters used in the original scan to keep the scope consistent.
+Unlike the Gmail skill's archive script (which supports `cache_key` + sender emails), `messaging_archive_by_sender` is query-based. Build `from:<email>` queries from the sender digest results to target specific senders. Include the same date/category filters used in the original scan to keep the scope consistent.

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

@@ -374,6 +374,10 @@
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
+          },
+          "user_approved": {
+            "type": "boolean",
+            "description": "Set to true ONLY when the user's most recent message contains explicit approval language for this specific action (e.g. 'archive these', 'yes do it', 'go ahead'). Do NOT set this when the user merely described what they want without confirming, or when acting on prior instructions without fresh confirmation in this turn."
           }
         },
         "required": ["query", "confidence"]

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

@@ -8,9 +8,16 @@ export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  if (!context.triggeredBySurfaceAction) {
+  const userApproved =
+    input.user_approved === true && context.trustClass === "guardian";
+  if (
+    !context.triggeredBySurfaceAction &&
+    !context.batchAuthorizedByTask &&
+    !context.approvedViaPrompt &&
+    !userApproved
+  ) {
     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/messaging/tools/messaging-read.ts

@@ -1,9 +1,23 @@
+import type { Message } from "../../../../messaging/provider-types.js";
+import { wrapUntrustedContent } from "../../../../security/untrusted-content.js";
 import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 import { err, getProviderConnection, ok, resolveProvider } from "./shared.js";
 
+function wrapMessageContent(msg: Message): Message {
+  const source =
+    msg.platform === "gmail" || msg.platform === "outlook" ? "email" : "slack";
+  return {
+    ...msg,
+    text: wrapUntrustedContent(msg.text, {
+      source,
+      sourceDetail: msg.sender.email ?? msg.sender.name,
+    }),
+  };
+}
+
 export async function run(
   input: Record<string, unknown>,
   _context: ToolContext,
@@ -32,7 +46,7 @@ export async function run(
     } else {
       messages = await provider.getHistory(conn, conversationId, { limit });
     }
-    return ok(JSON.stringify(messages, null, 2));
+    return ok(JSON.stringify(messages.map(wrapMessageContent), null, 2));
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));
   }

package/src/config/bundled-skills/messaging/tools/messaging-search.ts

@@ -1,9 +1,23 @@
+import type { Message } from "../../../../messaging/provider-types.js";
+import { wrapUntrustedContent } from "../../../../security/untrusted-content.js";
 import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 import { err, getProviderConnection, ok, resolveProvider } from "./shared.js";
 
+function wrapMessageContent(msg: Message): Message {
+  const source =
+    msg.platform === "gmail" || msg.platform === "outlook" ? "email" : "slack";
+  return {
+    ...msg,
+    text: wrapUntrustedContent(msg.text, {
+      source,
+      sourceDetail: msg.sender.email ?? msg.sender.name,
+    }),
+  };
+}
+
 export async function run(
   input: Record<string, unknown>,
   _context: ToolContext,
@@ -21,7 +35,13 @@ export async function run(
     const account = input.account as string | undefined;
     const conn = await getProviderConnection(provider, account);
     const result = await provider.search(conn, query, { count: maxResults });
-    return ok(JSON.stringify(result, null, 2));
+    return ok(
+      JSON.stringify(
+        { ...result, messages: result.messages.map(wrapMessageContent) },
+        null,
+        2,
+      ),
+    );
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));
   }

package/src/config/bundled-skills/messaging/tools/messaging-send.ts

@@ -8,11 +8,10 @@ import {
 import { syncMessageToDisk } from "../../../../memory/conversation-disk-view.js";
 import { getBindingByChannelChat } from "../../../../memory/external-conversation-store.js";
 import {
-  batchGetMessages,
   createDraft,
   createDraftRaw,
   getProfile,
-  listMessages,
+  getThread,
 } from "../../../../messaging/providers/gmail/client.js";
 import { buildMultipartMime } from "../../../../messaging/providers/gmail/mime-builder.js";
 import type {
@@ -72,19 +71,19 @@ export async function run(
       const gmailConn = conn;
       // Reply mode: thread_id provided - create a threaded draft with reply-all recipients
       if (threadId) {
-        // Fetch thread messages to extract recipients and threading headers
-        const list = await listMessages(gmailConn, `thread:${threadId}`, 10);
-        if (!list.messages?.length) {
+        // Fetch thread messages directly via Threads API
+        const thread = await getThread(gmailConn, threadId, "metadata", [
+          "From",
+          "To",
+          "Cc",
+          "Message-ID",
+          "Subject",
+        ]);
+        const messages = thread.messages ?? [];
+        if (!messages.length) {
           return err("No messages found in this thread.");
         }
 
-        const messages = await batchGetMessages(
-          gmailConn,
-          list.messages.map((m) => m.id),
-          "metadata",
-          ["From", "To", "Cc", "Message-ID", "Subject"],
-        );
-
         // Use the latest message for threading and recipient extraction
         const latest = messages[messages.length - 1];
         const latestHeaders = latest.payload?.headers ?? [];

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,34 @@
 
 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."` |
+| `llm.callSites.callAgent.model`             | Override LLM model for call orchestration                                                                                                                                                                                                 | _(unset — falls back to `llm.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 and xAI use media-stream).                                          | `deepgram`                                                                                               |
+| `services.tts.provider`                     | Active TTS provider for speech synthesis. Must be a provider ID from the catalog (`elevenlabs`, `fish-audio`, `deepgram`, `xai`). 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.    |
+| `xai`        | `synthesized-play` | The assistant synthesizes audio server-side via xAI's HTTP API and streams chunks to Twilio via play messages. No native Twilio fallback (`allowNativeFallback: false`). |
+
+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, xai — 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 (valid providers: elevenlabs, fish-audio, deepgram, xai). 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: one of elevenlabs, fish-audio, deepgram, xai. 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",

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

@@ -10,9 +10,12 @@ import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
+import { listCatalogProviderIds } from "../../../../tts/provider-catalog.js";
 
 /**
  * Valid voice config settings and their UserDefaults key mappings.
+ *
+ * All config paths are canonical (`services.tts.*`).
  */
 const VOICE_SETTINGS = {
   activation_key: {
@@ -23,8 +26,8 @@ const VOICE_SETTINGS = {
     userDefaultsKey: "voiceConversationTimeoutSeconds",
     type: "number" as const,
   },
-  tts_voice_id: { userDefaultsKey: "ttsVoiceId", type: "string" as const },
   tts_provider: { userDefaultsKey: "ttsProvider", type: "string" as const },
+  tts_voice_id: { userDefaultsKey: "ttsVoiceId", type: "string" as const },
   fish_audio_reference_id: {
     userDefaultsKey: "fishAudioReferenceId",
     type: "string" as const,
@@ -40,8 +43,8 @@ const VALID_TIMEOUTS: readonly number[] = VALID_CONVERSATION_TIMEOUTS;
 const FRIENDLY_NAMES: Record<VoiceSettingName, string> = {
   activation_key: "PTT activation key",
   conversation_timeout: "Conversation timeout",
-  tts_voice_id: "ElevenLabs voice",
   tts_provider: "TTS provider",
+  tts_voice_id: "ElevenLabs voice",
   fish_audio_reference_id: "Fish Audio voice",
 };
 
@@ -105,11 +108,11 @@ function validateSetting(
       return { ok: true, coerced: trimmed };
     }
     case "tts_provider": {
-      const valid = ["elevenlabs", "fish-audio"];
-      if (typeof value !== "string" || !valid.includes(value.trim())) {
+      const catalogIds = listCatalogProviderIds();
+      if (typeof value !== "string" || !catalogIds.includes(value.trim())) {
         return {
           ok: false,
-          error: `tts_provider must be one of: ${valid.join(", ")}`,
+          error: `tts_provider must be one of: ${catalogIds.join(", ")}`,
         };
       }
       return { ok: true, coerced: value.trim() };
@@ -170,40 +173,41 @@ export async function run(
     });
   }
 
-  // For tts_voice_id, also persist to the config file (elevenlabs.voiceId)
-  // so phone calls and other consumers pick it up.
-  if (setting === "tts_voice_id") {
-    const raw = loadRawConfig();
-    setNestedValue(raw, "elevenlabs.voiceId", validation.coerced);
+  // Persist to canonical config paths under services.tts.*
+  const raw = loadRawConfig();
+
+  if (setting === "tts_provider") {
+    setNestedValue(raw, "services.tts.provider", validation.coerced);
     saveRawConfig(raw);
     invalidateConfigCache();
   }
 
-  // For conversation_timeout, persist to the config file
-  // (elevenlabs.conversationTimeoutSeconds).
-  if (setting === "conversation_timeout") {
-    const raw = loadRawConfig();
+  if (setting === "tts_voice_id") {
     setNestedValue(
       raw,
-      "elevenlabs.conversationTimeoutSeconds",
+      "services.tts.providers.elevenlabs.voiceId",
       validation.coerced,
     );
     saveRawConfig(raw);
     invalidateConfigCache();
   }
 
-  // For tts_provider, persist to config file (calls.voice.ttsProvider).
-  if (setting === "tts_provider") {
-    const raw = loadRawConfig();
-    setNestedValue(raw, "calls.voice.ttsProvider", validation.coerced);
+  if (setting === "conversation_timeout") {
+    setNestedValue(
+      raw,
+      "services.tts.providers.elevenlabs.conversationTimeoutSeconds",
+      validation.coerced,
+    );
     saveRawConfig(raw);
     invalidateConfigCache();
   }
 
-  // For fish_audio_reference_id, persist to config file (fishAudio.referenceId).
   if (setting === "fish_audio_reference_id") {
-    const raw = loadRawConfig();
-    setNestedValue(raw, "fishAudio.referenceId", validation.coerced);
+    setNestedValue(
+      raw,
+      "services.tts.providers.fish-audio.referenceId",
+      validation.coerced,
+    );
     saveRawConfig(raw);
     invalidateConfigCache();
   }

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

@@ -1,6 +1,6 @@
 ---
 name: transcribe
-description: Transcribe audio and video files using Whisper
+description: Transcribe audio and video files using the configured speech-to-text provider
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "🎙️"
@@ -8,22 +8,17 @@ metadata:
     display-name: "Transcribe"
 ---
 
-Transcribe audio and video files using OpenAI's Whisper model - either via the cloud API or locally via whisper.cpp.
-
-## Choosing a Mode
-
-Before transcribing, **ask the user which mode they prefer** if they haven't specified:
-
-1. **`api`** - Uses the OpenAI Whisper API. Fast, accurate, no setup needed. Requires an OpenAI API key (check if one is already configured). Audio is sent to OpenAI's servers. Costs ~$0.006/min.
-2. **`local`** - Uses whisper.cpp installed via Homebrew. Free, private, runs entirely on-device. Requires a one-time `brew install whisper-cpp`. Slightly slower but no data leaves the machine.
-
-If the user says "cloud", "API", or "online" → use `api`.
-If the user says "local", "offline", "private", or "on-device" → use `local`.
+Transcribe audio and video files using the configured speech-to-text provider. Supports multiple STT providers including OpenAI Whisper, Deepgram, and Google Gemini — the active provider is selected in Settings under Speech-to-Text (`services.stt`).
 
 ## Usage Notes
 
 - The tool accepts a `file_path` (absolute path to a local audio or video file) to transcribe.
 - Supported formats: any video (mp4, mov, etc.) or audio (mp3, wav, m4a, etc.) file.
 - For video files, audio is automatically extracted via ffmpeg before transcription.
-- The API mode has a 25MB per-request limit - large files are automatically split into chunks.
-- Local mode requires whisper.cpp (`brew install whisper-cpp`). The model is downloaded automatically on first use.
+- Large files are automatically split into chunks for processing.
+- If no STT provider credentials are configured, the tool will return an error with setup instructions.
+- The STT provider (`services.stt`) is shared between transcription and telephony call paths.
+
+## Maintenance
+
+When adding or modifying an STT provider, follow the onboarding checklist at `assistant/docs/stt-provider-onboarding.md`. That document covers the daemon catalog, config schema, adapter wiring, client catalog parity, and required tests.

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "transcribe_media",
-      "description": "Transcribe an audio or video file using Whisper. Provide a file_path to the media file. Set mode to 'api' (OpenAI cloud) or 'local' (whisper.cpp on-device). Ask the user which mode they prefer before calling.",
+      "description": "Transcribe an audio or video file using the configured speech-to-text provider. Provide a file_path to the media file.",
       "category": "transcribe",
       "risk": "low",
       "input_schema": {
@@ -13,17 +13,12 @@
             "type": "string",
             "description": "Absolute path to a local audio or video file to transcribe"
           },
-          "mode": {
-            "type": "string",
-            "enum": ["api", "local"],
-            "description": "Transcription backend: 'api' for OpenAI Whisper API (cloud), 'local' for whisper.cpp (on-device)"
-          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["mode", "file_path"]
+        "required": ["file_path"]
       },
       "executor": "tools/transcribe-media.ts",
       "execution_target": "host"