@vellumai/assistant 0.3.4 → 0.3.6

package/src/__tests__/relay-server.test.ts

@@ -17,7 +17,6 @@ import { describe, test, expect, beforeEach, afterAll, mock, type Mock } from 'b
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { EventEmitter } from 'node:events';
 
 const testDir = mkdtempSync(join(tmpdir(), 'relay-server-test-'));
 
@@ -33,6 +32,7 @@ mock.module('../util/platform.js', () => ({
   getDbPath: () => join(testDir, 'test.db'),
   getLogPath: () => join(testDir, 'test.log'),
   ensureDataDir: () => {},
+  readHttpToken: () => null,
 }));
 
 mock.module('../util/logger.js', () => ({
@@ -44,53 +44,75 @@ mock.module('../util/logger.js', () => ({
 
 // ── Config mock ─────────────────────────────────────────────────────
 
-mock.module('../config/loader.js', () => ({
-  getConfig: () => ({
-    apiKeys: { anthropic: 'test-key' },
-    calls: {
-      enabled: true,
-      provider: 'twilio',
-      maxDurationSeconds: 3600,
-      userConsultTimeoutSeconds: 120,
-      disclosure: { enabled: false, text: '' },
-      safety: { denyCategories: [] },
+const mockConfig = {
+  provider: 'anthropic',
+  providerOrder: ['anthropic'],
+  apiKeys: { anthropic: 'test-key' },
+  calls: {
+    enabled: true,
+    provider: 'twilio',
+    maxDurationSeconds: 3600,
+    userConsultTimeoutSeconds: 120,
+    disclosure: { enabled: false, text: '' },
+    safety: { denyCategories: [] },
+    verification: {
+      enabled: false,
+      maxAttempts: 3,
+      codeLength: 6,
     },
-  }),
+  },
+  memory: { enabled: false },
+};
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => mockConfig,
 }));
 
-// ── Anthropic SDK mock ──────────────────────────────────────────────
+// ── Helpers for building mock provider responses ────────────────────
 
-function createMockStream(tokens: string[]) {
-  const emitter = new EventEmitter();
+function createMockProviderResponse(tokens: string[]) {
   const fullText = tokens.join('');
-
-  const stream = {
-    on: (event: string, handler: (...args: unknown[]) => void) => {
-      emitter.on(event, handler);
-      return stream;
-    },
-    finalMessage: () => {
-      for (const token of tokens) {
-        emitter.emit('text', token);
-      }
-      return Promise.resolve({
-        content: [{ type: 'text', text: fullText }],
-      });
-    },
+  return async (
+    _messages: unknown[],
+    _tools: unknown[],
+    _systemPrompt: string,
+    options?: { onEvent?: (event: { type: string; text?: string }) => void; signal?: AbortSignal },
+  ) => {
+    for (const token of tokens) {
+      options?.onEvent?.({ type: 'text_delta', text: token });
+    }
+    return {
+      content: [{ type: 'text', text: fullText }],
+      model: 'claude-sonnet-4-20250514',
+      usage: { inputTokens: 100, outputTokens: 50 },
+      stopReason: 'end_turn',
+    };
   };
-
-  return stream;
 }
 
-let mockStreamFn: Mock<(...args: unknown[]) => unknown>;
+// ── Provider registry mock ──────────────────────────────────────────
 
-mock.module('@anthropic-ai/sdk', () => {
-  mockStreamFn = mock((..._args: unknown[]) => createMockStream(['Hello']));
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mockSendMessage: Mock<any>;
+
+mock.module('../providers/registry.js', () => {
+  mockSendMessage = mock(createMockProviderResponse(['Hello']));
   return {
-    default: class MockAnthropic {
-      messages = {
-        stream: (...args: unknown[]) => mockStreamFn(...args),
+    listProviders: () => ['anthropic'],
+    getFailoverProvider: () => ({
+      name: 'anthropic',
+      sendMessage: (...args: unknown[]) => mockSendMessage(...args),
+    }),
+    getDefaultModel: (providerName: string) => {
+      const defaults: Record<string, string> = {
+        anthropic: 'claude-opus-4-6',
+        openai: 'gpt-5.2',
+        gemini: 'gemini-3-flash',
+        ollama: 'llama3.2',
+        fireworks: 'accounts/fireworks/models/kimi-k2p5',
+        openrouter: 'x-ai/grok-4',
       };
+      return defaults[providerName] ?? defaults.anthropic;
     },
   };
 });
@@ -104,9 +126,15 @@ import {
   getCallSession,
   getCallEvents,
 } from '../calls/call-store.js';
+import { getMessages } from '../memory/conversation-store.js';
 import { registerCallCompletionNotifier, unregisterCallCompletionNotifier } from '../calls/call-state.js';
 import { RelayConnection, activeRelayConnections } from '../calls/relay-server.js';
 import type { RelayWebSocketData } from '../calls/relay-server.js';
+import {
+  createVerificationChallenge,
+  getGuardianBinding,
+} from '../runtime/channel-guardian-service.js';
+import { createBinding } from '../memory/channel-guardian-store.js';
 
 initializeDb();
 
@@ -159,18 +187,48 @@ function ensureConversation(id: string): void {
 
 function resetTables() {
   const db = getDb();
+  db.run('DELETE FROM guardian_action_deliveries');
+  db.run('DELETE FROM guardian_action_requests');
   db.run('DELETE FROM call_pending_questions');
   db.run('DELETE FROM call_events');
   db.run('DELETE FROM call_sessions');
+  db.run('DELETE FROM tool_invocations');
+  db.run('DELETE FROM messages');
   db.run('DELETE FROM conversations');
+  db.run('DELETE FROM channel_guardian_verification_challenges');
+  db.run('DELETE FROM channel_guardian_bindings');
+  db.run('DELETE FROM channel_guardian_rate_limits');
   ensuredConvIds = new Set();
 }
 
+function getLatestAssistantText(conversationId: string): string | null {
+  const messages = getMessages(conversationId).filter((m) => m.role === 'assistant');
+  if (messages.length === 0) return null;
+  const latest = messages[messages.length - 1];
+  try {
+    const parsed = JSON.parse(latest.content) as unknown;
+    if (Array.isArray(parsed)) {
+      return parsed
+        .filter((block): block is { type: string; text?: string } => typeof block === 'object' && block != null)
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text ?? '')
+        .join('');
+    }
+    if (typeof parsed === 'string') return parsed;
+  } catch {
+    // Ignore parse failures and fall back to raw content.
+  }
+  return latest.content;
+}
+
 describe('relay-server', () => {
   beforeEach(() => {
     resetTables();
     activeRelayConnections.clear();
-    mockStreamFn.mockImplementation(() => createMockStream(['Hello']));
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello']));
+    mockConfig.calls.verification.enabled = false;
+    mockConfig.calls.verification.maxAttempts = 3;
+    mockConfig.calls.verification.codeLength = 6;
   });
 
   // ── Setup message handling ──────────────────────────────────────
@@ -211,6 +269,41 @@ describe('relay-server', () => {
     relay.destroy();
   });
 
+  test('handleMessage: setup triggers initial assistant greeting turn', async () => {
+    ensureConversation('conv-relay-setup-greet');
+    const session = createCallSession({
+      conversationId: 'conv-relay-setup-greet',
+      provider: 'twilio',
+      fromNumber: '+15551111111',
+      toNumber: '+15552222222',
+      task: 'Confirm appointment time',
+    });
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello, I am calling to confirm your appointment.']));
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_setup_greet_123',
+      from: '+15551111111',
+      to: '+15552222222',
+    }));
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string; last?: boolean })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('confirm your appointment'))).toBe(true);
+    expect(textMessages.some((m) => m.last === true)).toBe(true);
+
+    const events = getCallEvents(session.id).filter((e) => e.eventType === 'assistant_spoke');
+    expect(events.length).toBeGreaterThan(0);
+
+    relay.destroy();
+  });
+
   test('handleTransportClosed: normal close marks call completed and notifies completion', () => {
     ensureConversation('conv-relay-close-normal');
     const session = createCallSession({
@@ -235,6 +328,7 @@ describe('relay-server', () => {
     const endedEvents = getCallEvents(session.id).filter((e) => e.eventType === 'call_ended');
     expect(endedEvents.length).toBe(1);
     expect(completionCount).toBe(1);
+    expect(getLatestAssistantText('conv-relay-close-normal')).toContain('**Call completed**');
 
     unregisterCallCompletionNotifier('conv-relay-close-normal');
     relay.destroy();
@@ -259,6 +353,7 @@ describe('relay-server', () => {
     expect(updated!.lastError).toContain('abnormal closure');
     const failEvents = getCallEvents(session.id).filter((e) => e.eventType === 'call_failed');
     expect(failEvents.length).toBe(1);
+    expect(getLatestAssistantText('conv-relay-close-abnormal')).toContain('**Call failed**');
 
     relay.destroy();
   });
@@ -285,8 +380,9 @@ describe('relay-server', () => {
 
     // Verify event recorded with custom parameters
     const events = getCallEvents(session.id);
-    expect(events.length).toBe(1);
-    const payload = JSON.parse(events[0].payloadJson);
+    const connectedEvents = events.filter((e) => e.eventType === 'call_connected');
+    expect(connectedEvents.length).toBe(1);
+    const payload = JSON.parse(connectedEvents[0].payloadJson);
     expect(payload.customParameters).toEqual({ taskId: 'task-1', priority: 'high' });
 
     relay.destroy();
@@ -359,6 +455,9 @@ describe('relay-server', () => {
       to: '+15552222222',
     }));
 
+    // Let any async initial-greeting turn settle so we can compare only
+    // the effect of the partial prompt itself.
+    await new Promise((resolve) => setTimeout(resolve, 10));
     const messagesBeforePrompt = ws.sentMessages.length;
 
     // Send a partial prompt (last=false)
@@ -467,6 +566,58 @@ describe('relay-server', () => {
     relay.destroy();
   });
 
+  test('verification failure remains failed if transport closes during goodbye delay', async () => {
+    ensureConversation('conv-relay-verify-race');
+    ensureConversation('conv-relay-verify-race-initiator');
+    const session = createCallSession({
+      conversationId: 'conv-relay-verify-race',
+      provider: 'twilio',
+      fromNumber: '+15551111111',
+      toNumber: '+15552222222',
+      initiatedFromConversationId: 'conv-relay-verify-race-initiator',
+    });
+
+    mockConfig.calls.verification.enabled = true;
+    mockConfig.calls.verification.maxAttempts = 1;
+    mockConfig.calls.verification.codeLength = 1;
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_verify_race_123',
+      from: '+15551111111',
+      to: '+15552222222',
+    }));
+
+    const verificationCode = relay.getVerificationCode();
+    expect(verificationCode).not.toBeNull();
+    const wrongDigit = verificationCode === '0' ? '1' : '0';
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'dtmf',
+      digit: wrongDigit,
+    }));
+
+    // Simulate the callee hanging up before the delayed endSession executes.
+    relay.handleTransportClosed(1000, 'callee hung up');
+
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('failed');
+    expect(updated!.lastError).toContain('max attempts exceeded');
+    expect(getLatestAssistantText('conv-relay-verify-race')).toContain('**Call failed**');
+
+    // Let the delayed endSession callback flush to avoid timer bleed across tests.
+    await new Promise((resolve) => setTimeout(resolve, 2100));
+
+    const finalState = getCallSession(session.id);
+    expect(finalState).not.toBeNull();
+    expect(finalState!.status).toBe('failed');
+
+    relay.destroy();
+  });
+
   // ── Error handling ──────────────────────────────────────────────
 
   test('handleMessage: error message records call_failed event', async () => {
@@ -685,4 +836,592 @@ describe('relay-server', () => {
     relay.destroy();
     expect(() => relay.destroy()).not.toThrow();
   });
+
+  // ── Inbound call setup ────────────────────────────────────────────
+
+  test('handleMessage: inbound call (no task) triggers greeting without verification', async () => {
+    ensureConversation('conv-relay-inbound-greet');
+    // Inbound sessions have no task and no initiatedFromConversationId
+    const session = createCallSession({
+      conversationId: 'conv-relay-inbound-greet',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      // no task — inbound call
+    });
+
+    // Enable verification to prove inbound calls skip it
+    mockConfig.calls.verification.enabled = true;
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello, how can I help you today?']));
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_inbound_greet_123',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Should NOT have started verification (no verification code prompt)
+    expect(relay.getVerificationCode()).toBeNull();
+
+    // Should have generated a greeting via the orchestrator
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string; last?: boolean })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('how can I help'))).toBe(true);
+    expect(textMessages.some((m) => m.last === true)).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('handleMessage: inbound call persists caller transcript to voice conversation', async () => {
+    ensureConversation('conv-relay-inbound-persist');
+    const session = createCallSession({
+      conversationId: 'conv-relay-inbound-persist',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      // no task — inbound call
+    });
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Sure, let me help with that.']));
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_inbound_persist_123',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    // Wait for initial greeting to settle
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Send a caller utterance
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'I would like to schedule an appointment',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Verify caller transcript is persisted to the voice conversation
+    const userMessages = getMessages('conv-relay-inbound-persist').filter((m) => m.role === 'user');
+    expect(userMessages.length).toBeGreaterThan(0);
+    const lastUserMsg = userMessages[userMessages.length - 1];
+    expect(lastUserMsg.content).toContain('schedule an appointment');
+
+    // Verify assistant response is also persisted
+    const assistantMessages = getMessages('conv-relay-inbound-persist').filter((m) => m.role === 'assistant');
+    expect(assistantMessages.length).toBeGreaterThan(0);
+
+    relay.destroy();
+  });
+
+  test('handleMessage: inbound call supports multi-turn conversation', async () => {
+    ensureConversation('conv-relay-inbound-multi');
+    const session = createCallSession({
+      conversationId: 'conv-relay-inbound-multi',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      // no task — inbound call
+    });
+
+    let turnCount = 0;
+    mockSendMessage.mockImplementation(async (_messages: unknown[], _tools: unknown[], _systemPrompt: unknown, options?: { onEvent?: (event: { type: string; text?: string }) => void }) => {
+      turnCount++;
+      let tokens: string[];
+      if (turnCount === 1) tokens = ['Hello, how can I help you?'];
+      else if (turnCount === 2) tokens = ['Sure, I can help with that.'];
+      else tokens = ['Your appointment is confirmed.'];
+      for (const token of tokens) {
+        options?.onEvent?.({ type: 'text_delta', text: token });
+      }
+      return {
+        content: [{ type: 'text', text: tokens.join('') }],
+        model: 'claude-sonnet-4-20250514',
+        usage: { inputTokens: 100, outputTokens: 50 },
+        stopReason: 'end_turn',
+      };
+    });
+
+    const { ws: _ws, relay } = createMockWs(session.id);
+
+    // Setup
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_inbound_multi_123',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // First caller turn
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'I need to schedule something',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Second caller turn
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'How about next Tuesday?',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Verify conversation history has multiple turns
+    const history = relay.getConversationHistory();
+    expect(history.length).toBe(2);
+    expect(history[0].text).toBe('I need to schedule something');
+    expect(history[1].text).toBe('How about next Tuesday?');
+
+    // Verify LLM was called for each turn (greeting + 2 caller turns)
+    expect(turnCount).toBe(3);
+
+    // Verify events were recorded for both caller utterances
+    const events = getCallEvents(session.id).filter((e) => e.eventType === 'caller_spoke');
+    expect(events.length).toBe(2);
+
+    relay.destroy();
+  });
+
+  // ── Inbound voice guardian verification gate ────────────────────────
+
+  test('inbound guardian verification: DTMF code entry succeeds and starts normal call flow', async () => {
+    ensureConversation('conv-guardian-dtmf-ok');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-dtmf-ok',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+      // no task — inbound call
+    });
+
+    // Create a pending voice guardian challenge
+    const challenge = createVerificationChallenge('test-assistant', 'voice');
+    const secret = challenge.secret;
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello, how can I help you?']));
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_dtmf_ok',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    // Should be in verification-pending state
+    expect(relay.isGuardianVerificationActive()).toBe(true);
+    expect(relay.getConnectionState()).toBe('verification_pending');
+
+    // Verify TTS prompt was sent asking for code
+    const setupMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(setupMessages.some((m) => (m.token ?? '').includes('verification code'))).toBe(true);
+
+    // Enter the correct code via DTMF
+    for (const digit of secret) {
+      await relay.handleMessage(JSON.stringify({ type: 'dtmf', digit }));
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Verification should have succeeded
+    expect(relay.isGuardianVerificationActive()).toBe(false);
+    expect(relay.getConnectionState()).toBe('connected');
+
+    // Guardian binding should have been created
+    const binding = getGuardianBinding('test-assistant', 'voice');
+    expect(binding).not.toBeNull();
+
+    // Orchestrator greeting should have fired
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('how can I help'))).toBe(true);
+
+    // Verify events recorded
+    const guardianEvents = getCallEvents(session.id);
+    expect(guardianEvents.some((e) => e.eventType === 'guardian_voice_verification_started')).toBe(true);
+    expect(guardianEvents.some((e) => e.eventType === 'guardian_voice_verification_succeeded')).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('inbound guardian verification: speech-based code entry succeeds', async () => {
+    ensureConversation('conv-guardian-speech-ok');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-speech-ok',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+    });
+
+    const challenge = createVerificationChallenge('test-assistant', 'voice');
+    const secret = challenge.secret;
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello, verified caller!']));
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_speech_ok',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    expect(relay.isGuardianVerificationActive()).toBe(true);
+
+    // Speak the code as individual digit characters
+    const spokenCode = secret.split('').join(' ');
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: spokenCode,
+      lang: 'en-US',
+      last: true,
+    }));
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Verification should have succeeded
+    expect(relay.isGuardianVerificationActive()).toBe(false);
+    expect(relay.getConnectionState()).toBe('connected');
+
+    // Binding created
+    const binding = getGuardianBinding('test-assistant', 'voice');
+    expect(binding).not.toBeNull();
+
+    // Greeting should have started
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('verified caller'))).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('inbound call: caller matching voice guardian binding is classified as guardian', async () => {
+    ensureConversation('conv-guardian-role-match');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-role-match',
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+    });
+
+    createBinding({
+      assistantId: 'test-assistant',
+      channel: 'voice',
+      guardianExternalUserId: '+15550001111',
+      guardianDeliveryChatId: '+15550001111',
+    });
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello there.']));
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_role_match',
+      from: '+15550001111',
+      to: '+15551111111',
+    }));
+
+    const runtimeContext = (relay.getOrchestrator() as unknown as { guardianContext?: { sourceChannel?: string; actorRole?: string; guardianExternalUserId?: string } })?.guardianContext;
+    expect(runtimeContext?.sourceChannel).toBe('voice');
+    expect(runtimeContext?.actorRole).toBe('guardian');
+    expect(runtimeContext?.guardianExternalUserId).toBe('+15550001111');
+
+    relay.destroy();
+  });
+
+  test('inbound call: caller not matching voice guardian binding is classified as non-guardian', async () => {
+    ensureConversation('conv-guardian-role-mismatch');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-role-mismatch',
+      provider: 'twilio',
+      fromNumber: '+15550002222',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+    });
+
+    createBinding({
+      assistantId: 'test-assistant',
+      channel: 'voice',
+      guardianExternalUserId: '+15550009999',
+      guardianDeliveryChatId: '+15550009999',
+    });
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Hello there.']));
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_role_mismatch',
+      from: '+15550002222',
+      to: '+15551111111',
+    }));
+
+    const runtimeContext = (relay.getOrchestrator() as unknown as {
+      guardianContext?: {
+        sourceChannel?: string;
+        actorRole?: string;
+        guardianExternalUserId?: string;
+        requesterExternalUserId?: string;
+      };
+    })?.guardianContext;
+    expect(runtimeContext?.sourceChannel).toBe('voice');
+    expect(runtimeContext?.actorRole).toBe('non-guardian');
+    expect(runtimeContext?.guardianExternalUserId).toBe('+15550009999');
+    expect(runtimeContext?.requesterExternalUserId).toBe('+15550002222');
+
+    relay.destroy();
+  });
+
+  test('inbound guardian verification updates orchestrator context to guardian', async () => {
+    ensureConversation('conv-guardian-context-upgrade');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-context-upgrade',
+      provider: 'twilio',
+      fromNumber: '+15550003333',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+    });
+
+    const challenge = createVerificationChallenge('test-assistant', 'voice');
+    const spokenCode = challenge.secret.split('').join(' ');
+
+    const { relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_context_upgrade',
+      from: session.fromNumber,
+      to: session.toNumber,
+    }));
+
+    const preVerify = (relay.getOrchestrator() as unknown as {
+      guardianContext?: { actorRole?: string };
+    })?.guardianContext;
+    expect(preVerify?.actorRole).toBe('unverified_channel');
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: spokenCode,
+      lang: 'en-US',
+      last: true,
+    }));
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    const postVerify = (relay.getOrchestrator() as unknown as {
+      guardianContext?: { sourceChannel?: string; actorRole?: string; guardianExternalUserId?: string };
+    })?.guardianContext;
+    expect(postVerify?.sourceChannel).toBe('voice');
+    expect(postVerify?.actorRole).toBe('guardian');
+    expect(postVerify?.guardianExternalUserId).toBe(session.fromNumber);
+
+    relay.destroy();
+  });
+
+  test('inbound guardian verification: invalid code triggers retry prompt', async () => {
+    ensureConversation('conv-guardian-retry');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-retry',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+    });
+
+    createVerificationChallenge('test-assistant', 'voice');
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_retry',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    expect(relay.isGuardianVerificationActive()).toBe(true);
+
+    // Enter a wrong code via DTMF
+    for (const digit of '000000') {
+      await relay.handleMessage(JSON.stringify({ type: 'dtmf', digit }));
+    }
+
+    // Should still be in verification-pending state (retry allowed)
+    expect(relay.isGuardianVerificationActive()).toBe(true);
+    expect(relay.getConnectionState()).toBe('verification_pending');
+
+    // Should have sent a retry prompt
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('incorrect'))).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('inbound guardian verification: max attempts exhaustion terminates call', async () => {
+    ensureConversation('conv-guardian-max-attempts');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-max-attempts',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+    });
+
+    createVerificationChallenge('test-assistant', 'voice');
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_max_attempts',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    expect(relay.isGuardianVerificationActive()).toBe(true);
+
+    // Enter wrong codes 3 times (max attempts = 3)
+    for (let attempt = 0; attempt < 3; attempt++) {
+      for (const digit of '000000') {
+        await relay.handleMessage(JSON.stringify({ type: 'dtmf', digit }));
+      }
+    }
+
+    // Call should be marked as failed
+    const updated = getCallSession(session.id);
+    expect(updated).not.toBeNull();
+    expect(updated!.status).toBe('failed');
+    expect(updated!.lastError).toContain('Guardian voice verification failed');
+
+    // Should have sent goodbye message
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('Verification failed. Goodbye.'))).toBe(true);
+
+    // Verify events
+    const events = getCallEvents(session.id);
+    expect(events.some((e) => e.eventType === 'guardian_voice_verification_failed')).toBe(true);
+
+    // Let the delayed endSession callback flush
+    await new Promise((resolve) => setTimeout(resolve, 2100));
+
+    // Verify end message was sent
+    const endMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string })
+      .filter((m) => m.type === 'end');
+    expect(endMessages.length).toBe(1);
+
+    relay.destroy();
+  });
+
+  test('inbound guardian verification: no pending challenge proceeds with normal flow', async () => {
+    ensureConversation('conv-guardian-no-challenge');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-no-challenge',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+      // no task — inbound call
+    });
+
+    // Do NOT create any pending challenge
+
+    mockSendMessage.mockImplementation(createMockProviderResponse(['Welcome to the line.']));
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_no_challenge',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Should NOT be in guardian verification state
+    expect(relay.isGuardianVerificationActive()).toBe(false);
+    expect(relay.getConnectionState()).toBe('connected');
+
+    // Should have started normal greeting
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('Welcome to the line'))).toBe(true);
+
+    relay.destroy();
+  });
+
+  test('inbound guardian verification: speech with partial digits prompts for more', async () => {
+    ensureConversation('conv-guardian-partial-speech');
+    const session = createCallSession({
+      conversationId: 'conv-guardian-partial-speech',
+      provider: 'twilio',
+      fromNumber: '+15559999999',
+      toNumber: '+15551111111',
+      assistantId: 'test-assistant',
+    });
+
+    createVerificationChallenge('test-assistant', 'voice');
+
+    const { ws, relay } = createMockWs(session.id);
+
+    await relay.handleMessage(JSON.stringify({
+      type: 'setup',
+      callSid: 'CA_guardian_partial_speech',
+      from: '+15559999999',
+      to: '+15551111111',
+    }));
+
+    expect(relay.isGuardianVerificationActive()).toBe(true);
+
+    // Speak only 3 digits
+    await relay.handleMessage(JSON.stringify({
+      type: 'prompt',
+      voicePrompt: 'one two three',
+      lang: 'en-US',
+      last: true,
+    }));
+
+    // Should still be in verification state
+    expect(relay.isGuardianVerificationActive()).toBe(true);
+
+    // Should have prompted for more digits
+    const textMessages = ws.sentMessages
+      .map((raw) => JSON.parse(raw) as { type: string; token?: string })
+      .filter((m) => m.type === 'text');
+    expect(textMessages.some((m) => (m.token ?? '').includes('3 digits'))).toBe(true);
+    expect(textMessages.some((m) => (m.token ?? '').includes('all 6 digits'))).toBe(true);
+
+    relay.destroy();
+  });
 });