vellum 0.2.8 → 0.2.9

package/src/__tests__/twitter-auth-handler.test.ts

@@ -8,10 +8,11 @@ const testDir = mkdtempSync(join(tmpdir(), 'handlers-twitter-auth-test-'));
 
 // Track loadRawConfig / saveRawConfig calls
 let rawConfigStore: Record<string, unknown> = {};
+let mockIngressPublicBaseUrl: string | undefined = 'https://test.example.com';
 
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({}),
-  loadConfig: () => ({}),
+  loadConfig: () => ({ ingress: { publicBaseUrl: mockIngressPublicBaseUrl } }),
   loadRawConfig: () => ({ ...rawConfigStore }),
   saveRawConfig: (cfg: Record<string, unknown>) => {
     rawConfigStore = { ...cfg };
@@ -20,6 +21,19 @@ mock.module('../config/loader.js', () => ({
   invalidateConfigCache: () => {},
 }));
 
+mock.module('../inbound/public-ingress-urls.js', () => ({
+  getPublicBaseUrl: (config: { ingress?: { publicBaseUrl?: string } }) => {
+    const url = config?.ingress?.publicBaseUrl;
+    if (url) return url;
+    throw new Error('No public base URL configured.');
+  },
+  getOAuthCallbackUrl: (config: { ingress?: { publicBaseUrl?: string } }) => {
+    const url = config?.ingress?.publicBaseUrl;
+    if (!url) throw new Error('No public base URL configured.');
+    return `${url}/webhooks/oauth/callback`;
+  },
+}));
+
 mock.module('../util/platform.js', () => ({
   getRootDir: () => testDir,
   getDataDir: () => testDir,
@@ -77,9 +91,15 @@ mock.module('../security/secure-keys.js', () => ({
 // Mock OAuth2 flow
 let oauthFlowResult: unknown = null;
 let oauthFlowError: Error | null = null;
+let lastOAuthFlowOptions: Record<string, unknown> | undefined;
 
 mock.module('../security/oauth2.js', () => ({
-  startOAuth2Flow: async (_config: unknown, callbacks: { openUrl: (url: string) => void }) => {
+  startOAuth2Flow: async (
+    _config: unknown,
+    callbacks: { openUrl: (url: string) => void },
+    options?: Record<string, unknown>,
+  ) => {
+    lastOAuthFlowOptions = options;
     // Trigger the openUrl callback so tests can verify the open_url message is sent
     callbacks.openUrl('https://twitter.com/i/oauth2/authorize?test=1');
     if (oauthFlowError) throw oauthFlowError;
@@ -163,6 +183,8 @@ describe('Twitter auth handler', () => {
     oauthFlowResult = null;
     oauthFlowError = null;
     lastUpsertPolicy = undefined;
+    lastOAuthFlowOptions = undefined;
+    mockIngressPublicBaseUrl = 'https://test.example.com';
     // Mock fetch for Twitter API
     globalThis.fetch = (async (_url: string | URL | Request) => {
       return mockFetchResponse;
@@ -267,6 +289,69 @@ describe('Twitter auth handler', () => {
       expect(meta!.accountInfo).toBe('@testuser');
     });
 
+    test('passes callbackTransport: gateway to startOAuth2Flow', async () => {
+      rawConfigStore = { twitterIntegrationMode: 'local_byo' };
+      secureKeyStore['credential:integration:twitter:oauth_client_id'] = 'test-client-id';
+
+      oauthFlowResult = {
+        tokens: {
+          accessToken: 'mock-access-token',
+          refreshToken: 'mock-refresh-token',
+          expiresIn: 7200,
+          scope: 'tweet.read users.read offline.access',
+          tokenType: 'bearer',
+        },
+        grantedScopes: ['tweet.read', 'users.read', 'offline.access'],
+        rawTokenResponse: {},
+      };
+
+      const msg: TwitterAuthStartRequest = { type: 'twitter_auth_start' };
+      const { ctx, sent } = createTestContext();
+      await handleMessage(msg, {} as net.Socket, ctx);
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Verify startOAuth2Flow was called with gateway transport
+      expect(lastOAuthFlowOptions).toBeDefined();
+      expect(lastOAuthFlowOptions!.callbackTransport).toBe('gateway');
+    });
+
+    test('fails fast with actionable error when no ingress URL is configured', async () => {
+      rawConfigStore = { twitterIntegrationMode: 'local_byo' };
+      secureKeyStore['credential:integration:twitter:oauth_client_id'] = 'test-client-id';
+      mockIngressPublicBaseUrl = undefined;
+
+      oauthFlowResult = {
+        tokens: { accessToken: 'should-not-reach', refreshToken: undefined },
+        grantedScopes: [],
+        rawTokenResponse: {},
+      };
+
+      const msg: TwitterAuthStartRequest = { type: 'twitter_auth_start' };
+      const { ctx, sent } = createTestContext();
+      await handleMessage(msg, {} as net.Socket, ctx);
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should NOT have sent open_url — the flow should fail before reaching OAuth
+      const openUrlMsg = sent.find((m) => m.type === 'open_url');
+      expect(openUrlMsg).toBeUndefined();
+
+      const result = sent.find((m) => m.type === 'twitter_auth_result') as {
+        type: string;
+        success: boolean;
+        error?: string;
+      };
+      expect(result).toBeDefined();
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('ingress.publicBaseUrl');
+      expect(result.error).toContain('INGRESS_PUBLIC_BASE_URL');
+      expect(result.error).toContain('/webhooks/oauth/callback');
+
+      // startOAuth2Flow should not have been called
+      expect(lastOAuthFlowOptions).toBeUndefined();
+    });
+
     describe('auth hardening', () => {
       test('OAuth cancel path returns sanitized failure', async () => {
         rawConfigStore = { twitterIntegrationMode: 'local_byo' };

package/src/calls/call-domain.ts

@@ -20,7 +20,8 @@ import { getCallOrchestrator, unregisterCallOrchestrator } from './call-state.js
 import { activeRelayConnections } from './relay-server.js';
 import { TwilioConversationRelayProvider } from './twilio-provider.js';
 import { getTwilioConfig } from './twilio-config.js';
-import { buildTwilioVoiceWebhookUrl, buildTwilioStatusCallbackUrl } from './twilio-webhook-urls.js';
+import { getTwilioVoiceWebhookUrl, getTwilioStatusCallbackUrl } from '../inbound/public-ingress-urls.js';
+import { loadConfig } from '../config/loader.js';
 import type { CallSession } from './types.js';
 
 const log = getLogger('call-domain');
@@ -89,13 +90,14 @@ export async function startCall(input: StartCallInput): Promise<StartCallResult
   let sessionId: string | null = null;
 
   try {
-    const config = getTwilioConfig();
+    const twilioConfig = getTwilioConfig();
+    const ingressConfig = loadConfig();
     const provider = new TwilioConversationRelayProvider();
 
     const session = createCallSession({
       conversationId,
       provider: 'twilio',
-      fromNumber: config.phoneNumber,
+      fromNumber: twilioConfig.phoneNumber,
       toNumber: phoneNumber,
       task: callContext ? `${task}\n\nContext: ${callContext}` : task,
     });
@@ -104,10 +106,10 @@ export async function startCall(input: StartCallInput): Promise<StartCallResult
     log.info({ callSessionId: session.id, to: phoneNumber, task }, 'Initiating outbound call');
 
     const { callSid } = await provider.initiateCall({
-      from: config.phoneNumber,
+      from: twilioConfig.phoneNumber,
       to: phoneNumber,
-      webhookUrl: buildTwilioVoiceWebhookUrl(config.webhookBaseUrl, session.id),
-      statusCallbackUrl: buildTwilioStatusCallbackUrl(config.webhookBaseUrl),
+      webhookUrl: getTwilioVoiceWebhookUrl(ingressConfig, session.id),
+      statusCallbackUrl: getTwilioStatusCallbackUrl(ingressConfig),
     });
 
     updateCallSession(session.id, { providerCallSid: callSid });

package/src/calls/twilio-config.ts

@@ -1,8 +1,7 @@
 import { getSecureKey } from '../security/secure-keys.js';
 import { getLogger } from '../util/logger.js';
 import { loadConfig } from '../config/loader.js';
-import { getWebhookBaseUrl } from './twilio-webhook-urls.js';
-import { getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
+import { getPublicBaseUrl, getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
 
 const log = getLogger('twilio-config');
 
@@ -19,7 +18,7 @@ export function getTwilioConfig(): TwilioConfig {
   const authToken = getSecureKey('credential:twilio:auth_token');
   const phoneNumber = process.env.TWILIO_PHONE_NUMBER || getSecureKey('credential:twilio:phone_number') || '';
   const config = loadConfig();
-  const webhookBaseUrl = getWebhookBaseUrl(config);
+  const webhookBaseUrl = getPublicBaseUrl(config);
 
   // In gateway_only mode, ignore TWILIO_WSS_BASE_URL and always use the
   // centralized relay URL derived from the public ingress base URL.

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

@@ -251,6 +251,31 @@
       },
       "executor": "tools/task-list-remove.ts",
       "execution_target": "host"
+    },
+    {
+      "name": "task_queue_run",
+      "description": "Run a task from the Task Queue in the background. Use this when the user says \"run this task\", \"execute this task\", \"start this task\", or wants to kick off a queued work item. The task runs asynchronously — the user can continue chatting while it executes. Required tool permissions are auto-approved since the user is explicitly requesting execution.",
+      "category": "tasks",
+      "risk": "medium",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "Direct work item ID (most precise selector)"
+          },
+          "task_name": {
+            "type": "string",
+            "description": "Task name/title to search for (case-insensitive substring match)"
+          },
+          "title": {
+            "type": "string",
+            "description": "Work item title to search for (case-insensitive substring match)"
+          }
+        }
+      },
+      "executor": "tools/task-queue-run.ts",
+      "execution_target": "host"
     }
   ]
 }

package/src/config/bundled-skills/tasks/tools/task-queue-run.ts

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { executeTaskQueueRun } from '../../../../tools/tasks/work-item-run.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeTaskQueueRun(input, context);
+}

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

@@ -0,0 +1,25 @@
+---
+name: "Transcribe"
+description: "Transcribe audio and video files using Whisper (cloud API or local)"
+metadata: {"vellum": {"emoji": "🎙️"}}
+---
+
+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`.
+
+## Usage Notes
+
+- The tool accepts either a `file_path` (absolute path to a local file) or an `attachment_id` (for uploaded attachments). Prefer `file_path` when the user references a file on disk.
+- 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.

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

@@ -0,0 +1,32 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "transcribe_media",
+      "description": "Transcribe an audio or video file using Whisper. Provide either a file_path to a local file or an attachment_id for an uploaded attachment. Set mode to 'api' (OpenAI cloud) or 'local' (whisper.cpp on-device). Ask the user which mode they prefer before calling.",
+      "category": "transcribe",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "file_path": {
+            "type": "string",
+            "description": "Absolute path to a local audio or video file to transcribe"
+          },
+          "attachment_id": {
+            "type": "string",
+            "description": "The ID of an attached 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)"
+          }
+        },
+        "required": ["mode"]
+      },
+      "executor": "tools/transcribe-media.ts",
+      "execution_target": "host"
+    }
+  ]
+}

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

@@ -0,0 +1,370 @@
+import { tmpdir } from 'node:os';
+import { join, extname } from 'node:path';
+import { writeFile, unlink, access, readFile, mkdir, readdir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { getAttachmentsByIds } from '../../../../memory/attachments-store.js';
+import { getConfig } from '../../../../config/loader.js';
+
+const VIDEO_EXTENSIONS = new Set(['.mp4', '.mov', '.avi', '.mkv', '.webm', '.m4v', '.mpeg', '.mpg']);
+const AUDIO_EXTENSIONS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg', '.flac', '.aiff', '.wma']);
+
+/** Timeout for ffmpeg operations. */
+const FFMPEG_TIMEOUT_MS = 120_000;
+
+/** Max file size for a single OpenAI Whisper API request (25MB). */
+const WHISPER_API_MAX_BYTES = 25 * 1024 * 1024;
+
+/** Duration per chunk when splitting for the API (10 minutes — stays well under 25MB as WAV). */
+const API_CHUNK_DURATION_SECS = 600;
+
+/** Timeout for a single Whisper API request. */
+const API_REQUEST_TIMEOUT_MS = 300_000;
+
+/** Timeout for a single whisper.cpp chunk transcription. */
+const LOCAL_CHUNK_TIMEOUT_MS = 600_000;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function spawnWithTimeout(
+  cmd: string[],
+  timeoutMs: number,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const proc = Bun.spawn(cmd, { stdout: 'pipe', stderr: 'pipe' });
+    const timer = setTimeout(() => {
+      proc.kill();
+      reject(new Error(`Process timed out after ${timeoutMs}ms: ${cmd[0]}`));
+    }, timeoutMs);
+    proc.exited.then(async (exitCode) => {
+      clearTimeout(timer);
+      const stdout = await new Response(proc.stdout).text();
+      const stderr = await new Response(proc.stderr).text();
+      resolve({ exitCode, stdout, stderr });
+    });
+  });
+}
+
+async function getAudioDuration(audioPath: string): Promise<number> {
+  const result = await spawnWithTimeout([
+    'ffprobe', '-v', 'error',
+    '-show_entries', 'format=duration',
+    '-of', 'csv=p=0',
+    audioPath,
+  ], 10_000);
+  if (result.exitCode !== 0) return 0;
+  return parseFloat(result.stdout.trim()) || 0;
+}
+
+async function splitAudio(
+  audioPath: string,
+  chunkDir: string,
+  chunkDurationSecs: number,
+): Promise<string[]> {
+  const chunkPattern = join(chunkDir, 'chunk-%03d.wav');
+  const result = await spawnWithTimeout([
+    'ffmpeg', '-y',
+    '-i', audioPath,
+    '-f', 'segment',
+    '-segment_time', String(chunkDurationSecs),
+    '-acodec', 'pcm_s16le',
+    '-ar', '16000',
+    '-ac', '1',
+    chunkPattern,
+  ], FFMPEG_TIMEOUT_MS);
+  if (result.exitCode !== 0) {
+    throw new Error(`Failed to split audio: ${result.stderr.slice(0, 300)}`);
+  }
+  const files = await readdir(chunkDir);
+  return files
+    .filter(f => f.startsWith('chunk-') && f.endsWith('.wav'))
+    .sort()
+    .map(f => join(chunkDir, f));
+}
+
+// ---------------------------------------------------------------------------
+// Source resolution
+// ---------------------------------------------------------------------------
+
+async function resolveSource(
+  input: Record<string, unknown>,
+): Promise<{ inputPath: string; isVideo: boolean; tempFile: string | null } | ToolExecutionResult> {
+  const filePath = input.file_path as string | undefined;
+  const attachmentId = input.attachment_id as string | undefined;
+
+  if (filePath) {
+    try { await access(filePath); } catch {
+      return { content: `File not found: ${filePath}`, isError: true };
+    }
+    const ext = extname(filePath).toLowerCase();
+    const isVideo = VIDEO_EXTENSIONS.has(ext);
+    const isAudio = AUDIO_EXTENSIONS.has(ext);
+    if (!isVideo && !isAudio) {
+      return { content: `Unsupported file type: ${ext}. Only video and audio files can be transcribed.`, isError: true };
+    }
+    return { inputPath: filePath, isVideo, tempFile: null };
+  }
+
+  if (attachmentId) {
+    const attachments = getAttachmentsByIds([attachmentId]);
+    if (attachments.length === 0) {
+      return { content: `Attachment not found: ${attachmentId}`, isError: true };
+    }
+    const attachment = attachments[0];
+    const mime = attachment.mimeType;
+    if (!mime.startsWith('video/') && !mime.startsWith('audio/')) {
+      return { content: `Unsupported file type: ${mime}. Only video and audio files can be transcribed.`, isError: true };
+    }
+    const ext = mime.startsWith('video/') ? '.mp4' : '.m4a';
+    const tempPath = join(tmpdir(), `vellum-transcribe-in-${randomUUID()}${ext}`);
+    await writeFile(tempPath, Buffer.from(attachment.dataBase64, 'base64'));
+    return { inputPath: tempPath, isVideo: mime.startsWith('video/'), tempFile: tempPath };
+  }
+
+  return { content: 'Provide either file_path or attachment_id.', isError: true };
+}
+
+/** Convert source to 16kHz mono WAV for consistent processing. */
+async function toWav(inputPath: string, isVideo: boolean): Promise<string> {
+  const wavPath = join(tmpdir(), `vellum-transcribe-${randomUUID()}.wav`);
+  const args = ['ffmpeg', '-y', '-i', inputPath];
+  if (isVideo) args.push('-vn');
+  args.push('-acodec', 'pcm_s16le', '-ar', '16000', '-ac', '1', wavPath);
+  const result = await spawnWithTimeout(args, FFMPEG_TIMEOUT_MS);
+  if (result.exitCode !== 0) {
+    throw new Error(`ffmpeg failed: ${result.stderr.slice(0, 500)}`);
+  }
+  return wavPath;
+}
+
+// ---------------------------------------------------------------------------
+// API mode — OpenAI Whisper API
+// ---------------------------------------------------------------------------
+
+async function transcribeViaApi(
+  audioPath: string,
+  apiKey: string,
+  context: ToolContext,
+): Promise<string> {
+  const duration = await getAudioDuration(audioPath);
+  const fileSize = Bun.file(audioPath).size;
+
+  // If small enough, send directly
+  if (fileSize <= WHISPER_API_MAX_BYTES) {
+    return await whisperApiRequest(audioPath, apiKey);
+  }
+
+  // Split into chunks for large files
+  const chunkDir = join(tmpdir(), `vellum-transcribe-api-chunks-${randomUUID()}`);
+  await mkdir(chunkDir, { recursive: true });
+
+  try {
+    context.onOutput?.(`Large file (${Math.round(duration / 60)}min) — splitting into chunks...\n`);
+    const chunks = await splitAudio(audioPath, chunkDir, API_CHUNK_DURATION_SECS);
+    const parts: string[] = [];
+
+    for (let i = 0; i < chunks.length; i++) {
+      if (context.signal?.aborted) throw new Error('Cancelled');
+      context.onOutput?.(`  Transcribing chunk ${i + 1}/${chunks.length}...\n`);
+      const text = await whisperApiRequest(chunks[i], apiKey);
+      if (text) parts.push(text);
+    }
+
+    return parts.join(' ');
+  } finally {
+    const { rm } = await import('node:fs/promises');
+    await rm(chunkDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+async function whisperApiRequest(audioPath: string, apiKey: string): Promise<string> {
+  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) {
+    const body = await response.text().catch(() => '');
+    throw new Error(`Whisper API error (${response.status}): ${body.slice(0, 300)}`);
+  }
+
+  const result = await response.json() as { text?: string };
+  return result.text?.trim() ?? '';
+}
+
+// ---------------------------------------------------------------------------
+// Local mode — whisper.cpp
+// ---------------------------------------------------------------------------
+
+async function transcribeViaLocal(
+  audioPath: string,
+  context: ToolContext,
+): Promise<string> {
+  // Check if whisper-cpp is installed
+  const whichResult = await spawnWithTimeout(['which', 'whisper-cpp'], 5_000);
+  if (whichResult.exitCode !== 0) {
+    throw new Error(
+      'whisper-cpp is not installed. Install it with: brew install whisper-cpp'
+    );
+  }
+
+  // Resolve model path — use the base model, download if needed
+  const modelPath = await resolveWhisperModel(context);
+
+  const duration = await getAudioDuration(audioPath);
+
+  if (duration > 0 && duration <= 1800) {
+    // Under 30 minutes — transcribe directly (whisper.cpp handles long files well)
+    context.onOutput?.(`Transcribing ${Math.round(duration / 60)}min of audio locally...\n`);
+    return await whisperCppRun(audioPath, modelPath);
+  }
+
+  // Very long files — split into 10-minute chunks to show progress
+  const chunkDir = join(tmpdir(), `vellum-transcribe-local-chunks-${randomUUID()}`);
+  await mkdir(chunkDir, { recursive: true });
+
+  try {
+    context.onOutput?.(`Large file (${Math.round(duration / 60)}min) — splitting into chunks...\n`);
+    const chunks = await splitAudio(audioPath, chunkDir, 600);
+    const parts: string[] = [];
+
+    for (let i = 0; i < chunks.length; i++) {
+      if (context.signal?.aborted) throw new Error('Cancelled');
+      context.onOutput?.(`  Transcribing chunk ${i + 1}/${chunks.length}...\n`);
+      const text = await whisperCppRun(chunks[i], modelPath);
+      if (text) parts.push(text);
+    }
+
+    return parts.join(' ');
+  } finally {
+    const { rm } = await import('node:fs/promises');
+    await rm(chunkDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+async function resolveWhisperModel(context: ToolContext): Promise<string> {
+  // Check common locations for the base model
+  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 */ }
+  }
+
+  // Download the base.en model (~140MB)
+  const modelDir = join(homeDir, '.vellum', 'models');
+  await mkdir(modelDir, { recursive: true });
+  const modelPath = join(modelDir, 'ggml-base.en.bin');
+  const modelUrl = 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin';
+
+  context.onOutput?.('Downloading Whisper base.en model (~140MB)...\n');
+
+  const response = await fetch(modelUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to download model: ${response.status}`);
+  }
+
+  const data = Buffer.from(await response.arrayBuffer());
+  await writeFile(modelPath, data);
+  context.onOutput?.('Model downloaded.\n');
+
+  return modelPath;
+}
+
+async function whisperCppRun(audioPath: string, modelPath: string): Promise<string> {
+  const result = await spawnWithTimeout([
+    'whisper-cpp',
+    '-m', modelPath,
+    '-f', audioPath,
+    '--no-timestamps',
+  ], LOCAL_CHUNK_TIMEOUT_MS);
+
+  if (result.exitCode !== 0) {
+    throw new Error(`whisper-cpp failed: ${result.stderr.slice(0, 300)}`);
+  }
+
+  // whisper-cpp outputs transcription to stderr with some logging, and
+  // the actual text lines to stdout. Clean up whitespace.
+  return result.stdout
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l.length > 0)
+    .join(' ')
+    .trim();
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const mode = input.mode as 'api' | 'local';
+  if (!mode || (mode !== 'api' && mode !== 'local')) {
+    return {
+      content: "Please specify mode: 'api' (OpenAI cloud) or 'local' (whisper.cpp on-device). Ask the user which they prefer.",
+      isError: true,
+    };
+  }
+
+  // Validate API key for api mode
+  if (mode === 'api') {
+    const config = getConfig();
+    const apiKey = config.apiKeys.openai;
+    if (!apiKey) {
+      return {
+        content: 'No OpenAI API key configured. Set your OpenAI API key to use cloud transcription, or use mode "local" for on-device transcription with whisper.cpp.',
+        isError: true,
+      };
+    }
+  }
+
+  const source = await resolveSource(input);
+  if ('isError' in source) return source;
+
+  const { inputPath, isVideo, tempFile } = source;
+  let wavPath: string | null = null;
+
+  try {
+    // Convert to WAV
+    wavPath = await toWav(inputPath, isVideo);
+
+    let text: string;
+    if (mode === 'api') {
+      const config = getConfig();
+      text = await transcribeViaApi(wavPath, config.apiKeys.openai!, context);
+    } else {
+      text = await transcribeViaLocal(wavPath, context);
+    }
+
+    if (!text.trim()) {
+      return { content: 'No speech detected in the audio.', isError: false };
+    }
+
+    return { content: text, isError: false };
+  } catch (err) {
+    return {
+      content: `Transcription failed: ${(err as Error).message}`,
+      isError: true,
+    };
+  } finally {
+    if (tempFile) { try { await unlink(tempFile); } catch { /* ignore */ } }
+    if (wavPath) { try { await unlink(wavPath); } catch { /* ignore */ } }
+  }
+}

package/src/config/defaults.ts

@@ -217,7 +217,6 @@ export const DEFAULT_CONFIG: AssistantConfig = {
   calls: {
     enabled: true,
     provider: 'twilio' as const,
-    webhookBaseUrl: '',
     maxDurationSeconds: 3600,
     userConsultTimeoutSeconds: 120,
     disclosure: {
@@ -230,6 +229,6 @@ export const DEFAULT_CONFIG: AssistantConfig = {
   },
   ingress: {
     publicBaseUrl: '',
-    mode: 'compat' as const,
+    mode: 'gateway_only' as const,
   },
 };