vellum 0.2.7 → 0.2.9

package/src/__tests__/runtime-events-sse.test.ts

@@ -0,0 +1,162 @@
+/**
+ * HTTP-layer integration tests for GET /v1/events (SSE assistant-events endpoint).
+ *
+ * Tests:
+ *   - 401 unauthorized (missing bearer token)
+ *   - 400 when conversationKey is absent
+ *   - Happy path: stream receives a published AssistantEvent
+ */
+import { describe, test, expect, beforeEach, afterAll, mock } from 'bun:test';
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testDir = realpathSync(mkdtempSync(join(tmpdir(), 'runtime-events-sse-test-')));
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => testDir,
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => ({
+    model: 'test',
+    provider: 'test',
+    apiKeys: {},
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    secretDetection: { enabled: false },
+  }),
+}));
+
+import { initializeDb, getDb, resetDb } from '../memory/db.js';
+import { RuntimeHttpServer } from '../runtime/http-server.js';
+import { assistantEventHub } from '../runtime/assistant-event-hub.js';
+import { buildAssistantEvent } from '../runtime/assistant-event.js';
+import { getOrCreateConversation } from '../memory/conversation-key-store.js';
+
+initializeDb();
+
+const TEST_TOKEN = 'test-bearer-token-events-sse';
+const AUTH_HEADERS = { Authorization: `Bearer ${TEST_TOKEN}` };
+
+describe('SSE assistant-events endpoint', () => {
+  let server: RuntimeHttpServer;
+  let port: number;
+
+  beforeEach(() => {
+    const db = getDb();
+    db.run('DELETE FROM conversation_keys');
+    db.run('DELETE FROM conversations');
+  });
+
+  afterAll(() => {
+    resetDb();
+    try { rmSync(testDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  });
+
+  async function startServer(): Promise<void> {
+    port = 19500 + Math.floor(Math.random() * 500);
+    server = new RuntimeHttpServer({ port, bearerToken: TEST_TOKEN });
+    await server.start();
+  }
+
+  async function stopServer(): Promise<void> {
+    await server?.stop();
+  }
+
+  function eventsUrl(params = ''): string {
+    return `http://127.0.0.1:${port}/v1/events${params ? `?${params}` : ''}`;
+  }
+
+  // ── Auth ──────────────────────────────────────────────────────────────────
+
+  test('401 when bearer token is missing', async () => {
+    await startServer();
+
+    const res = await fetch(eventsUrl('conversationKey=test-noauth'));
+    expect(res.status).toBe(401);
+    // Consume body to prevent resource leak
+    await res.body?.cancel();
+
+    await stopServer();
+  });
+
+  test('401 when bearer token is wrong', async () => {
+    await startServer();
+
+    const res = await fetch(eventsUrl('conversationKey=test-badauth'), {
+      headers: { Authorization: 'Bearer wrong-token' },
+    });
+    expect(res.status).toBe(401);
+    await res.body?.cancel();
+
+    await stopServer();
+  });
+
+  // ── Validation ────────────────────────────────────────────────────────────
+
+  test('400 when conversationKey is missing', async () => {
+    await startServer();
+
+    const res = await fetch(eventsUrl(), { headers: AUTH_HEADERS });
+    expect(res.status).toBe(400);
+    const body = await res.json() as { error: string };
+    expect(body.error).toContain('conversationKey');
+
+    await stopServer();
+  });
+
+  // ── Happy path ────────────────────────────────────────────────────────────
+
+  test('stream receives a published assistant event', async () => {
+    // Test the handler directly (bypassing HTTP) to avoid chunked-transfer
+    // buffering in Bun's loopback SSE implementation. The HTTP auth and
+    // routing are already covered by other test files; here we focus on the
+    // SSE subscription logic and frame delivery.
+    const { conversationId } = getOrCreateConversation('sse-happy-path');
+
+    const ac = new AbortController();
+    const req = new Request(
+      'http://localhost/v1/events?conversationKey=sse-happy-path',
+      { signal: ac.signal },
+    );
+
+    const { handleSubscribeAssistantEvents } = await import('../runtime/routes/events-routes.js');
+    const response = handleSubscribeAssistantEvents(req, new URL(req.url));
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toContain('text/event-stream');
+
+    // start() is called synchronously during ReadableStream construction, so the
+    // hub subscription is already registered before we publish.
+    const event = buildAssistantEvent('self', { type: 'pong' }, conversationId);
+    await assistantEventHub.publish(event);
+
+    // Read the first frame directly from the response body stream.
+    const reader = response.body!.getReader();
+    const { value, done } = await reader.read();
+    ac.abort();
+
+    expect(done).toBe(false);
+    const frame = new TextDecoder().decode(value);
+    expect(frame).toContain('event: assistant_event');
+    expect(frame).toContain(`"assistantId":"self"`);
+    expect(frame).toContain(`"sessionId":"${conversationId}"`);
+    expect(frame).toContain('"type":"pong"');
+  });
+});

package/src/__tests__/tool-executor.test.ts

@@ -1965,3 +1965,91 @@ describe('buildSanitizedEnv — baseline: credential exclusion', () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Persistent-allow lifecycle: roundtrip and auto-allow on subsequent invocation
+// ---------------------------------------------------------------------------
+
+describe('ToolExecutor persistent-allow lifecycle', () => {
+  beforeEach(() => {
+    fakeToolResult = { content: 'ok', isError: false };
+    lastCheckArgs = undefined;
+    getToolOverride = undefined;
+    checkResultOverride = undefined;
+    checkFnOverride = undefined;
+    if (addRuleSpy) { addRuleSpy.mockRestore(); addRuleSpy = undefined; }
+  });
+
+  function setupAddRuleSpy() {
+    addRuleSpy = spyOn(trustStore, 'addRule').mockImplementation(
+      (tool: string, pattern: string, scope: string, decision = 'allow', priority = 100, options?: any) => {
+        return { id: 'spy-rule-id', tool, pattern, scope, decision, priority, createdAt: Date.now(), ...options } as any;
+      },
+    );
+    return addRuleSpy;
+  }
+
+  test('persistent-allow roundtrip: always_allow saves rule and allows tool', async () => {
+    // Simulate check() returning 'prompt' so the executor asks the user
+    checkResultOverride = { decision: 'prompt', reason: 'Medium risk: requires approval' };
+    const spy = setupAddRuleSpy();
+
+    // User responds with always_allow, selecting a pattern and scope
+    const prompter = makePrompterWithDecision('always_allow', 'git *', '/tmp/project');
+    const executor = new ToolExecutor(prompter);
+    const result = await executor.execute('bash', { command: 'git status' }, makeContext());
+
+    // The tool should have been allowed to proceed
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe('ok');
+
+    // addRule should have been called with the correct arguments
+    expect(spy).toHaveBeenCalledTimes(1);
+    const [tool, pattern, scope, decision] = spy.mock.calls[0];
+    expect(tool).toBe('bash');
+    expect(pattern).toBe('git *');
+    expect(scope).toBe('/tmp/project');
+    expect(decision).toBe('allow');
+  });
+
+  test('auto-allow on subsequent invocation: matching rule skips prompt', async () => {
+    // Simulate a previously saved rule by making check() return 'allow'
+    // with a matched rule (as findHighestPriorityRule would).
+    checkResultOverride = { decision: 'allow', reason: 'Matched trust rule: git *' };
+
+    let promptCalled = false;
+    const trackingPrompter = {
+      prompt: async () => { promptCalled = true; return { decision: 'allow' as const }; },
+      resolveConfirmation: () => {},
+      updateSender: () => {},
+      dispose: () => {},
+    } as unknown as PermissionPrompter;
+
+    const executor = new ToolExecutor(trackingPrompter);
+    const result = await executor.execute('bash', { command: 'git status' }, makeContext());
+
+    // The tool should be auto-allowed
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe('ok');
+
+    // The prompter should NOT have been called — the rule auto-allowed
+    expect(promptCalled).toBe(false);
+  });
+
+  test('always_allow with everywhere scope saves rule and allows tool', async () => {
+    checkResultOverride = { decision: 'prompt', reason: 'Medium risk: requires approval' };
+    const spy = setupAddRuleSpy();
+
+    const prompter = makePrompterWithDecision('always_allow', 'file_write:*', 'everywhere');
+    const executor = new ToolExecutor(prompter);
+    const result = await executor.execute('file_write', { path: '/tmp/test.txt', content: 'hello' }, makeContext());
+
+    expect(result.isError).toBe(false);
+    expect(spy).toHaveBeenCalledTimes(1);
+    const [tool, pattern, scope, decision] = spy.mock.calls[0];
+    expect(tool).toBe('file_write');
+    expect(pattern).toBe('file_write:*');
+    expect(scope).toBe('everywhere');
+    expect(decision).toBe('allow');
+  });
+});

package/src/__tests__/turn-commit.test.ts

@@ -487,4 +487,68 @@ describe('LLM commit message integration', () => {
 
     expect(fullMessage).toContain('Turn:');
   });
+
+  test('changed files from preStatus are passed to generator', async () => {
+    let capturedContext: { changedFiles: string[] } | undefined;
+    let capturedOptions: { changedFiles: string[] } | undefined;
+
+    const llmResult: GenerateCommitMessageResult = {
+      message: 'feat: captured context test',
+      source: 'llm',
+    };
+
+    mock.module('../workspace/provider-commit-message-generator.js', () => ({
+      getCommitMessageGenerator: () => ({
+        generateCommitMessage: async (ctx: { changedFiles: string[] }, opts: { changedFiles: string[] }) => {
+          capturedContext = ctx;
+          capturedOptions = opts;
+          return llmResult;
+        },
+      }),
+    }));
+
+    const { commitTurnChanges: commit } = await import('../workspace/turn-commit.js');
+
+    const service = new WorkspaceGitService(testDir);
+    await service.ensureInitialized();
+
+    writeFileSync(join(testDir, 'alpha.ts'), 'export const a = 1;');
+    writeFileSync(join(testDir, 'beta.ts'), 'export const b = 2;');
+
+    await commit(testDir, 'sess_files', 1);
+
+    // The generator should have received the actual file list, not empty arrays
+    expect(capturedContext).toBeDefined();
+    expect(capturedContext!.changedFiles.length).toBeGreaterThan(0);
+    expect(capturedContext!.changedFiles).toContain('alpha.ts');
+    expect(capturedContext!.changedFiles).toContain('beta.ts');
+
+    expect(capturedOptions).toBeDefined();
+    expect(capturedOptions!.changedFiles.length).toBeGreaterThan(0);
+    expect(capturedOptions!.changedFiles).toContain('alpha.ts');
+    expect(capturedOptions!.changedFiles).toContain('beta.ts');
+  });
+
+  test('clean workspace skips LLM generator call', async () => {
+    let generatorCalled = false;
+
+    mock.module('../workspace/provider-commit-message-generator.js', () => ({
+      getCommitMessageGenerator: () => ({
+        generateCommitMessage: async () => {
+          generatorCalled = true;
+          return { message: 'should not be called', source: 'llm' as const };
+        },
+      }),
+    }));
+
+    const { commitTurnChanges: commit } = await import('../workspace/turn-commit.js');
+
+    const service = new WorkspaceGitService(testDir);
+    await service.ensureInitialized();
+
+    // No file changes — workspace is clean
+    await commit(testDir, 'sess_clean', 1);
+
+    expect(generatorCalled).toBe(false);
+  });
 });

package/src/__tests__/twilio-provider.test.ts

@@ -33,7 +33,7 @@ let mockAuthToken: string | undefined = 'test-auth-token-secret';
 
 mock.module('../security/secure-keys.js', () => ({
   getSecureKey: (account: string) => {
-    if (account === 'twilio_auth_token') return mockAuthToken;
+    if (account === 'credential:twilio:auth_token') return mockAuthToken;
     return undefined;
   },
 }));

package/src/__tests__/twilio-routes.test.ts

@@ -52,7 +52,7 @@ let mockAuthToken: string | undefined = 'test-auth-token-for-webhooks';
 
 mock.module('../security/secure-keys.js', () => ({
   getSecureKey: (account: string) => {
-    if (account === 'twilio_auth_token') return mockAuthToken;
+    if (account === 'credential:twilio:auth_token') return mockAuthToken;
     return undefined;
   },
 }));
@@ -72,7 +72,7 @@ mock.module('../calls/twilio-provider.js', () => {
       readonly name = 'twilio';
 
       static getAuthToken(): string | null {
-        return getSecureKey('twilio_auth_token') ?? null;
+        return getSecureKey('credential:twilio:auth_token') ?? null;
       }
 
       static verifyWebhookSignature(
@@ -205,9 +205,9 @@ describe('twilio webhook routes', () => {
   });
 
   async function startServer(): Promise<void> {
-    port = 20000 + Math.floor(Math.random() * 1000);
-    server = new RuntimeHttpServer({ port, bearerToken: TEST_TOKEN });
+    server = new RuntimeHttpServer({ port: 0, bearerToken: TEST_TOKEN });
     await server.start();
+    port = server.actualPort;
   }
 
   async function stopServer(): Promise<void> {

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,7 +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 { getPublicBaseUrl, getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
 
 const log = getLogger('twilio-config');
 
@@ -18,8 +18,23 @@ 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 wssBaseUrl = process.env.TWILIO_WSS_BASE_URL || '';
+  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.
+  let wssBaseUrl: string;
+  if (config.ingress.mode === 'gateway_only') {
+    if (process.env.TWILIO_WSS_BASE_URL) {
+      log.warn('TWILIO_WSS_BASE_URL env var is ignored in gateway-only mode. Relay URL is derived from ingress.publicBaseUrl.');
+    }
+    try {
+      wssBaseUrl = getTwilioRelayUrl(config);
+    } catch {
+      wssBaseUrl = '';
+    }
+  } else {
+    wssBaseUrl = process.env.TWILIO_WSS_BASE_URL || '';
+  }
 
   if (!accountSid || !authToken) {
     throw new Error('Twilio credentials not configured. Set credential:twilio:account_sid and credential:twilio:auth_token via the credential_store tool.');

package/src/calls/twilio-routes.ts

@@ -22,6 +22,8 @@ import type { CallStatus } from './types.js';
 import { logDeadLetterEvent } from './call-recovery.js';
 import { isTerminalState } from './call-state-machine.js';
 import { getTwilioConfig } from './twilio-config.js';
+import { loadConfig } from '../config/loader.js';
+import { getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
 
 const log = getLogger('twilio-routes');
 
@@ -125,8 +127,14 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     log.info({ callSessionId, callSid }, 'Stored CallSid from voice webhook');
   }
 
-  const config = getTwilioConfig();
-  const relayUrl = resolveRelayUrl(config.wssBaseUrl, config.webhookBaseUrl);
+  const twilioConfig = getTwilioConfig();
+  let relayUrl: string;
+  try {
+    relayUrl = getTwilioRelayUrl(loadConfig());
+  } catch {
+    // Fallback to legacy resolution when ingress is not configured
+    relayUrl = resolveRelayUrl(twilioConfig.wssBaseUrl, twilioConfig.webhookBaseUrl);
+  }
   const welcomeGreeting = process.env.CALL_WELCOME_GREETING ?? 'Hello, how can I help you today?';
 
   const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting);

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.