vellum 0.2.12 → 0.2.14

package/src/__tests__/call-bridge.test.ts

@@ -101,7 +101,7 @@ import {
   fireCallCompletionNotifier,
 } from '../calls/call-state.js';
 import { CallOrchestrator } from '../calls/call-orchestrator.js';
-import { tryHandlePendingCallAnswer } from '../calls/call-bridge.js';
+import { tryRouteCallMessage } from '../calls/call-bridge.js';
 import * as conversationStore from '../memory/conversation-store.js';
 import type { RelayConnection } from '../calls/relay-server.js';
 
@@ -177,26 +177,27 @@ describe('call-bridge', () => {
     mockStreamFn.mockImplementation(() => createMockStream(['Hello']));
   });
 
-  // ── tryHandlePendingCallAnswer ──────────────────────────────────
+  // ── tryRouteCallMessage — answer path ───────────────────────
 
   test('returns handled:false when no active call exists', async () => {
     ensureConversation('conv-no-call');
-    const result = await tryHandlePendingCallAnswer('conv-no-call', 'some answer');
+    const result = await tryRouteCallMessage('conv-no-call', 'some answer');
     expect(result.handled).toBe(false);
     expect(result.reason).toBe('no_active_call');
   });
 
-  test('returns handled:false when call exists but no pending question', async () => {
-    ensureConversation('conv-no-question');
+  test('returns instruction_relay_failed (consumed) when call exists but no orchestrator and no pending question', async () => {
+    ensureConversation('conv-no-orch');
     createCallSession({
-      conversationId: 'conv-no-question',
+      conversationId: 'conv-no-orch',
       provider: 'twilio',
       fromNumber: '+15551111111',
       toNumber: '+15552222222',
     });
-    const result = await tryHandlePendingCallAnswer('conv-no-question', 'some answer');
-    expect(result.handled).toBe(false);
-    expect(result.reason).toBe('no_pending_question');
+    const result = await tryRouteCallMessage('conv-no-orch', 'some instruction');
+    expect(result.handled).toBe(true);
+    expect(result.reason).toBe('instruction_relay_failed');
+    expect(result.userFacingText).toBe('Failed to relay instruction to the active call.');
   });
 
   test('returns handled:false when orchestrator is not found (call still active but no orchestrator)', async () => {
@@ -215,7 +216,7 @@ describe('call-bridge', () => {
     // Create a pending question without an orchestrator
     createPendingQuestion(callSession.id, 'What time?');
 
-    const result = await tryHandlePendingCallAnswer('conv-ended', 'Too late');
+    const result = await tryRouteCallMessage('conv-ended', 'Too late');
     expect(result.handled).toBe(false);
     expect(result.reason).toBe('orchestrator_not_found');
   });
@@ -231,7 +232,7 @@ describe('call-bridge', () => {
     // Mark the call as completed — getActiveCallSessionForConversation will return null
     updateCallSession(callSession.id, { status: 'completed', endedAt: Date.now() });
 
-    const result = await tryHandlePendingCallAnswer('conv-completed', 'Too late');
+    const result = await tryRouteCallMessage('conv-completed', 'Too late');
     expect(result.handled).toBe(false);
     expect(result.reason).toBe('no_active_call');
   });
@@ -252,7 +253,7 @@ describe('call-bridge', () => {
     // Create a pending question in the DB but orchestrator is idle, not waiting_on_user
     createPendingQuestion(callSession.id, 'What time?');
 
-    const result = await tryHandlePendingCallAnswer('conv-not-waiting', 'answer');
+    const result = await tryRouteCallMessage('conv-not-waiting', 'answer');
     expect(result.handled).toBe(false);
     expect(result.reason).toBe('orchestrator_not_waiting');
 
@@ -284,7 +285,7 @@ describe('call-bridge', () => {
     // Now provide the answer — set up mock for the LLM call after answer
     mockStreamFn.mockImplementation(() => createMockStream(['Great, booking for tomorrow.']));
 
-    const result = await tryHandlePendingCallAnswer('conv-bridge', 'Tomorrow at noon');
+    const result = await tryRouteCallMessage('conv-bridge', 'Tomorrow at noon');
     expect(result.handled).toBe(true);
 
     // Wait for the fire-and-forget LLM call
@@ -298,6 +299,97 @@ describe('call-bridge', () => {
     orchestrator.destroy();
   });
 
+  // ── tryRouteCallMessage — instruction path ────────────────────
+
+  test('routes instruction to orchestrator when active call exists with no pending question', async () => {
+    ensureConversation('conv-instruct');
+    const callSession = createCallSession({
+      conversationId: 'conv-instruct',
+      provider: 'twilio',
+      fromNumber: '+15551111111',
+      toNumber: '+15552222222',
+    });
+
+    const relay = createMockRelay();
+    const orchestrator = new CallOrchestrator(callSession.id, relay as unknown as RelayConnection, 'test task');
+
+    const result = await tryRouteCallMessage('conv-instruct', 'Please ask about pricing');
+    expect(result.handled).toBe(true);
+    expect(result.userFacingText).toBe('Instruction relayed to active call.');
+
+    // Verify acknowledgement was persisted
+    const msgs = getMessagesForConversation('conv-instruct');
+    const ackMsg = msgs.find((m) => m.content.includes('Instruction relayed'));
+    expect(ackMsg).toBeDefined();
+    expect(ackMsg!.role).toBe('assistant');
+
+    orchestrator.destroy();
+  });
+
+  test('prefers answer path over instruction path when pending question exists', async () => {
+    // Setup: trigger ASK_USER to put orchestrator in waiting_on_user state
+    mockStreamFn.mockImplementation(() =>
+      createMockStream(['Hold on. [ASK_USER: Budget range?]']),
+    );
+
+    ensureConversation('conv-prefer-answer');
+    const callSession = createCallSession({
+      conversationId: 'conv-prefer-answer',
+      provider: 'twilio',
+      fromNumber: '+15551111111',
+      toNumber: '+15552222222',
+    });
+
+    const relay = createMockRelay();
+    const orchestrator = new CallOrchestrator(callSession.id, relay as unknown as RelayConnection, 'test task');
+
+    await orchestrator.handleCallerUtterance('What is your budget?');
+    expect(orchestrator.getState()).toBe('waiting_on_user');
+
+    // Mock the next LLM call
+    mockStreamFn.mockImplementation(() => createMockStream(['Got it, thanks.']));
+
+    // This should route as answer, not instruction
+    const result = await tryRouteCallMessage('conv-prefer-answer', '$500');
+    expect(result.handled).toBe(true);
+
+    // Wait for fire-and-forget LLM call
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Should have answered the pending question, not relayed as instruction
+    const question = getPendingQuestion(callSession.id);
+    expect(question).toBeNull();
+
+    // No instruction acknowledgement should be persisted
+    const msgs = getMessagesForConversation('conv-prefer-answer');
+    const ackMsg = msgs.find((m) => m.content.includes('Instruction relayed'));
+    expect(ackMsg).toBeUndefined();
+
+    orchestrator.destroy();
+  });
+
+  test('instruction relay failure persists notice and is consumed (handled:true)', async () => {
+    ensureConversation('conv-no-orch-instruct');
+    createCallSession({
+      conversationId: 'conv-no-orch-instruct',
+      provider: 'twilio',
+      fromNumber: '+15551111111',
+      toNumber: '+15552222222',
+    });
+
+    // No orchestrator registered — relay should fail but still be consumed
+    const result = await tryRouteCallMessage('conv-no-orch-instruct', 'Change the topic');
+    expect(result.handled).toBe(true);
+    expect(result.reason).toBe('instruction_relay_failed');
+    expect(result.userFacingText).toBe('Failed to relay instruction to the active call.');
+
+    // Verify failure notice was persisted in-thread
+    const msgs = getMessagesForConversation('conv-no-orch-instruct');
+    const failMsg = msgs.find((m) => m.content.includes('Failed to relay'));
+    expect(failMsg).toBeDefined();
+    expect(failMsg!.role).toBe('assistant');
+  });
+
   // ── Call question notifier ──────────────────────────────────────
 
   test('call question notifier persists assistant message and emits events', () => {

package/src/__tests__/call-domain.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Unit tests for caller identity resolution in call-domain.ts.
+ *
+ * Validates the strict implicit-default policy:
+ * - Implicit calls (no explicit mode) always use assistant_number.
+ * - Explicit user_number calls succeed when eligible.
+ * - Explicit user_number calls fail clearly when missing/ineligible.
+ * - Explicit override rejected when allowPerCallOverride=false.
+ */
+import { describe, test, expect, mock } from 'bun:test';
+import { mkdtempSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testDir = realpathSync(mkdtempSync(join(tmpdir(), 'call-domain-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('../calls/twilio-config.js', () => ({
+  getTwilioConfig: () => ({
+    accountSid: 'AC_test',
+    authToken: 'test_token',
+    phoneNumber: '+15550001111',
+    webhookBaseUrl: 'https://test.example.com',
+    wssBaseUrl: 'wss://test.example.com',
+  }),
+}));
+
+mock.module('../calls/twilio-provider.js', () => ({
+  TwilioConversationRelayProvider: class {
+    async checkCallerIdEligibility(number: string) {
+      // Simulate: +15550002222 is eligible, others are not
+      if (number === '+15550002222') return { eligible: true };
+      return { eligible: false, reason: `${number} is not eligible as a caller ID` };
+    }
+  },
+}));
+
+mock.module('../security/secure-keys.js', () => ({
+  getSecureKey: () => null,
+}));
+
+import { resolveCallerIdentity } from '../calls/call-domain.js';
+import type { AssistantConfig } from '../config/types.js';
+
+function makeConfig(overrides: {
+  allowPerCallOverride?: boolean;
+  userNumber?: string;
+} = {}): AssistantConfig {
+  return {
+    calls: {
+      callerIdentity: {
+        allowPerCallOverride: overrides.allowPerCallOverride ?? true,
+        userNumber: overrides.userNumber,
+      },
+    },
+  } as unknown as AssistantConfig;
+}
+
+describe('resolveCallerIdentity — strict implicit-default policy', () => {
+  test('implicit call defaults to assistant_number', async () => {
+    const result = await resolveCallerIdentity(makeConfig());
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.mode).toBe('assistant_number');
+      expect(result.fromNumber).toBe('+15550001111');
+      expect(result.source).toBe('implicit_default');
+    }
+  });
+
+  test('implicit call uses assistant_number even when userNumber is configured', async () => {
+    const result = await resolveCallerIdentity(
+      makeConfig({ userNumber: '+15550002222' }),
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.mode).toBe('assistant_number');
+      expect(result.fromNumber).toBe('+15550001111');
+      expect(result.source).toBe('implicit_default');
+    }
+  });
+
+  test('explicit user_number succeeds when eligible', async () => {
+    const result = await resolveCallerIdentity(
+      makeConfig({ userNumber: '+15550002222' }),
+      'user_number',
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.mode).toBe('user_number');
+      expect(result.fromNumber).toBe('+15550002222');
+      expect(result.source).toBe('user_config');
+    }
+  });
+
+  test('explicit user_number fails when no user phone configured', async () => {
+    const result = await resolveCallerIdentity(makeConfig(), 'user_number');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain('user_number');
+      expect(result.error).toContain('user phone number');
+    }
+  });
+
+  test('explicit user_number fails when number is ineligible', async () => {
+    const result = await resolveCallerIdentity(
+      makeConfig({ userNumber: '+15559999999' }),
+      'user_number',
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain('not eligible');
+    }
+  });
+
+  test('explicit override rejected when allowPerCallOverride=false', async () => {
+    const result = await resolveCallerIdentity(
+      makeConfig({ allowPerCallOverride: false, userNumber: '+15550002222' }),
+      'user_number',
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain('override is disabled');
+    }
+  });
+
+  test('explicit assistant_number override succeeds when allowed', async () => {
+    const result = await resolveCallerIdentity(makeConfig(), 'assistant_number');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.mode).toBe('assistant_number');
+      expect(result.source).toBe('per_call_override');
+    }
+  });
+
+  test('invalid mode returns error', async () => {
+    const result = await resolveCallerIdentity(
+      makeConfig(),
+      'custom_number' as 'assistant_number',
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain('Invalid callerIdentityMode');
+    }
+  });
+});

package/src/__tests__/call-orchestrator.test.ts

@@ -29,6 +29,8 @@ mock.module('../util/logger.js', () => ({
 
 // ── Config mock ─────────────────────────────────────────────────────
 
+let mockCallModel: string | undefined = undefined;
+
 mock.module('../config/loader.js', () => ({
   getConfig: () => ({
     apiKeys: { anthropic: 'test-key' },
@@ -41,6 +43,7 @@ mock.module('../config/loader.js', () => ({
       silenceTimeoutSeconds: 30,
       disclosure: { enabled: false, text: '' },
       safety: { denyCategories: [] },
+      model: mockCallModel,
     },
   }),
 }));
@@ -97,6 +100,7 @@ import { conversations } from '../memory/schema.js';
 import {
   createCallSession,
   getCallSession,
+  getCallEvents,
   getPendingQuestion,
   updateCallSession,
 } from '../calls/call-store.js';
@@ -192,6 +196,7 @@ function setupOrchestrator(task?: string) {
 describe('call-orchestrator', () => {
   beforeEach(() => {
     resetTables();
+    mockCallModel = undefined;
     // Reset the stream mock to default behaviour
     mockStreamFn.mockImplementation(() => createMockStream(['Hello', ' there']));
   });
@@ -451,4 +456,170 @@ describe('call-orchestrator', () => {
     // Second destroy should not throw
     expect(() => orchestrator.destroy()).not.toThrow();
   });
+
+  // ── Model override from config ──────────────────────────────────────
+
+  test('uses default model when calls.model is not set', async () => {
+    mockCallModel = undefined;
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { model: string };
+      expect(firstArg.model).toBe('claude-sonnet-4-20250514');
+      return createMockStream(['Default model response.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hello');
+    orchestrator.destroy();
+  });
+
+  test('uses calls.model override from config when set', async () => {
+    mockCallModel = 'claude-haiku-4-5-20251001';
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { model: string };
+      expect(firstArg.model).toBe('claude-haiku-4-5-20251001');
+      return createMockStream(['Override model response.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hello');
+    orchestrator.destroy();
+  });
+
+  test('treats empty string calls.model as unset and falls back to default', async () => {
+    mockCallModel = '';
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { model: string };
+      expect(firstArg.model).toBe('claude-sonnet-4-20250514');
+      return createMockStream(['Fallback model response.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hello');
+    orchestrator.destroy();
+  });
+
+  test('treats whitespace-only calls.model as unset and falls back to default', async () => {
+    mockCallModel = '   ';
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { model: string };
+      expect(firstArg.model).toBe('claude-sonnet-4-20250514');
+      return createMockStream(['Fallback model response.']);
+    });
+
+    const { orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('Hello');
+    orchestrator.destroy();
+  });
+
+  // ── handleUserInstruction ─────────────────────────────────────────
+
+  test('handleUserInstruction: injects instruction marker into conversation history and triggers LLM when idle', async () => {
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { messages: Array<{ role: string; content: string }> };
+      const instructionMsg = firstArg.messages.find((m) =>
+        m.role === 'user' && m.content.includes('[USER_INSTRUCTION:'),
+      );
+      expect(instructionMsg).toBeDefined();
+      expect(instructionMsg!.content).toContain('[USER_INSTRUCTION: Ask about their weekend plans]');
+      return createMockStream(['Sure, do you have any weekend plans?']);
+    });
+
+    const { relay, orchestrator } = setupOrchestrator();
+
+    await orchestrator.handleUserInstruction('Ask about their weekend plans');
+
+    // Should have streamed a response since orchestrator was idle
+    const nonEmptyTokens = relay.sentTokens.filter((t) => t.token.length > 0);
+    expect(nonEmptyTokens.length).toBeGreaterThan(0);
+
+    orchestrator.destroy();
+  });
+
+  test('handleUserInstruction: does not break existing answer flow', async () => {
+    // Step 1: Caller says something, LLM responds normally
+    mockStreamFn.mockImplementation(() => createMockStream(['Hello! How can I help you today?']));
+    const { session: _session, relay, orchestrator } = setupOrchestrator('Book appointment');
+
+    await orchestrator.handleCallerUtterance('Hi there');
+
+    // Step 2: Inject an instruction while idle
+    mockStreamFn.mockImplementation((...args: unknown[]) => {
+      const firstArg = args[0] as { messages: Array<{ role: string; content: string }> };
+      // Verify the history contains both the original exchange and the instruction
+      const messages = firstArg.messages;
+      expect(messages.length).toBeGreaterThanOrEqual(3); // user utterance + assistant response + instruction
+      const instructionMsg = messages.find((m) =>
+        m.role === 'user' && m.content.includes('[USER_INSTRUCTION:'),
+      );
+      expect(instructionMsg).toBeDefined();
+      return createMockStream(['Of course, let me mention the weekend special.']);
+    });
+
+    await orchestrator.handleUserInstruction('Mention the weekend special');
+
+    // Step 3: Caller speaks again — the flow should continue normally
+    mockStreamFn.mockImplementation(() =>
+      createMockStream(['Great choice! The weekend special is 20% off.']),
+    );
+
+    await orchestrator.handleCallerUtterance('Tell me more about that');
+
+    // Verify state is idle after the normal flow
+    expect(orchestrator.getState()).toBe('idle');
+
+    // Verify relay received tokens from all exchanges
+    const allText = relay.sentTokens.map((t) => t.token).join('');
+    expect(allText).toContain('Hello');
+    expect(allText).toContain('weekend special');
+
+    orchestrator.destroy();
+  });
+
+  test('handleUserInstruction: emits user_instruction_relayed event', async () => {
+    mockStreamFn.mockImplementation(() => createMockStream(['Understood, adjusting approach.']));
+
+    const { session, orchestrator } = setupOrchestrator();
+
+    await orchestrator.handleUserInstruction('Be more formal in your tone');
+
+    const events = getCallEvents(session.id);
+    const instructionEvents = events.filter((e) => e.eventType === 'user_instruction_relayed');
+    expect(instructionEvents.length).toBe(1);
+
+    const payload = JSON.parse(instructionEvents[0].payloadJson);
+    expect(payload.instruction).toBe('Be more formal in your tone');
+
+    orchestrator.destroy();
+  });
+
+  test('handleUserInstruction: does not trigger LLM when orchestrator is not idle', async () => {
+    // First, trigger ASK_USER so orchestrator enters waiting_on_user
+    mockStreamFn.mockImplementation(() =>
+      createMockStream(['Hold on. [ASK_USER: What time?]']),
+    );
+
+    const { session, orchestrator } = setupOrchestrator();
+    await orchestrator.handleCallerUtterance('I need an appointment');
+    expect(orchestrator.getState()).toBe('waiting_on_user');
+
+    // Track how many times the stream mock is called
+    let streamCallCount = 0;
+    mockStreamFn.mockImplementation(() => {
+      streamCallCount++;
+      return createMockStream(['Response after instruction.']);
+    });
+
+    // Inject instruction while in waiting_on_user state
+    await orchestrator.handleUserInstruction('Suggest morning slots');
+
+    // The LLM should NOT have been triggered since we're not idle
+    expect(streamCallCount).toBe(0);
+
+    // But the event should still be recorded
+    const events = getCallEvents(session.id);
+    const instructionEvents = events.filter((e) => e.eventType === 'user_instruction_relayed');
+    expect(instructionEvents.length).toBe(1);
+
+    orchestrator.destroy();
+  });
 });