vellum 0.2.7 → 0.2.9

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: {
@@ -228,4 +227,8 @@ export const DEFAULT_CONFIG: AssistantConfig = {
       denyCategories: [],
     },
   },
+  ingress: {
+    publicBaseUrl: '',
+    mode: 'gateway_only' as const,
+  },
 };

package/src/config/schema.ts

@@ -9,6 +9,7 @@ const VALID_SANDBOX_BACKENDS = ['native', 'docker'] as const;
 const VALID_DOCKER_NETWORKS = ['none', 'bridge'] as const;
 const VALID_PERMISSIONS_MODES = ['legacy', 'strict'] as const;
 const VALID_CALL_PROVIDERS = ['twilio'] as const;
+const VALID_INGRESS_MODES = ['gateway_only', 'compat'] as const;
 
 export const TimeoutConfigSchema = z.object({
   shellMaxTimeoutSec: z
@@ -780,8 +781,19 @@ export const WorkspaceGitConfigSchema = z.object({
         .int().positive().default(2000),
       backoffMaxMs: z.number({ error: 'workspaceGit.commitMessageLLM.breaker.backoffMaxMs must be a number' })
         .int().positive().default(60000),
-    }).default({}),
-  }).default({}),
+    }).default({ openAfterFailures: 3, backoffBaseMs: 2000, backoffMaxMs: 60000 }),
+  }).default({
+    enabled: false,
+    useConfiguredProvider: true,
+    providerFastModelOverrides: {},
+    timeoutMs: 600,
+    maxTokens: 120,
+    temperature: 0.2,
+    maxFilesInPrompt: 30,
+    maxDiffBytes: 12000,
+    minRemainingTurnBudgetMs: 1000,
+    breaker: { openAfterFailures: 3, backoffBaseMs: 2000, backoffMaxMs: 60000 },
+  }),
 });
 
 export const AgentHeartbeatConfigSchema = z.object({
@@ -883,9 +895,6 @@ export const CallsConfigSchema = z.object({
       error: `calls.provider must be one of: ${VALID_CALL_PROVIDERS.join(', ')}`,
     })
     .default('twilio'),
-  webhookBaseUrl: z
-    .string({ error: 'calls.webhookBaseUrl must be a string' })
-    .default(''),
   maxDurationSeconds: z
     .number({ error: 'calls.maxDurationSeconds must be a number' })
     .int('calls.maxDurationSeconds must be an integer')
@@ -914,6 +923,17 @@ export const SkillsConfigSchema = z.object({
   allowBundled: z.array(z.string()).nullable().default(null),
 });
 
+export const IngressConfigSchema = z.object({
+  publicBaseUrl: z
+    .string({ error: 'ingress.publicBaseUrl must be a string' })
+    .default(''),
+  mode: z
+    .enum(VALID_INGRESS_MODES, {
+      error: `ingress.mode must be one of: ${VALID_INGRESS_MODES.join(', ')}`,
+    })
+    .default('gateway_only'),
+});
+
 export const AssistantConfigSchema = z.object({
   provider: z
     .enum(VALID_PROVIDERS, {
@@ -1152,7 +1172,6 @@ export const AssistantConfigSchema = z.object({
   calls: CallsConfigSchema.default({
     enabled: true,
     provider: 'twilio',
-    webhookBaseUrl: '',
     maxDurationSeconds: 3600,
     userConsultTimeoutSeconds: 120,
     disclosure: {
@@ -1163,6 +1182,10 @@ export const AssistantConfigSchema = z.object({
       denyCategories: [],
     },
   }),
+  ingress: IngressConfigSchema.default({
+    publicBaseUrl: '',
+    mode: 'gateway_only',
+  }),
 }).superRefine((config, ctx) => {
   if (config.contextWindow.targetInputTokens >= config.contextWindow.maxInputTokens) {
     ctx.addIssue({
@@ -1223,3 +1246,4 @@ export type WorkspaceGitConfig = z.infer<typeof WorkspaceGitConfigSchema>;
 export type CallsConfig = z.infer<typeof CallsConfigSchema>;
 export type CallsDisclosureConfig = z.infer<typeof CallsDisclosureConfigSchema>;
 export type CallsSafetyConfig = z.infer<typeof CallsSafetyConfigSchema>;
+export type IngressConfig = z.infer<typeof IngressConfigSchema>;

package/src/config/system-prompt.ts

@@ -218,7 +218,7 @@ function buildTaskScheduleReminderRoutingSection(): string {
     '',
     'You can create ad-hoc work items by providing just a `title` to `task_list_add` — no existing task template is needed. A lightweight template is auto-created behind the scenes. For reusable task definitions with templates and input schemas, use `task_save` first.',
     '',
-    '**IMPORTANT:** When you call `task_list_show`, the Tasks window opens automatically on the client. Do NOT also create a separate surface/UI (via `ui_show` or `app_create`) to display the task queue. Doing so causes duplicate Task Queue windows. Just call `task_list_show` and let the native window handle the presentation.',
+    '**IMPORTANT:** When you call `task_list_show`, the Tasks window opens automatically on the client AND the tool returns the current task list. Present a brief summary of the tasks in your chat response so the user can see them inline. Do NOT also create a separate surface/UI (via `ui_show` or `app_create`) to display the task queue — that causes duplicate windows.',
     '',
     '### Schedules (schedule_create / schedule_list / schedule_update / schedule_delete)',
     'For recurring automated jobs that run on a recurrence schedule (cron or RRULE). Use ONLY when the user explicitly wants:',

package/src/config/types.ts

@@ -34,4 +34,5 @@ export type {
   CallsConfig,
   CallsDisclosureConfig,
   CallsSafetyConfig,
+  IngressConfig,
 } from './schema.js';

package/src/config/vellum-skills/google-oauth-setup/SKILL.md

@@ -124,7 +124,7 @@ Tell the user: "Consent screen is configured! Almost there — just need to crea
 
 > **Create OAuth Credentials**
 >
-> I'm about to create OAuth Desktop credentials for Vellum Assistant. This generates a client ID that Vellum uses to initiate the authorization flow. No secret keys are involved — we use the secure PKCE method.
+> I'm about to create OAuth Web Application credentials for Vellum Assistant. This generates a client ID that Vellum uses to initiate the authorization flow. The redirect URI will point to the gateway's OAuth callback endpoint.
 
 Wait for the user to approve. If they decline, explain that credentials are the final step needed and offer to try again or cancel.
 
@@ -133,8 +133,9 @@ Once approved, navigate to `https://console.cloud.google.com/apis/credentials?pr
 Use `browser_click` on "+ Create Credentials" at the top, then select "OAuth client ID" from the dropdown.
 
 Take a `browser_snapshot` and fill in:
-1. **Application type:** Select "Desktop app" from the dropdown
-2. **Name:** "Vellum Assistant Desktop"
+1. **Application type:** Select "Web application" from the dropdown
+2. **Name:** "Vellum Assistant"
+3. **Authorized redirect URIs:** Click "Add URI" and enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable.
 
 Use `browser_click` on the "Create" button.
 
@@ -179,7 +180,7 @@ Summarize what was accomplished:
 - Created a Google Cloud project (or used an existing one)
 - Enabled the Gmail API and Google Calendar API
 - Configured the OAuth consent screen with appropriate scopes (including calendar)
-- Created OAuth Desktop credentials using secure PKCE
+- Created OAuth Web Application credentials with gateway callback redirect URI
 - Connected your Gmail and Google Calendar accounts
 
 ## Error Handling

package/src/config/vellum-skills/slack-oauth-setup/SKILL.md

@@ -85,14 +85,16 @@ Tell the user: "Permissions configured! Now let's set up the redirect URL and ge
 
 Navigate to the "OAuth & Permissions" page if not already there.
 
+The redirect URL must point to the gateway's OAuth callback endpoint. Determine the URL by reading the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable. The callback path is `/webhooks/oauth/callback`.
+
 In the "Redirect URLs" section:
 1. Click "Add New Redirect URL"
-2. Enter `http://127.0.0.1:0/callback` — Vellum will use a random port on localhost
+2. Enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`)
 3. Click "Add" then "Save URLs"
 
 Take a `browser_snapshot` to confirm.
 
-Tell the user: "Redirect URL configured."
+Tell the user: "Redirect URL configured. Make sure your tunnel is running and `ingress.publicBaseUrl` is set in Settings so the callback can reach the gateway."
 
 ## Step 5: Extract Client ID and Client Secret
 

package/src/config/vellum-skills/telegram-setup/SKILL.md

@@ -5,14 +5,14 @@ user-invocable: true
 metadata: {"vellum": {"emoji": "\ud83e\udd16"}}
 ---
 
-You are helping your user connect a Telegram bot to the Vellum Assistant gateway. When this skill is invoked, walk through each step below using only existing tools.
+You are helping your user connect a Telegram bot to the Vellum Assistant gateway. Telegram webhooks are received exclusively by the gateway (the public ingress boundary) — they never hit the assistant runtime directly. When this skill is invoked, walk through each step below using only existing tools.
 
 ## What You Need
 
 1. **Bot token** from Telegram's @BotFather (the user provides this)
-2. **Gateway webhook URL** where the gateway receives webhooks (e.g. `https://their-domain/webhooks/telegram`)
+2. **Gateway webhook URL** — derived from the canonical ingress setting: `${ingress.publicBaseUrl}/webhooks/telegram`. The gateway is the only publicly reachable endpoint; Telegram sends webhooks to the gateway, which validates and forwards them to the assistant runtime internally. If `ingress.publicBaseUrl` is configured (Settings UI > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var), use it to auto-derive the webhook URL. If it is not configured, ask the user to set it before proceeding.
 
-If the user has already provided the bot token in the conversation, use it directly. Otherwise, ask for it. Always confirm the gateway webhook URL if not provided.
+If the user has already provided the bot token in the conversation, use it directly. Otherwise, ask for it.
 
 ## Setup Steps
 

package/src/daemon/computer-use-session.ts

@@ -15,6 +15,7 @@ import { AgentLoop } from '../agent/loop.js';
 import { ToolExecutor } from '../tools/executor.js';
 import { PermissionPrompter } from '../permissions/prompter.js';
 import { SecretPrompter } from '../permissions/secret-prompter.js';
+import type { UserDecision } from '../permissions/types.js';
 import { allUiSurfaceTools } from '../tools/ui-surface/definitions.js';
 import { allComputerUseTools } from '../tools/computer-use/definitions.js';
 import { registerSkillTools } from '../tools/registry.js';
@@ -893,7 +894,7 @@ export class ComputerUseSession {
 
   handleConfirmationResponse(
     requestId: string,
-    decision: 'allow' | 'always_allow' | 'deny',
+    decision: UserDecision,
     selectedPattern?: string,
     selectedScope?: string,
   ): void {