@vellumai/assistant 0.3.2 → 0.3.3

package/src/__tests__/handlers-twilio-config.test.ts

@@ -10,8 +10,8 @@ const testDir = mkdtempSync(join(tmpdir(), 'handlers-twilio-cfg-test-'));
 let rawConfigStore: Record<string, unknown> = {};
 
 mock.module('../config/loader.js', () => ({
-  getConfig: () => ({}),
-  loadConfig: () => ({}),
+  getConfig: () => ({ ...rawConfigStore }),
+  loadConfig: () => ({ ...rawConfigStore }),
   loadRawConfig: () => ({ ...rawConfigStore }),
   saveRawConfig: (cfg: Record<string, unknown>) => {
     rawConfigStore = { ...cfg };
@@ -20,6 +20,28 @@ mock.module('../config/loader.js', () => ({
   invalidateConfigCache: () => {},
 }));
 
+// Provide a thin mock of public-ingress-urls that computes real-looking
+// webhook URLs from the raw config store so that both getTwilioConfig()
+// and the syncTwilioWebhooks() helper used by ingress tests work correctly.
+mock.module('../inbound/public-ingress-urls.js', () => {
+  function getBase(config: Record<string, unknown>): string {
+    const ingress = (config?.ingress ?? {}) as Record<string, unknown>;
+    const url = (ingress.publicBaseUrl as string) ?? '';
+    if (!url) throw new Error('No public ingress URL configured');
+    return url;
+  }
+  return {
+    getPublicBaseUrl: (config: Record<string, unknown>) => getBase(config),
+    getTwilioRelayUrl: (config: Record<string, unknown>) => {
+      const base = getBase(config);
+      return base.replace(/^http(s?)/, 'ws$1') + '/webhooks/twilio/relay';
+    },
+    getTwilioVoiceWebhookUrl: (config: Record<string, unknown>) => getBase(config) + '/webhooks/twilio/voice',
+    getTwilioStatusCallbackUrl: (config: Record<string, unknown>) => getBase(config) + '/webhooks/twilio/status',
+    getTwilioSmsWebhookUrl: (config: Record<string, unknown>) => getBase(config) + '/webhooks/twilio/sms',
+  };
+});
+
 mock.module('../util/platform.js', () => ({
   getRootDir: () => testDir,
   getDataDir: () => testDir,
@@ -113,10 +135,12 @@ mock.module('../tools/credentials/metadata-store.js', () => ({
 // Mock fetch for Twilio API validation
 const originalFetch = globalThis.fetch;
 
-import { handleTwilioConfig } from '../daemon/handlers/config.js';
+import { handleTwilioConfig, handleIngressConfig } from '../daemon/handlers/config.js';
+import { getTwilioConfig } from '../calls/twilio-config.js';
 import type { HandlerContext } from '../daemon/handlers.js';
 import type {
   TwilioConfigRequest,
+  IngressConfigRequest,
   ServerMessage,
 } from '../daemon/ipc-contract.js';
 import { DebouncerMap } from '../util/debounce.js';
@@ -382,9 +406,11 @@ describe('Twilio config handler', () => {
 
   // ── clear_credentials ───────────────────────────────────────────────
 
-  test('clear_credentials removes stored credentials', async () => {
+  test('clear_credentials removes stored credentials but preserves phone number', async () => {
     secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
     secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    secureKeyStore['credential:twilio:phone_number'] = '+15551234567';
+    rawConfigStore = { sms: { phoneNumber: '+15551234567' } };
     credentialMetadataStore.push({ service: 'twilio', field: 'account_sid' });
     credentialMetadataStore.push({ service: 'twilio', field: 'auth_token' });
 
@@ -402,11 +428,15 @@ describe('Twilio config handler', () => {
     expect(res.success).toBe(true);
     expect(res.hasCredentials).toBe(false);
 
-    // Verify everything was cleaned up
+    // Verify auth credentials were cleaned up
     expect(secureKeyStore['credential:twilio:account_sid']).toBeUndefined();
     expect(secureKeyStore['credential:twilio:auth_token']).toBeUndefined();
     expect(deletedMetadata).toContainEqual({ service: 'twilio', field: 'account_sid' });
     expect(deletedMetadata).toContainEqual({ service: 'twilio', field: 'auth_token' });
+
+    // Verify phone number is preserved in both stores
+    expect(secureKeyStore['credential:twilio:phone_number']).toBe('+15551234567');
+    expect((rawConfigStore.sms as Record<string, unknown>)?.phoneNumber).toBe('+15551234567');
   });
 
   test('clear_credentials is idempotent when no credentials exist', async () => {
@@ -424,6 +454,75 @@ describe('Twilio config handler', () => {
     expect(res.hasCredentials).toBe(false);
   });
 
+  // ── Phone number resolution order ──────────────────────────────────
+
+  test('getTwilioConfig resolves phone number from config when secure key also present', () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    secureKeyStore['credential:twilio:phone_number'] = '+15559999999';
+    rawConfigStore = {
+      sms: { phoneNumber: '+15551234567' },
+      ingress: { enabled: true, publicBaseUrl: 'https://test.ngrok.io' },
+    };
+
+    // Clean env var to test config-only resolution
+    const savedEnv = process.env.TWILIO_PHONE_NUMBER;
+    delete process.env.TWILIO_PHONE_NUMBER;
+
+    try {
+      const config = getTwilioConfig();
+      // Config value (+15551234567) should take priority over secure key (+15559999999)
+      expect(config.phoneNumber).toBe('+15551234567');
+    } finally {
+      if (savedEnv !== undefined) process.env.TWILIO_PHONE_NUMBER = savedEnv;
+    }
+  });
+
+  test('getTwilioConfig falls back to secure key when config has no phone number', () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    secureKeyStore['credential:twilio:phone_number'] = '+15559999999';
+    rawConfigStore = {
+      ingress: { enabled: true, publicBaseUrl: 'https://test.ngrok.io' },
+    };
+
+    const savedEnv = process.env.TWILIO_PHONE_NUMBER;
+    delete process.env.TWILIO_PHONE_NUMBER;
+
+    try {
+      const config = getTwilioConfig();
+      // Secure key should be used as fallback
+      expect(config.phoneNumber).toBe('+15559999999');
+    } finally {
+      if (savedEnv !== undefined) process.env.TWILIO_PHONE_NUMBER = savedEnv;
+    }
+  });
+
+  test('getTwilioConfig env var overrides both config and secure key', () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    secureKeyStore['credential:twilio:phone_number'] = '+15559999999';
+    rawConfigStore = {
+      sms: { phoneNumber: '+15551234567' },
+      ingress: { enabled: true, publicBaseUrl: 'https://test.ngrok.io' },
+    };
+
+    const savedEnv = process.env.TWILIO_PHONE_NUMBER;
+    process.env.TWILIO_PHONE_NUMBER = '+15550000000';
+
+    try {
+      const config = getTwilioConfig();
+      // Env var should take highest priority
+      expect(config.phoneNumber).toBe('+15550000000');
+    } finally {
+      if (savedEnv !== undefined) {
+        process.env.TWILIO_PHONE_NUMBER = savedEnv;
+      } else {
+        delete process.env.TWILIO_PHONE_NUMBER;
+      }
+    }
+  });
+
   // ── assign_number ───────────────────────────────────────────────────
 
   test('assign_number persists phone number to config', async () => {
@@ -573,6 +672,169 @@ describe('Twilio config handler', () => {
     expect(res.phoneNumber).toBe('+15559999999');
   });
 
+  test('provision_number auto-assigns the purchased number to config and secure storage', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      if (urlStr.includes('AvailablePhoneNumbers') && urlStr.includes('Local.json')) {
+        return new Response(JSON.stringify({
+          available_phone_numbers: [{
+            phone_number: '+15559999999',
+            friendly_name: '(555) 999-9999',
+            capabilities: { voice: true, sms: true },
+          }],
+        }), { status: 200 });
+      }
+      if (urlStr.includes('IncomingPhoneNumbers.json') && init?.method === 'POST') {
+        return new Response(JSON.stringify({
+          phone_number: '+15559999999',
+          friendly_name: '(555) 999-9999',
+          capabilities: { voice: true, sms: true },
+        }), { status: 201 });
+      }
+      // Webhook lookup (no ingress configured, will fail gracefully)
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'provision_number',
+      country: 'US',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string };
+    expect(res.success).toBe(true);
+    expect(res.phoneNumber).toBe('+15559999999');
+
+    // Verify the number was persisted in secure storage (same as assign_number)
+    expect(secureKeyStore['credential:twilio:phone_number']).toBe('+15559999999');
+
+    // Verify the number was persisted in the config file (same as assign_number)
+    expect((rawConfigStore.sms as Record<string, unknown>)?.phoneNumber).toBe('+15559999999');
+  });
+
+  test('provision_number configures Twilio webhooks when ingress URL is available', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    rawConfigStore = { ingress: { enabled: true, publicBaseUrl: 'https://example.ngrok.io' } };
+
+    const fetchCalls: Array<{ url: string; method: string; body?: string }> = [];
+
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      fetchCalls.push({ url: urlStr, method: init?.method ?? 'GET', body: init?.body?.toString() });
+
+      if (urlStr.includes('AvailablePhoneNumbers') && urlStr.includes('Local.json')) {
+        return new Response(JSON.stringify({
+          available_phone_numbers: [{
+            phone_number: '+15559999999',
+            friendly_name: '(555) 999-9999',
+            capabilities: { voice: true, sms: true },
+          }],
+        }), { status: 200 });
+      }
+      if (urlStr.includes('IncomingPhoneNumbers.json') && init?.method === 'POST'
+          && init?.body?.toString().includes('PhoneNumber')) {
+        return new Response(JSON.stringify({
+          phone_number: '+15559999999',
+          friendly_name: '(555) 999-9999',
+          capabilities: { voice: true, sms: true },
+        }), { status: 201 });
+      }
+      // Webhook number lookup
+      if (urlStr.includes('IncomingPhoneNumbers.json') && urlStr.includes('PhoneNumber=')) {
+        return new Response(JSON.stringify({
+          incoming_phone_numbers: [{ sid: 'PN123abc', phone_number: '+15559999999' }],
+        }), { status: 200 });
+      }
+      // Webhook update
+      if (urlStr.includes('IncomingPhoneNumbers/PN123abc.json') && init?.method === 'POST') {
+        return new Response(JSON.stringify({ sid: 'PN123abc' }), { status: 200 });
+      }
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'provision_number',
+      country: 'US',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean };
+    expect(res.success).toBe(true);
+
+    // Find the webhook update call
+    const webhookUpdate = fetchCalls.find((c) =>
+      c.url.includes('IncomingPhoneNumbers/PN123abc.json') && c.method === 'POST',
+    );
+    expect(webhookUpdate).toBeDefined();
+
+    // Verify the webhook URLs contain the expected ingress base URL paths
+    const body = webhookUpdate!.body!;
+    expect(body).toContain('VoiceUrl=');
+    expect(body).toContain('webhooks%2Ftwilio%2Fvoice');
+    expect(body).toContain('StatusCallback=');
+    expect(body).toContain('webhooks%2Ftwilio%2Fstatus');
+    expect(body).toContain('SmsUrl=');
+    expect(body).toContain('webhooks%2Ftwilio%2Fsms');
+  });
+
+  test('provision_number succeeds with clear warning when ingress URL is missing', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    // No ingress config — webhook configuration will be skipped gracefully
+
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      if (urlStr.includes('AvailablePhoneNumbers') && urlStr.includes('Local.json')) {
+        return new Response(JSON.stringify({
+          available_phone_numbers: [{
+            phone_number: '+15559999999',
+            friendly_name: '(555) 999-9999',
+            capabilities: { voice: true, sms: true },
+          }],
+        }), { status: 200 });
+      }
+      if (urlStr.includes('IncomingPhoneNumbers.json') && init?.method === 'POST') {
+        return new Response(JSON.stringify({
+          phone_number: '+15559999999',
+          friendly_name: '(555) 999-9999',
+          capabilities: { voice: true, sms: true },
+        }), { status: 201 });
+      }
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'provision_number',
+      country: 'US',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    // The provision should still succeed — webhook config failure is non-fatal
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string };
+    expect(res.success).toBe(true);
+    expect(res.phoneNumber).toBe('+15559999999');
+
+    // Number should still be persisted even without webhook setup
+    expect(secureKeyStore['credential:twilio:phone_number']).toBe('+15559999999');
+    expect((rawConfigStore.sms as Record<string, unknown>)?.phoneNumber).toBe('+15559999999');
+  });
+
   test('provision_number returns error when no numbers available', async () => {
     secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
     secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
@@ -635,6 +897,404 @@ describe('Twilio config handler', () => {
     expect(res.error).toContain('nonexistent_action');
   });
 
+  // ── Ingress webhook reconciliation ──────────────────────────────────
+
+  test('ingress config update triggers Twilio webhook sync when assigned number and credentials exist', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    rawConfigStore = { sms: { phoneNumber: '+15551234567' } };
+
+    const fetchCalls: Array<{ url: string; method: string; body?: string }> = [];
+
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      fetchCalls.push({ url: urlStr, method: init?.method ?? 'GET', body: init?.body?.toString() });
+
+      // Webhook number lookup
+      if (urlStr.includes('IncomingPhoneNumbers.json') && urlStr.includes('PhoneNumber=')) {
+        return new Response(JSON.stringify({
+          incoming_phone_numbers: [{ sid: 'PN123abc', phone_number: '+15551234567' }],
+        }), { status: 200 });
+      }
+      // Webhook update
+      if (urlStr.includes('IncomingPhoneNumbers/PN123abc.json') && init?.method === 'POST') {
+        return new Response(JSON.stringify({ sid: 'PN123abc' }), { status: 200 });
+      }
+      // Gateway reconcile (ignore)
+      if (urlStr.includes('/internal/telegram/reconcile')) {
+        return new Response('{}', { status: 200 });
+      }
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: IngressConfigRequest = {
+      type: 'ingress_config',
+      action: 'set',
+      publicBaseUrl: 'https://new-tunnel.ngrok.io',
+      enabled: true,
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleIngressConfig(msg, {} as net.Socket, ctx);
+
+    // Ingress save should succeed
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; enabled: boolean; publicBaseUrl: string };
+    expect(res.type).toBe('ingress_config_response');
+    expect(res.success).toBe(true);
+    expect(res.enabled).toBe(true);
+    expect(res.publicBaseUrl).toBe('https://new-tunnel.ngrok.io');
+
+    // Wait a tick for the fire-and-forget webhook sync to complete
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify webhook update was attempted with the new ingress URL
+    const webhookUpdate = fetchCalls.find((c) =>
+      c.url.includes('IncomingPhoneNumbers/PN123abc.json') && c.method === 'POST',
+    );
+    expect(webhookUpdate).toBeDefined();
+    const body = webhookUpdate!.body!;
+    expect(body).toContain('VoiceUrl=');
+    expect(body).toContain('new-tunnel.ngrok.io');
+  });
+
+  test('webhook sync failure on ingress update does not fail the ingress update', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    rawConfigStore = { sms: { phoneNumber: '+15551234567' } };
+
+    globalThis.fetch = (async (url: string | URL | Request, _init?: RequestInit) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      // Gateway reconcile (ignore)
+      if (urlStr.includes('/internal/telegram/reconcile')) {
+        return new Response('{}', { status: 200 });
+      }
+      // Webhook number lookup — simulate failure
+      if (urlStr.includes('IncomingPhoneNumbers.json') && urlStr.includes('PhoneNumber=')) {
+        return new Response('Internal Server Error', { status: 500 });
+      }
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: IngressConfigRequest = {
+      type: 'ingress_config',
+      action: 'set',
+      publicBaseUrl: 'https://example.ngrok.io',
+      enabled: true,
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleIngressConfig(msg, {} as net.Socket, ctx);
+
+    // The ingress update must still succeed despite the webhook sync failure
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; enabled: boolean };
+    expect(res.type).toBe('ingress_config_response');
+    expect(res.success).toBe(true);
+    expect(res.enabled).toBe(true);
+
+    // Wait a tick for the fire-and-forget promise
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('ingress config update skips webhook sync when no Twilio credentials', async () => {
+    rawConfigStore = { sms: { phoneNumber: '+15551234567' } };
+
+    const fetchCalls: Array<{ url: string }> = [];
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      fetchCalls.push({ url: urlStr });
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: IngressConfigRequest = {
+      type: 'ingress_config',
+      action: 'set',
+      publicBaseUrl: 'https://example.ngrok.io',
+      enabled: true,
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleIngressConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean };
+    expect(res.success).toBe(true);
+
+    // No Twilio API calls should have been made (only gateway reconcile)
+    const twilioApiCalls = fetchCalls.filter((c) => c.url.includes('api.twilio.com'));
+    expect(twilioApiCalls).toHaveLength(0);
+  });
+
+  test('ingress config update skips webhook sync when no assigned number', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    // No sms.phoneNumber in config
+
+    const fetchCalls: Array<{ url: string }> = [];
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      fetchCalls.push({ url: urlStr });
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: IngressConfigRequest = {
+      type: 'ingress_config',
+      action: 'set',
+      publicBaseUrl: 'https://example.ngrok.io',
+      enabled: true,
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleIngressConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean };
+    expect(res.success).toBe(true);
+
+    // No Twilio API calls should have been made
+    const twilioApiCalls = fetchCalls.filter((c) => c.url.includes('api.twilio.com'));
+    expect(twilioApiCalls).toHaveLength(0);
+  });
+
+  // ── Warning field ─────────────────────────────────────────────────
+
+  test('provision_number surfaces webhook warning when ingress is missing', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    // No ingress config — webhook configuration will produce a warning
+
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      if (urlStr.includes('AvailablePhoneNumbers') && urlStr.includes('Local.json')) {
+        return new Response(JSON.stringify({
+          available_phone_numbers: [{
+            phone_number: '+15559999999',
+            friendly_name: '(555) 999-9999',
+            capabilities: { voice: true, sms: true },
+          }],
+        }), { status: 200 });
+      }
+      if (urlStr.includes('IncomingPhoneNumbers.json') && init?.method === 'POST') {
+        return new Response(JSON.stringify({
+          phone_number: '+15559999999',
+          friendly_name: '(555) 999-9999',
+          capabilities: { voice: true, sms: true },
+        }), { status: 201 });
+      }
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'provision_number',
+      country: 'US',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string; warning?: string };
+    expect(res.success).toBe(true);
+    expect(res.phoneNumber).toBe('+15559999999');
+    // Warning should be present because no ingress URL is configured
+    expect(res.warning).toBeDefined();
+    expect(res.warning).toContain('Webhook configuration skipped');
+  });
+
+  test('assign_number surfaces webhook warning when Twilio API fails', async () => {
+    secureKeyStore['credential:twilio:account_sid'] = 'AC1234567890abcdef1234567890abcdef';
+    secureKeyStore['credential:twilio:auth_token'] = 'test_auth_token';
+    rawConfigStore = { ingress: { enabled: true, publicBaseUrl: 'https://example.ngrok.io' } };
+
+    globalThis.fetch = (async (url: string | URL | Request) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+      // Webhook number lookup — simulate Twilio API error
+      if (urlStr.includes('IncomingPhoneNumbers.json')) {
+        return new Response('Service Unavailable', { status: 503 });
+      }
+      return new Response('{}', { status: 200 });
+    }) as typeof fetch;
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'assign_number',
+      phoneNumber: '+15551234567',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string; warning?: string };
+    // Assignment itself succeeds
+    expect(res.success).toBe(true);
+    expect(res.phoneNumber).toBe('+15551234567');
+    // Warning should surface the webhook failure
+    expect(res.warning).toBeDefined();
+    expect(res.warning).toContain('Webhook configuration skipped');
+  });
+
+  // ── Assistant-scoped phone number assignment ─────────────────────────
+
+  test('get action with assistantId returns assistant-specific phone number', async () => {
+    rawConfigStore = {
+      sms: {
+        phoneNumber: '+15551111111',
+        assistantPhoneNumbers: { 'ast-alpha': '+15552222222', 'ast-beta': '+15553333333' },
+      },
+    };
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'get',
+      assistantId: 'ast-alpha',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string };
+    expect(res.success).toBe(true);
+    // Should return the assistant-specific number, not the legacy one
+    expect(res.phoneNumber).toBe('+15552222222');
+  });
+
+  test('get action with assistantId falls back to legacy phoneNumber when no mapping exists', async () => {
+    rawConfigStore = {
+      sms: { phoneNumber: '+15551111111' },
+    };
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'get',
+      assistantId: 'ast-unknown',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string };
+    expect(res.success).toBe(true);
+    // Should fall back to the legacy phoneNumber
+    expect(res.phoneNumber).toBe('+15551111111');
+  });
+
+  test('assign_number with assistantId persists into assistantPhoneNumbers mapping', async () => {
+    rawConfigStore = { sms: { phoneNumber: '+15551111111' } };
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'assign_number',
+      phoneNumber: '+15554444444',
+      assistantId: 'ast-gamma',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string };
+    expect(res.success).toBe(true);
+    expect(res.phoneNumber).toBe('+15554444444');
+
+    // Legacy field should NOT be overwritten when assistantId is provided
+    // and the field already has a value — prevents multi-assistant clobbering
+    const sms = rawConfigStore.sms as Record<string, unknown>;
+    expect(sms.phoneNumber).toBe('+15551111111');
+
+    // Per-assistant mapping should contain the new assignment
+    const mapping = sms.assistantPhoneNumbers as Record<string, string>;
+    expect(mapping['ast-gamma']).toBe('+15554444444');
+  });
+
+  test('assign_number with assistantId sets legacy phoneNumber as fallback when empty', async () => {
+    rawConfigStore = { sms: {} };
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'assign_number',
+      phoneNumber: '+15554444444',
+      assistantId: 'ast-gamma',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string };
+    expect(res.success).toBe(true);
+    expect(res.phoneNumber).toBe('+15554444444');
+
+    // When no legacy phoneNumber exists, the first assistant assignment sets it as fallback
+    const sms = rawConfigStore.sms as Record<string, unknown>;
+    expect(sms.phoneNumber).toBe('+15554444444');
+
+    // Per-assistant mapping should contain the new assignment
+    const mapping = sms.assistantPhoneNumbers as Record<string, string>;
+    expect(mapping['ast-gamma']).toBe('+15554444444');
+  });
+
+  test('assign_number with assistantId does not clobber existing global phoneNumber', async () => {
+    // Simulate a multi-assistant scenario: assistant alpha already has a number assigned
+    rawConfigStore = {
+      sms: {
+        phoneNumber: '+15551111111',
+        assistantPhoneNumbers: { 'ast-alpha': '+15551111111' },
+      },
+    };
+
+    // Now assign a different number to assistant beta
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'assign_number',
+      phoneNumber: '+15552222222',
+      assistantId: 'ast-beta',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean; phoneNumber?: string };
+    expect(res.success).toBe(true);
+    expect(res.phoneNumber).toBe('+15552222222');
+
+    const sms = rawConfigStore.sms as Record<string, unknown>;
+    // The global phoneNumber should still be alpha's number, NOT beta's
+    expect(sms.phoneNumber).toBe('+15551111111');
+
+    // Both assistant mappings should be intact
+    const mapping = sms.assistantPhoneNumbers as Record<string, string>;
+    expect(mapping['ast-alpha']).toBe('+15551111111');
+    expect(mapping['ast-beta']).toBe('+15552222222');
+  });
+
+  test('assign_number without assistantId does not write assistantPhoneNumbers', async () => {
+    rawConfigStore = { sms: {} };
+
+    const msg: TwilioConfigRequest = {
+      type: 'twilio_config',
+      action: 'assign_number',
+      phoneNumber: '+15555555555',
+    };
+
+    const { ctx, sent } = createTestContext();
+    await handleTwilioConfig(msg, {} as net.Socket, ctx);
+
+    expect(sent).toHaveLength(1);
+    const res = sent[0] as { type: string; success: boolean };
+    expect(res.success).toBe(true);
+
+    const sms = rawConfigStore.sms as Record<string, unknown>;
+    expect(sms.phoneNumber).toBe('+15555555555');
+    // No assistantPhoneNumbers should have been created
+    expect(sms.assistantPhoneNumbers).toBeUndefined();
+  });
+
   // ── Security ────────────────────────────────────────────────────────
 
   test('response messages never contain raw credential values', async () => {