@vellumai/assistant 0.6.2 → 0.6.4

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/slack/SKILL.md

@@ -50,6 +50,7 @@ Refer to https://api.slack.com/methods for available endpoints. The bot token sc
 ### Reacting & managing
 
 - `reactions.add` — add an emoji reaction
+- `conversations.join` — join a public channel
 - `conversations.leave` — leave a channel
 - `search.messages` — search across the workspace
 

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

@@ -63,6 +63,24 @@ Only the parent conversation that spawned a subagent can interact with it (check
 
 Set `send_result_to_user: false` when spawning a subagent whose result is for internal processing only. The parent will still be notified on completion, but the notification will instruct it to read the result without presenting it to the user.
 
+## Fork Mode
+
+Forks are sub-agents that inherit the parent's full context -- messages, system prompt, and memory -- sharing the KV cache for near-free context inheritance. Use forks when the task benefits from knowing what you've been discussing; use a regular sub-agent when the task is self-contained.
+
+**Key behaviors:** Forks always run as `general` role (the `role` parameter is ignored). `send_result_to_user` defaults to `false`. Read fork output with `last_n: 1` to get only the final synthesis.
+
+**When to fork vs regular sub-agent:**
+
+| Task | Mode |
+|---|---|
+| Single tool call (one search, one file read) | Direct -- don't spawn at all |
+| Multi-page web research needing conversation context | Fork |
+| Exploratory file search informed by prior discussion | Fork |
+| Comparing multiple sources against what was discussed | Parallel forks |
+| Self-contained task with a clear objective | Regular sub-agent |
+
+Rule of thumb: "Does this task need to know what we've been talking about?" If yes, fork. If the objective is fully self-describing, use a regular sub-agent with a scoped role.
+
 ## Tips
 
 - Do NOT poll `subagent_status` in a loop. You will be notified automatically when a subagent completes.
@@ -71,3 +89,6 @@ Set `send_result_to_user: false` when spawning a subagent whose result is for in
 - Use `notify_parent` for interim findings instead of waiting for completion. This lets the parent act on partial results early.
 - Use `subagent_message` to send follow-up instructions to a running subagent.
 - Use `subagent_abort` to cancel a subagent that is no longer needed.
+- Default to spawning subagents for any task that involves web research, multi-file exploration, or independent coding work. Serial execution should be the exception, not the rule.
+- When a user request has both an information-gathering component and an action component, spawn a researcher immediately rather than doing the research inline yourself.
+- Prefer spawning 2-3 focused subagents over one large general-purpose subagent. Smaller scopes finish faster and fail more gracefully.

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "subagent_spawn",
-      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.",
+      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Can use scoped roles (researcher, coder, planner).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. Always runs as general role. Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -19,16 +19,20 @@
           },
           "context": {
             "type": "string",
-            "description": "Optional additional context to pass to the subagent"
+            "description": "Optional additional context to pass to the subagent. Ignored when fork is true — forks inherit the parent's full context."
+          },
+          "fork": {
+            "type": "boolean",
+            "description": "When true, the subagent inherits the parent's full context (messages, system prompt, memory) instead of receiving only the objective + context fields. Fork mode always runs as 'general' role (the role parameter is ignored) and defaults send_result_to_user to false. Use for tasks that benefit from the full conversational context."
           },
           "send_result_to_user": {
             "type": "boolean",
-            "description": "Whether to present the subagent's result to the user when it completes. Defaults to true. Set to false for internal/silent processing."
+            "description": "Whether to present the subagent's result to the user when it completes. Defaults to true for regular sub-agents, false for forks. Set explicitly to override."
           },
           "role": {
             "type": "string",
             "enum": ["general", "researcher", "coder", "planner"],
-            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'general': full access (default)."
+            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'general': full access (default). Ignored when fork: true (forks always use general)."
           },
           "activity": {
             "type": "string",

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

@@ -6,6 +6,11 @@ metadata:
   emoji: "✅"
   vellum:
     display-name: "Tasks"
+    activation-hints:
+      - "User wants to add, check, or manage items on their to-do list or task queue"
+      - "For one-off action items, not recurring automations (use schedule for those)"
+    avoid-when:
+      - "User wants recurring/scheduled automation — use the schedule skill instead"
 ---
 
 Two-layer task system: **task templates** (reusable definitions with input placeholders) and **work items** (instances in the Task Queue with priority tiers and status tracking).

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"

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

@@ -0,0 +1,256 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { BatchTranscriber } from "../../../../stt/types.js";
+import type { ToolContext } from "../../../../tools/types.js";
+
+// ---------------------------------------------------------------------------
+// Mocks — must be declared before the subject import
+// ---------------------------------------------------------------------------
+
+mock.module("../../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+let mockTranscriber: BatchTranscriber | null = null;
+
+mock.module("../../../../providers/speech-to-text/resolve.js", () => ({
+  resolveBatchTranscriber: async () => mockTranscriber,
+}));
+
+// Track calls to spawnWithTimeout so we can simulate ffmpeg/ffprobe results.
+let spawnResults: Record<
+  string,
+  { exitCode: number; stdout: string; stderr: string }
+> = {};
+
+mock.module("../../../../util/spawn.js", () => ({
+  FFMPEG_TRANSCODE_TIMEOUT_MS: 60_000,
+  FFPROBE_TIMEOUT_MS: 10_000,
+  spawnWithTimeout: async (args: string[]) => {
+    const cmd = args[0];
+    if (cmd === "ffprobe" && spawnResults["ffprobe"]) {
+      return spawnResults["ffprobe"];
+    }
+    if (cmd === "ffmpeg" && spawnResults["ffmpeg"]) {
+      return spawnResults["ffmpeg"];
+    }
+    return { exitCode: 0, stdout: "", stderr: "" };
+  },
+}));
+
+// Mock file access and reading
+let accessiblePaths: Set<string> = new Set();
+let mockFileContents: Record<string, Buffer> = {};
+
+mock.module("node:fs/promises", () => ({
+  access: async (p: string) => {
+    if (!accessiblePaths.has(p)) throw new Error(`ENOENT: no such file: ${p}`);
+  },
+  readFile: async (p: string) => {
+    return mockFileContents[p] ?? Buffer.alloc(0);
+  },
+  unlink: async () => {},
+  mkdir: async () => {},
+  readdir: async (dir: string) => {
+    // Return chunk files if any were set up
+    const chunks = Object.keys(mockFileContents).filter(
+      (k) => k.startsWith(dir) && k.includes("chunk-"),
+    );
+    return chunks.map((k) => k.split("/").pop()!);
+  },
+}));
+
+mock.module("../../../../util/silently.js", () => ({
+  silentlyWithLog: async () => {},
+}));
+
+// ---------------------------------------------------------------------------
+// Subject import (after mocks)
+// ---------------------------------------------------------------------------
+
+import { run } from "./transcribe-media.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeContext(overrides?: Partial<ToolContext>): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "test-conv",
+    trustClass: "guardian",
+    ...overrides,
+  };
+}
+
+function makeMockTranscriber(
+  results: Array<{ text: string }>,
+): BatchTranscriber {
+  let callIndex = 0;
+  return {
+    providerId: "openai-whisper",
+    boundaryId: "daemon-batch",
+    transcribe: async () => {
+      const result = results[callIndex] ?? { text: "" };
+      callIndex++;
+      return result;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("transcribe_media tool", () => {
+  beforeEach(() => {
+    mockTranscriber = null;
+    spawnResults = {};
+    accessiblePaths = new Set();
+    mockFileContents = {};
+  });
+
+  describe("no provider configured", () => {
+    test("returns error when no STT provider is available", async () => {
+      mockTranscriber = null;
+
+      const result = await run({ file_path: "/tmp/test.mp3" }, makeContext());
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain(
+        "No speech-to-text provider is configured",
+      );
+    });
+  });
+
+  describe("input validation", () => {
+    test("returns error when file_path is missing", async () => {
+      mockTranscriber = makeMockTranscriber([{ text: "hello" }]);
+
+      const result = await run({}, makeContext());
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("Provide a file_path");
+    });
+
+    test("returns error when file does not exist", async () => {
+      mockTranscriber = makeMockTranscriber([{ text: "hello" }]);
+
+      const result = await run(
+        { file_path: "/tmp/nonexistent.mp3" },
+        makeContext(),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("File not found");
+    });
+
+    test("returns error for unsupported file type", async () => {
+      mockTranscriber = makeMockTranscriber([{ text: "hello" }]);
+      accessiblePaths.add("/tmp/test.xyz");
+
+      const result = await run({ file_path: "/tmp/test.xyz" }, makeContext());
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("Unsupported file type");
+    });
+  });
+
+  describe("successful transcription", () => {
+    test("transcribes audio file via configured STT provider", async () => {
+      mockTranscriber = makeMockTranscriber([
+        { text: "Hello world, this is a test." },
+      ]);
+      accessiblePaths.add("/tmp/test.mp3");
+
+      // Mock ffmpeg conversion success — toWav will produce a tmp wav file
+      spawnResults["ffmpeg"] = {
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+      };
+      // Mock ffprobe for duration check
+      spawnResults["ffprobe"] = {
+        exitCode: 0,
+        stdout: "60.0\n",
+        stderr: "",
+      };
+
+      const result = await run({ file_path: "/tmp/test.mp3" }, makeContext());
+
+      expect(result.isError).toBe(false);
+      expect(result.content).toBe("Hello world, this is a test.");
+    });
+
+    test("returns no-speech message when transcription is empty", async () => {
+      mockTranscriber = makeMockTranscriber([{ text: "" }]);
+      accessiblePaths.add("/tmp/silence.wav");
+
+      spawnResults["ffmpeg"] = { exitCode: 0, stdout: "", stderr: "" };
+      spawnResults["ffprobe"] = {
+        exitCode: 0,
+        stdout: "10.0\n",
+        stderr: "",
+      };
+
+      const result = await run(
+        { file_path: "/tmp/silence.wav" },
+        makeContext(),
+      );
+
+      expect(result.isError).toBe(false);
+      expect(result.content).toContain("No speech detected");
+    });
+  });
+
+  describe("error handling", () => {
+    test("returns error when ffmpeg conversion fails", async () => {
+      mockTranscriber = makeMockTranscriber([{ text: "hello" }]);
+      accessiblePaths.add("/tmp/test.mp3");
+
+      spawnResults["ffmpeg"] = {
+        exitCode: 1,
+        stdout: "",
+        stderr: "ffmpeg error: unsupported codec",
+      };
+
+      const result = await run({ file_path: "/tmp/test.mp3" }, makeContext());
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("Transcription failed");
+      expect(result.content).toContain("ffmpeg failed");
+    });
+  });
+
+  describe("legacy mode parameter rejection", () => {
+    test("rejects calls that pass the legacy mode parameter", async () => {
+      mockTranscriber = makeMockTranscriber([{ text: "transcribed text" }]);
+      accessiblePaths.add("/tmp/test.wav");
+
+      const result = await run(
+        { file_path: "/tmp/test.wav", mode: "local" },
+        makeContext(),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain(
+        "`mode` parameter is no longer supported",
+      );
+    });
+
+    test("rejects mode parameter regardless of value", async () => {
+      mockTranscriber = makeMockTranscriber([{ text: "transcribed text" }]);
+
+      const result = await run(
+        { file_path: "/tmp/test.wav", mode: "cloud" },
+        makeContext(),
+      );
+
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain("configured speech-to-text service");
+    });
+  });
+});