vellum 0.2.2 → 0.2.8

package/src/__tests__/public-ingress-urls.test.ts

@@ -0,0 +1,206 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Mocks — silence logger output during tests
+// ---------------------------------------------------------------------------
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of ['info', 'warn', 'error', 'debug', 'trace', 'fatal', 'silent', 'child']) {
+    stub[m] = m === 'child' ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+import {
+  getPublicBaseUrl,
+  getTwilioVoiceWebhookUrl,
+  getTwilioStatusCallbackUrl,
+  getTwilioConnectActionUrl,
+  getTwilioRelayUrl,
+  getOAuthCallbackUrl,
+} from '../inbound/public-ingress-urls.js';
+
+// ---------------------------------------------------------------------------
+// getPublicBaseUrl — fallback chain
+// ---------------------------------------------------------------------------
+
+describe('getPublicBaseUrl', () => {
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    savedEnv = process.env.TWILIO_WEBHOOK_BASE_URL;
+    delete process.env.TWILIO_WEBHOOK_BASE_URL;
+  });
+
+  afterEach(() => {
+    if (savedEnv !== undefined) {
+      process.env.TWILIO_WEBHOOK_BASE_URL = savedEnv;
+    } else {
+      delete process.env.TWILIO_WEBHOOK_BASE_URL;
+    }
+  });
+
+  test('prefers ingress.publicBaseUrl when set', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: 'https://ingress.example.com/' },
+      calls: { webhookBaseUrl: 'https://calls.example.com' },
+    });
+    expect(result).toBe('https://ingress.example.com');
+  });
+
+  test('falls back to calls.webhookBaseUrl when ingress.publicBaseUrl is empty', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '' },
+      calls: { webhookBaseUrl: 'https://calls.example.com/' },
+    });
+    expect(result).toBe('https://calls.example.com');
+  });
+
+  test('falls back to calls.webhookBaseUrl when ingress is undefined', () => {
+    const result = getPublicBaseUrl({
+      calls: { webhookBaseUrl: 'https://calls.example.com' },
+    });
+    expect(result).toBe('https://calls.example.com');
+  });
+
+  test('falls back to TWILIO_WEBHOOK_BASE_URL env var when both config fields are empty', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com/';
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '' },
+      calls: { webhookBaseUrl: '' },
+    });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('falls back to env var when config fields are undefined', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getPublicBaseUrl({});
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('throws when no source provides a value', () => {
+    expect(() => getPublicBaseUrl({
+      ingress: { publicBaseUrl: '' },
+      calls: { webhookBaseUrl: '' },
+    })).toThrow(/No public base URL configured/);
+  });
+
+  test('throws when all sources are undefined', () => {
+    expect(() => getPublicBaseUrl({})).toThrow(/No public base URL configured/);
+  });
+
+  test('normalizes trailing slashes from ingress.publicBaseUrl', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: 'https://example.com///' },
+    });
+    expect(result).toBe('https://example.com');
+  });
+
+  test('trims whitespace from ingress.publicBaseUrl', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '  https://example.com  ' },
+    });
+    expect(result).toBe('https://example.com');
+  });
+
+  test('skips whitespace-only ingress.publicBaseUrl and falls through', () => {
+    const result = getPublicBaseUrl({
+      ingress: { publicBaseUrl: '   ' },
+      calls: { webhookBaseUrl: 'https://calls.example.com' },
+    });
+    expect(result).toBe('https://calls.example.com');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioVoiceWebhookUrl
+// ---------------------------------------------------------------------------
+
+describe('getTwilioVoiceWebhookUrl', () => {
+  test('builds correct URL with callSessionId', () => {
+    const url = getTwilioVoiceWebhookUrl(
+      { ingress: { publicBaseUrl: 'https://example.com' } },
+      'session-123',
+    );
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=session-123');
+  });
+
+  test('normalizes base URL before composing', () => {
+    const url = getTwilioVoiceWebhookUrl(
+      { ingress: { publicBaseUrl: 'https://example.com/' } },
+      'abc',
+    );
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=abc');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioStatusCallbackUrl
+// ---------------------------------------------------------------------------
+
+describe('getTwilioStatusCallbackUrl', () => {
+  test('builds correct URL', () => {
+    const url = getTwilioStatusCallbackUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('https://example.com/webhooks/twilio/status');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioConnectActionUrl
+// ---------------------------------------------------------------------------
+
+describe('getTwilioConnectActionUrl', () => {
+  test('builds correct URL', () => {
+    const url = getTwilioConnectActionUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('https://example.com/webhooks/twilio/connect-action');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTwilioRelayUrl — scheme conversion
+// ---------------------------------------------------------------------------
+
+describe('getTwilioRelayUrl', () => {
+  test('converts https to wss', () => {
+    const url = getTwilioRelayUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('wss://example.com/webhooks/twilio/relay');
+  });
+
+  test('converts http to ws', () => {
+    const url = getTwilioRelayUrl({
+      ingress: { publicBaseUrl: 'http://localhost:7821' },
+    });
+    expect(url).toBe('ws://localhost:7821/webhooks/twilio/relay');
+  });
+
+  test('normalizes trailing slash before conversion', () => {
+    const url = getTwilioRelayUrl({
+      ingress: { publicBaseUrl: 'https://example.com/' },
+    });
+    expect(url).toBe('wss://example.com/webhooks/twilio/relay');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getOAuthCallbackUrl
+// ---------------------------------------------------------------------------
+
+describe('getOAuthCallbackUrl', () => {
+  test('builds correct URL', () => {
+    const url = getOAuthCallbackUrl({
+      ingress: { publicBaseUrl: 'https://example.com' },
+    });
+    expect(url).toBe('https://example.com/webhooks/oauth/callback');
+  });
+});

package/src/__tests__/session-conflict-gate.test.ts

@@ -39,8 +39,18 @@ let resolverResult: {
 
 const persistedMessages: Array<{ id: string; role: string; content: string; createdAt: number }> = [];
 
+function makeMockLogger(): Record<string, unknown> {
+  const logger: Record<string, unknown> = {};
+  logger.child = () => logger;
+  logger.debug = () => {};
+  logger.info = () => {};
+  logger.warn = () => {};
+  logger.error = () => {};
+  return logger;
+}
+
 mock.module('../util/logger.js', () => ({
-  getLogger: () => new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+  getLogger: () => makeMockLogger(),
 }));
 
 mock.module('../util/platform.js', () => ({
@@ -305,7 +315,7 @@ describe('Session conflict soft gate', () => {
     await session.processMessage('Should I use React or Vue here?', [], (event) => events.push(event));
 
     expect(runCalls).toHaveLength(0);
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-relevant']);
     const clarificationEvent = events.find((event) => event.type === 'assistant_text_delta');
     expect(clarificationEvent).toBeDefined();
@@ -315,7 +325,7 @@ describe('Session conflict soft gate', () => {
     expect(events.some((event) => event.type === 'message_complete')).toBe(true);
   });
 
-  test('irrelevant unresolved conflict asks once and continues with normal answer flow', async () => {
+  test('irrelevant unresolved conflict does not inject side-question into normal answer flow', async () => {
     pendingConflicts = [{
       id: 'conflict-irrelevant',
       scopeId: 'default',
@@ -332,13 +342,6 @@ describe('Session conflict soft gate', () => {
       existingStatement: 'Use Postgres as the default database.',
       candidateStatement: 'Use MySQL as the default database.',
     }];
-    resolverResult = {
-      resolution: 'keep_existing',
-      strategy: 'heuristic',
-      resolvedStatement: null,
-      explanation: 'Resolved by accident.',
-    };
-
     const session = makeSession();
     await session.loadFromDb();
 
@@ -349,10 +352,10 @@ describe('Session conflict soft gate', () => {
     const injectedUser = runCalls[0][runCalls[0].length - 1];
     expect(injectedUser.role).toBe('user');
     const injectedText = extractText(injectedUser);
-    expect(injectedText).toContain('Memory clarification request');
-    expect(injectedText).toContain('Should I assume Postgres or MySQL?');
+    expect(injectedText).not.toContain('Memory clarification request');
+    expect(injectedText).not.toContain('Should I assume Postgres or MySQL?');
     expect(resolverCallCount).toBe(0);
-    expect(markAskedCalls).toEqual(['conflict-irrelevant']);
+    expect(markAskedCalls).toEqual([]);
     expect(events.some((event) => event.type === 'message_complete')).toBe(true);
   });
 
@@ -379,7 +382,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn asks the clarification and records it as asked.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-followup']);
 
     resolverResult = {
@@ -392,7 +395,7 @@ describe('Session conflict soft gate', () => {
     // Follow-up reply does not overlap statement tokens but should still resolve.
     await session.processMessage('Keep the new one.', [], () => {});
 
-    expect(resolverCallCount).toBe(2);
+    expect(resolverCallCount).toBe(1);
     expect(markAskedCalls).toEqual(['conflict-followup']);
     expect(runCalls).toHaveLength(1);
   });
@@ -420,7 +423,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn asks the clarification.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-concise']);
 
     resolverResult = {
@@ -433,7 +436,7 @@ describe('Session conflict soft gate', () => {
     // Short directional reply with no action verb should still resolve.
     await session.processMessage('both', [], () => {});
 
-    expect(resolverCallCount).toBe(2);
+    expect(resolverCallCount).toBe(1);
     expect(runCalls).toHaveLength(1);
   });
 
@@ -460,7 +463,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn: relevant question triggers clarification ask.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-unrelated']);
 
     // Second turn: unrelated question containing the cue word "new" should NOT
@@ -473,8 +476,8 @@ describe('Session conflict soft gate', () => {
     };
     await session.processMessage("What's new in Bun?", [], () => {});
 
-    // The resolver should NOT have been called again for this unrelated question.
-    expect(resolverCallCount).toBe(1);
+    // The resolver should NOT have been called for this unrelated question.
+    expect(resolverCallCount).toBe(0);
     // Normal agent loop should still run.
     expect(runCalls).toHaveLength(1);
   });
@@ -502,7 +505,7 @@ describe('Session conflict soft gate', () => {
 
     // First turn: triggers clarification ask.
     await session.processMessage('Should I assume Postgres or MySQL?', [], () => {});
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(markAskedCalls).toEqual(['conflict-unrelated-no-qmark']);
 
     resolverResult = {
@@ -516,11 +519,11 @@ describe('Session conflict soft gate', () => {
     // Should NOT resolve the conflict.
     await session.processMessage('I started a new project today', [], () => {});
 
-    expect(resolverCallCount).toBe(1);
+    expect(resolverCallCount).toBe(0);
     expect(runCalls).toHaveLength(1);
   });
 
-  test('cooldown prevents repeated asks on subsequent turns', async () => {
+  test('irrelevant conflicts remain silent across subsequent turns', async () => {
     pendingConflicts = [{
       id: 'conflict-cooldown',
       scopeId: 'default',
@@ -547,9 +550,9 @@ describe('Session conflict soft gate', () => {
     expect(runCalls).toHaveLength(2);
     const firstUserText = extractText(runCalls[0][runCalls[0].length - 1]);
     const secondUserText = extractText(runCalls[1][runCalls[1].length - 1]);
-    expect(firstUserText).toContain('Memory clarification request');
+    expect(firstUserText).not.toContain('Memory clarification request');
     expect(secondUserText).not.toContain('Memory clarification request');
-    expect(markAskedCalls).toEqual(['conflict-cooldown']);
+    expect(markAskedCalls).toEqual([]);
   });
 
   test('passes session scopeId through to conflict store queries', async () => {

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/calls/__tests__/twilio-webhook-urls.test.ts

@@ -0,0 +1,162 @@
+import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Mocks — silence logger output during tests
+// ---------------------------------------------------------------------------
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of ['info', 'warn', 'error', 'debug', 'trace', 'fatal', 'silent', 'child']) {
+    stub[m] = m === 'child' ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module('../../util/logger.js', () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+import {
+  normalizeBaseUrl,
+  buildTwilioVoiceWebhookUrl,
+  buildTwilioStatusCallbackUrl,
+  getWebhookBaseUrl,
+} from '../twilio-webhook-urls.js';
+
+// ---------------------------------------------------------------------------
+// normalizeBaseUrl
+// ---------------------------------------------------------------------------
+
+describe('normalizeBaseUrl', () => {
+  test('returns already-clean URL unchanged', () => {
+    expect(normalizeBaseUrl('https://example.com')).toBe('https://example.com');
+  });
+
+  test('strips trailing slash', () => {
+    expect(normalizeBaseUrl('https://example.com/')).toBe('https://example.com');
+  });
+
+  test('strips multiple trailing slashes', () => {
+    expect(normalizeBaseUrl('https://example.com///')).toBe('https://example.com');
+  });
+
+  test('trims leading and trailing whitespace', () => {
+    expect(normalizeBaseUrl('  https://example.com  ')).toBe('https://example.com');
+  });
+
+  test('trims whitespace and strips trailing slash together', () => {
+    expect(normalizeBaseUrl('  https://example.com/  ')).toBe('https://example.com');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTwilioVoiceWebhookUrl
+// ---------------------------------------------------------------------------
+
+describe('buildTwilioVoiceWebhookUrl', () => {
+  test('returns correct URL with callSessionId', () => {
+    const url = buildTwilioVoiceWebhookUrl('https://example.com', 'session-123');
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=session-123');
+  });
+
+  test('normalizes base URL before composing', () => {
+    const url = buildTwilioVoiceWebhookUrl('https://example.com/', 'abc');
+    expect(url).toBe('https://example.com/webhooks/twilio/voice?callSessionId=abc');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildTwilioStatusCallbackUrl
+// ---------------------------------------------------------------------------
+
+describe('buildTwilioStatusCallbackUrl', () => {
+  test('returns correct URL', () => {
+    const url = buildTwilioStatusCallbackUrl('https://example.com');
+    expect(url).toBe('https://example.com/webhooks/twilio/status');
+  });
+
+  test('normalizes base URL before composing', () => {
+    const url = buildTwilioStatusCallbackUrl('https://example.com/');
+    expect(url).toBe('https://example.com/webhooks/twilio/status');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getWebhookBaseUrl
+// ---------------------------------------------------------------------------
+
+describe('getWebhookBaseUrl', () => {
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    savedEnv = process.env.TWILIO_WEBHOOK_BASE_URL;
+    delete process.env.TWILIO_WEBHOOK_BASE_URL;
+  });
+
+  afterEach(() => {
+    if (savedEnv !== undefined) {
+      process.env.TWILIO_WEBHOOK_BASE_URL = savedEnv;
+    } else {
+      delete process.env.TWILIO_WEBHOOK_BASE_URL;
+    }
+  });
+
+  test('uses config value when set', () => {
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: 'https://config.example.com/' } });
+    expect(result).toBe('https://config.example.com');
+  });
+
+  test('falls back to env var when config value is empty', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com/';
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '' } });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('falls back to env var when config value is undefined', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getWebhookBaseUrl({ calls: {} });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('throws when neither config nor env var is set', () => {
+    expect(() => getWebhookBaseUrl({ calls: { webhookBaseUrl: '' } })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+
+  test('throws when config is undefined and env var is unset', () => {
+    expect(() => getWebhookBaseUrl({ calls: {} })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+
+  test('normalizes the returned URL', () => {
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '  https://example.com/  ' } });
+    expect(result).toBe('https://example.com');
+  });
+
+  test('falls through when config value is whitespace-only', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '   ' } });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('falls through when config value is slash-only', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = 'https://env.example.com';
+    const result = getWebhookBaseUrl({ calls: { webhookBaseUrl: '///' } });
+    expect(result).toBe('https://env.example.com');
+  });
+
+  test('throws when config is whitespace-only and env var is unset', () => {
+    expect(() => getWebhookBaseUrl({ calls: { webhookBaseUrl: '   ' } })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+
+  test('throws when env var is whitespace-only and config is empty', () => {
+    process.env.TWILIO_WEBHOOK_BASE_URL = '   ';
+    expect(() => getWebhookBaseUrl({ calls: {} })).toThrow(
+      /No webhook base URL configured/,
+    );
+  });
+});