@vellumai/assistant 0.3.3 → 0.3.5

package/src/daemon/handlers/config.ts

@@ -4,14 +4,18 @@ import { initializeProviders } from '../../providers/registry.js';
 import { addRule, removeRule, updateRule, getAllRules, acceptStarterBundle } from '../../permissions/trust-store.js';
 import { classifyRisk, check, generateAllowlistOptions, generateScopeOptions } from '../../permissions/checker.js';
 import { isSideEffectTool } from '../../tools/executor.js';
-import { resolveExecutionTarget } from '../../tools/execution-target.js';
-import { getAllTools } from '../../tools/registry.js';
+import { resolveExecutionTarget, type ManifestOverride } from '../../tools/execution-target.js';
+import { getAllTools, getTool } from '../../tools/registry.js';
+import { loadSkillCatalog } from '../../config/skills.js';
+import { parseToolManifestFile } from '../../skills/tool-manifest.js';
+import { join } from 'node:path';
 import { listSchedules, updateSchedule, deleteSchedule, describeCronExpression } from '../../schedule/schedule-store.js';
 import { listReminders, cancelReminder } from '../../tools/reminder/reminder-store.js';
 import { getSecureKey, setSecureKey, deleteSecureKey } from '../../security/secure-keys.js';
 import { upsertCredentialMetadata, deleteCredentialMetadata, getCredentialMetadata } from '../../tools/credentials/metadata-store.js';
 import { postToSlackWebhook } from '../../slack/slack-webhook.js';
 import { getApp } from '../../memory/app-store.js';
+import * as externalConversationStore from '../../memory/external-conversation-store.js';
 import { readHttpToken } from '../../util/platform.js';
 import type {
   ModelSetRequest,
@@ -29,6 +33,7 @@ import type {
   TwitterIntegrationConfigRequest,
   TelegramConfigRequest,
   TwilioConfigRequest,
+  ChannelReadinessRequest,
   GuardianVerificationRequest,
   ToolPermissionSimulateRequest,
 } from '../ipc-protocol.js';
@@ -38,6 +43,14 @@ import {
   searchAvailableNumbers,
   provisionPhoneNumber,
   updatePhoneNumberWebhooks,
+  getTollFreeVerificationStatus,
+  submitTollFreeVerification,
+  updateTollFreeVerification,
+  deleteTollFreeVerification,
+  getPhoneNumberSid,
+  releasePhoneNumber,
+  fetchMessageStatus,
+  type TollFreeVerificationSubmitParams,
 } from '../../calls/twilio-rest.js';
 import {
   getTwilioVoiceWebhookUrl,
@@ -46,6 +59,7 @@ import {
   type IngressConfig,
 } from '../../inbound/public-ingress-urls.js';
 import { createVerificationChallenge, getGuardianBinding, revokeBinding as revokeGuardianBinding } from '../../runtime/channel-guardian-service.js';
+import { createReadinessService, type ChannelReadinessService } from '../../runtime/channel-readiness-service.js';
 import { log, CONFIG_RELOAD_DEBOUNCE_MS, defineHandlers, type HandlerContext } from './shared.js';
 import { MODEL_TO_PROVIDER } from '../session-slash.js';
 
@@ -406,7 +420,7 @@ export async function handleShareToSlack(
       ctx.send(socket, {
         type: 'share_to_slack_response',
         success: false,
-        error: 'No Slack webhook URL configured. Set one in Settings.',
+        error: 'No Slack webhook URL configured. Provide one here in the chat, or set it from the Settings page.',
       });
       return;
     }
@@ -628,20 +642,36 @@ export async function handleIngressConfig(
       triggerGatewayReconcile(effectiveUrl);
 
       // Best-effort Twilio webhook reconciliation: when ingress is being
-      // enabled/updated and a Twilio number is assigned with valid credentials,
+      // enabled/updated and Twilio numbers are assigned with valid credentials,
       // push the new webhook URLs to Twilio so calls and SMS route correctly.
       if (isEnabled && hasTwilioCredentials()) {
         const currentConfig = loadRawConfig();
         const smsConfig = (currentConfig?.sms ?? {}) as Record<string, unknown>;
-        const assignedNumber = (smsConfig.phoneNumber as string) ?? '';
-        if (assignedNumber) {
+        const assignedNumbers = new Set<string>();
+        const legacyNumber = (smsConfig.phoneNumber as string) ?? '';
+        if (legacyNumber) assignedNumbers.add(legacyNumber);
+
+        const assistantPhoneNumbers = smsConfig.assistantPhoneNumbers;
+        if (assistantPhoneNumbers && typeof assistantPhoneNumbers === 'object' && !Array.isArray(assistantPhoneNumbers)) {
+          for (const number of Object.values(assistantPhoneNumbers as Record<string, unknown>)) {
+            if (typeof number === 'string' && number) {
+              assignedNumbers.add(number);
+            }
+          }
+        }
+
+        if (assignedNumbers.size > 0) {
           const acctSid = getSecureKey('credential:twilio:account_sid')!;
           const acctToken = getSecureKey('credential:twilio:auth_token')!;
-          // Fire-and-forget: webhook sync failure must not block the ingress save
-          syncTwilioWebhooks(assignedNumber, acctSid, acctToken, currentConfig as IngressConfig)
-            .catch(() => {
-              // Already logged inside syncTwilioWebhooks
-            });
+          // Fire-and-forget: webhook sync failure must not block the ingress save.
+          // Reconcile every assigned number so assistant-scoped mappings do not
+          // retain stale Twilio webhook URLs after ingress URL changes.
+          for (const assignedNumber of assignedNumbers) {
+            syncTwilioWebhooks(assignedNumber, acctSid, acctToken, currentConfig as IngressConfig)
+              .catch(() => {
+                // Already logged inside syncTwilioWebhooks
+              });
+          }
         }
       }
     } else {
@@ -1159,6 +1189,32 @@ export async function handleTelegramConfig(
   }
 }
 
+/** In-memory store for the last SMS send test result. Shared between sms_send_test and sms_doctor. */
+let _lastTestResult: {
+  messageSid: string;
+  to: string;
+  initialStatus: string;
+  finalStatus: string;
+  errorCode?: string;
+  errorMessage?: string;
+  timestamp: number;
+} | undefined;
+
+/** Map a Twilio error code to a human-readable remediation suggestion. */
+function mapTwilioErrorRemediation(errorCode: string | undefined): string | undefined {
+  if (!errorCode) return undefined;
+  const map: Record<string, string> = {
+    '30003': 'Unreachable destination. The handset may be off or out of service.',
+    '30004': 'Message blocked by carrier or recipient.',
+    '30005': 'Unknown destination phone number. Verify the number is valid.',
+    '30006': 'Landline or unreachable carrier. SMS cannot be delivered to this number.',
+    '30007': 'Message flagged as spam by carrier. Adjust content or register for A2P.',
+    '30008': 'Unknown error from the carrier network.',
+    '21610': 'Recipient has opted out (STOP). Cannot send until they opt back in.',
+  };
+  return map[errorCode];
+}
+
 export async function handleTwilioConfig(
   msg: TwilioConfigRequest,
   socket: net.Socket,
@@ -1459,6 +1515,608 @@ export async function handleTwilioConfig(
         hasCredentials: true,
         numbers,
       });
+    } else if (msg.action === 'sms_compliance_status') {
+      if (!hasTwilioCredentials()) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: false,
+          error: 'Twilio credentials not configured. Set credentials first.',
+        });
+        return;
+      }
+
+      const raw = loadRawConfig();
+      const sms = (raw?.sms ?? {}) as Record<string, unknown>;
+      let phoneNumber: string;
+      if (msg.assistantId) {
+        const mapping = (sms.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
+        phoneNumber = mapping[msg.assistantId] ?? (sms.phoneNumber as string) ?? '';
+      } else {
+        phoneNumber = (sms.phoneNumber as string) ?? '';
+      }
+
+      if (!phoneNumber) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: 'No phone number assigned. Assign a number first.',
+        });
+        return;
+      }
+
+      const accountSid = getSecureKey('credential:twilio:account_sid')!;
+      const authToken = getSecureKey('credential:twilio:auth_token')!;
+
+      // Determine number type from prefix
+      const tollFreePrefixes = ['+1800', '+1833', '+1844', '+1855', '+1866', '+1877', '+1888'];
+      const isTollFree = tollFreePrefixes.some((prefix) => phoneNumber.startsWith(prefix));
+      const numberType = isTollFree ? 'toll_free' : 'local_10dlc';
+
+      if (!isTollFree) {
+        // Non-toll-free numbers don't need toll-free verification
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: true,
+          hasCredentials: true,
+          phoneNumber,
+          compliance: { numberType },
+        });
+        return;
+      }
+
+      // Look up the phone number SID and check verification status
+      const phoneSid = await getPhoneNumberSid(accountSid, authToken, phoneNumber);
+      if (!phoneSid) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          phoneNumber,
+          error: `Phone number ${phoneNumber} not found on Twilio account`,
+        });
+        return;
+      }
+
+      const verification = await getTollFreeVerificationStatus(accountSid, authToken, phoneSid);
+
+      ctx.send(socket, {
+        type: 'twilio_config_response',
+        success: true,
+        hasCredentials: true,
+        phoneNumber,
+        compliance: {
+          numberType,
+          verificationSid: verification?.sid,
+          verificationStatus: verification?.status,
+          rejectionReason: verification?.rejectionReason,
+          rejectionReasons: verification?.rejectionReasons,
+          errorCode: verification?.errorCode,
+          editAllowed: verification?.editAllowed,
+          editExpiration: verification?.editExpiration,
+        },
+      });
+    } else if (msg.action === 'sms_submit_tollfree_verification') {
+      if (!hasTwilioCredentials()) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: false,
+          error: 'Twilio credentials not configured. Set credentials first.',
+        });
+        return;
+      }
+
+      const vp = msg.verificationParams;
+      if (!vp) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: 'verificationParams is required for sms_submit_tollfree_verification action',
+        });
+        return;
+      }
+
+      // Validate required fields
+      const requiredFields: Array<[string, unknown]> = [
+        ['tollfreePhoneNumberSid', vp.tollfreePhoneNumberSid],
+        ['businessName', vp.businessName],
+        ['businessWebsite', vp.businessWebsite],
+        ['notificationEmail', vp.notificationEmail],
+        ['useCaseCategories', vp.useCaseCategories],
+        ['useCaseSummary', vp.useCaseSummary],
+        ['productionMessageSample', vp.productionMessageSample],
+        ['optInImageUrls', vp.optInImageUrls],
+        ['optInType', vp.optInType],
+        ['messageVolume', vp.messageVolume],
+      ];
+
+      const missing = requiredFields
+        .filter(([, v]) => v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0))
+        .map(([name]) => name);
+
+      if (missing.length > 0) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: `Missing required verification fields: ${missing.join(', ')}`,
+        });
+        return;
+      }
+
+      // Validate enum values
+      const validUseCaseCategories = [
+        'TWO_FACTOR_AUTHENTICATION', 'ACCOUNT_NOTIFICATION', 'CUSTOMER_CARE',
+        'DELIVERY_NOTIFICATION', 'FRAUD_ALERT', 'HIGHER_EDUCATION', 'MARKETING',
+        'POLLING_AND_VOTING', 'PUBLIC_SERVICE_ANNOUNCEMENT', 'SECURITY_ALERT',
+      ];
+      const invalidCategories = (vp.useCaseCategories ?? []).filter((c) => !validUseCaseCategories.includes(c));
+      if (invalidCategories.length > 0) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: `Invalid useCaseCategories: ${invalidCategories.join(', ')}. Valid values: ${validUseCaseCategories.join(', ')}`,
+        });
+        return;
+      }
+
+      const validOptInTypes = ['VERBAL', 'WEB_FORM', 'PAPER_FORM', 'VIA_TEXT', 'MOBILE_QR_CODE'];
+      if (!validOptInTypes.includes(vp.optInType!)) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: `Invalid optInType: ${vp.optInType}. Valid values: ${validOptInTypes.join(', ')}`,
+        });
+        return;
+      }
+
+      const validMessageVolumes = [
+        '10', '100', '1,000', '10,000', '100,000', '250,000',
+        '500,000', '750,000', '1,000,000', '5,000,000', '10,000,000+',
+      ];
+      if (!validMessageVolumes.includes(vp.messageVolume!)) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: `Invalid messageVolume: ${vp.messageVolume}. Valid values: ${validMessageVolumes.join(', ')}`,
+        });
+        return;
+      }
+
+      const accountSid = getSecureKey('credential:twilio:account_sid')!;
+      const authToken = getSecureKey('credential:twilio:auth_token')!;
+
+      const submitParams: TollFreeVerificationSubmitParams = {
+        tollfreePhoneNumberSid: vp.tollfreePhoneNumberSid!,
+        businessName: vp.businessName!,
+        businessWebsite: vp.businessWebsite!,
+        notificationEmail: vp.notificationEmail!,
+        useCaseCategories: vp.useCaseCategories!,
+        useCaseSummary: vp.useCaseSummary!,
+        productionMessageSample: vp.productionMessageSample!,
+        optInImageUrls: vp.optInImageUrls!,
+        optInType: vp.optInType!,
+        messageVolume: vp.messageVolume!,
+        businessType: vp.businessType ?? 'SOLE_PROPRIETOR',
+        customerProfileSid: vp.customerProfileSid,
+      };
+
+      const verification = await submitTollFreeVerification(accountSid, authToken, submitParams);
+
+      ctx.send(socket, {
+        type: 'twilio_config_response',
+        success: true,
+        hasCredentials: true,
+        compliance: {
+          numberType: 'toll_free',
+          verificationSid: verification.sid,
+          verificationStatus: verification.status,
+        },
+      });
+    } else if (msg.action === 'sms_update_tollfree_verification') {
+      if (!hasTwilioCredentials()) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: false,
+          error: 'Twilio credentials not configured. Set credentials first.',
+        });
+        return;
+      }
+
+      if (!msg.verificationSid) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: 'verificationSid is required for sms_update_tollfree_verification action',
+        });
+        return;
+      }
+
+      const accountSid = getSecureKey('credential:twilio:account_sid')!;
+      const authToken = getSecureKey('credential:twilio:auth_token')!;
+
+      const verification = await updateTollFreeVerification(
+        accountSid,
+        authToken,
+        msg.verificationSid,
+        msg.verificationParams ?? {},
+      );
+
+      ctx.send(socket, {
+        type: 'twilio_config_response',
+        success: true,
+        hasCredentials: true,
+        compliance: {
+          numberType: 'toll_free',
+          verificationSid: verification.sid,
+          verificationStatus: verification.status,
+          editAllowed: verification.editAllowed,
+          editExpiration: verification.editExpiration,
+        },
+      });
+    } else if (msg.action === 'sms_delete_tollfree_verification') {
+      if (!hasTwilioCredentials()) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: false,
+          error: 'Twilio credentials not configured. Set credentials first.',
+        });
+        return;
+      }
+
+      if (!msg.verificationSid) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: 'verificationSid is required for sms_delete_tollfree_verification action',
+        });
+        return;
+      }
+
+      const accountSid = getSecureKey('credential:twilio:account_sid')!;
+      const authToken = getSecureKey('credential:twilio:auth_token')!;
+
+      await deleteTollFreeVerification(accountSid, authToken, msg.verificationSid);
+
+      ctx.send(socket, {
+        type: 'twilio_config_response',
+        success: true,
+        hasCredentials: true,
+        warning: 'Toll-free verification deleted. Re-submitting may reset your position in the review queue.',
+      });
+    } else if (msg.action === 'release_number') {
+      if (!hasTwilioCredentials()) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: false,
+          error: 'Twilio credentials not configured. Set credentials first.',
+        });
+        return;
+      }
+
+      const raw = loadRawConfig();
+      const sms = (raw?.sms ?? {}) as Record<string, unknown>;
+      let phoneNumber: string;
+      if (msg.phoneNumber) {
+        phoneNumber = msg.phoneNumber;
+      } else if (msg.assistantId) {
+        const mapping = (sms.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
+        phoneNumber = mapping[msg.assistantId] ?? (sms.phoneNumber as string) ?? '';
+      } else {
+        phoneNumber = (sms.phoneNumber as string) ?? '';
+      }
+
+      if (!phoneNumber) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: 'No phone number to release. Specify phoneNumber or ensure one is assigned.',
+        });
+        return;
+      }
+
+      const accountSid = getSecureKey('credential:twilio:account_sid')!;
+      const authToken = getSecureKey('credential:twilio:auth_token')!;
+
+      await releasePhoneNumber(accountSid, authToken, phoneNumber);
+
+      // Clear the number from config and secure key store
+      if (sms.phoneNumber === phoneNumber) {
+        delete sms.phoneNumber;
+      }
+      const assistantPhoneNumbers = sms.assistantPhoneNumbers as Record<string, string> | undefined;
+      if (assistantPhoneNumbers) {
+        for (const [id, num] of Object.entries(assistantPhoneNumbers)) {
+          if (num === phoneNumber) {
+            delete assistantPhoneNumbers[id];
+          }
+        }
+        if (Object.keys(assistantPhoneNumbers).length === 0) {
+          delete sms.assistantPhoneNumbers;
+        }
+      }
+
+      const wasSuppressed = ctx.suppressConfigReload;
+      ctx.setSuppressConfigReload(true);
+      try {
+        saveRawConfig({ ...raw, sms });
+      } catch (err) {
+        ctx.setSuppressConfigReload(wasSuppressed);
+        throw err;
+      }
+      ctx.debounceTimers.schedule('__suppress_reset__', () => { ctx.setSuppressConfigReload(false); }, CONFIG_RELOAD_DEBOUNCE_MS);
+
+      // Clear the phone number from secure key store if it matches
+      const storedPhone = getSecureKey('credential:twilio:phone_number');
+      if (storedPhone === phoneNumber) {
+        deleteSecureKey('credential:twilio:phone_number');
+      }
+
+      ctx.send(socket, {
+        type: 'twilio_config_response',
+        success: true,
+        hasCredentials: true,
+        warning: 'Phone number released from Twilio. Any associated toll-free verification context is lost.',
+      });
+    } else if (msg.action === 'sms_send_test') {
+      // ── SMS send test ────────────────────────────────────────────────
+      if (!hasTwilioCredentials()) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: false,
+          error: 'Twilio credentials not configured. Set credentials first.',
+        });
+        return;
+      }
+
+      const to = msg.phoneNumber;
+      if (!to) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: 'phoneNumber is required for sms_send_test action.',
+        });
+        return;
+      }
+
+      const raw = loadRawConfig();
+      const smsSection = (raw?.sms ?? {}) as Record<string, unknown>;
+      const from = (smsSection.phoneNumber as string | undefined)
+        || getSecureKey('credential:twilio:phone_number')
+        || '';
+      if (!from) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: 'No phone number assigned. Run the twilio-setup skill to assign a number.',
+        });
+        return;
+      }
+
+      const accountSid = getSecureKey('credential:twilio:account_sid')!;
+      const authToken = getSecureKey('credential:twilio:auth_token')!;
+      const text = msg.text || 'Test SMS from your Vellum assistant';
+
+      // Send via gateway's /deliver/sms endpoint
+      const bearerToken = readHttpToken();
+      const gatewayPort = Number(process.env.GATEWAY_PORT) || 7830;
+      const gatewayUrl = process.env.GATEWAY_INTERNAL_BASE_URL?.replace(/\/+$/, '') || `http://127.0.0.1:${gatewayPort}`;
+
+      const sendResp = await fetch(`${gatewayUrl}/deliver/sms`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+        },
+        body: JSON.stringify({ to, text }),
+        signal: AbortSignal.timeout(30_000),
+      });
+
+      if (!sendResp.ok) {
+        const errBody = await sendResp.text().catch(() => '<unreadable>');
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: true,
+          error: `SMS send failed (${sendResp.status}): ${errBody}`,
+        });
+        return;
+      }
+
+      const sendData = await sendResp.json().catch(() => ({})) as {
+        messageSid?: string;
+        status?: string;
+      };
+      const messageSid = sendData.messageSid || '';
+      const initialStatus = sendData.status || 'unknown';
+
+      // Poll Twilio for final status (up to 3 times, 2s apart)
+      let finalStatus = initialStatus;
+      let errorCode: string | undefined;
+      let errorMessage: string | undefined;
+
+      if (messageSid) {
+        for (let i = 0; i < 3; i++) {
+          await new Promise((r) => setTimeout(r, 2000));
+          try {
+            const pollResult = await fetchMessageStatus(accountSid, authToken, messageSid);
+            finalStatus = pollResult.status;
+            errorCode = pollResult.errorCode;
+            errorMessage = pollResult.errorMessage;
+            // Stop polling if we've reached a terminal status
+            if (['delivered', 'undelivered', 'failed'].includes(finalStatus)) break;
+          } catch {
+            // Polling failure is non-fatal; we'll use the last known status
+            break;
+          }
+        }
+      }
+
+      const testResult = {
+        messageSid,
+        to,
+        initialStatus,
+        finalStatus,
+        ...(errorCode ? { errorCode } : {}),
+        ...(errorMessage ? { errorMessage } : {}),
+      };
+
+      // Store for sms_doctor
+      _lastTestResult = { ...testResult, timestamp: Date.now() };
+
+      ctx.send(socket, {
+        type: 'twilio_config_response',
+        success: true,
+        hasCredentials: true,
+        testResult,
+      });
+
+    } else if (msg.action === 'sms_doctor') {
+      // ── SMS doctor diagnostic ────────────────────────────────────────
+      const hasCredentials = hasTwilioCredentials();
+
+      // 1. Channel readiness check
+      let readinessReady = false;
+      const readinessIssues: string[] = [];
+      try {
+        const readinessService = getReadinessService();
+        const snapshot = await readinessService.getReadiness('sms', { includeRemote: false });
+        readinessReady = snapshot.ready;
+        for (const r of snapshot.reasons) {
+          readinessIssues.push(r.text);
+        }
+      } catch (err) {
+        readinessIssues.push(`Readiness check failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // 2. Compliance status
+      let complianceStatus = 'unknown';
+      let complianceDetail: string | undefined;
+      let complianceRemediation: string | undefined;
+      if (hasCredentials) {
+        try {
+          const raw = loadRawConfig();
+          const smsSection = (raw?.sms ?? {}) as Record<string, unknown>;
+          const phoneNumber = (smsSection.phoneNumber as string | undefined) || getSecureKey('credential:twilio:phone_number') || '';
+          if (phoneNumber) {
+            const accountSid = getSecureKey('credential:twilio:account_sid')!;
+            const authToken = getSecureKey('credential:twilio:auth_token')!;
+            // Determine number type and verification status
+            const isTollFree = phoneNumber.startsWith('+1') && ['800','888','877','866','855','844','833'].some(
+              (p) => phoneNumber.startsWith(`+1${p}`),
+            );
+            if (isTollFree) {
+              try {
+                const verification = await getTollFreeVerificationStatus(accountSid, authToken, phoneNumber);
+                if (verification) {
+                  const status = verification.status;
+                  complianceStatus = status;
+                  complianceDetail = `Toll-free verification: ${status}`;
+                  if (status === 'TWILIO_APPROVED') {
+                    complianceRemediation = undefined;
+                  } else if (status === 'PENDING_REVIEW' || status === 'IN_REVIEW') {
+                    complianceRemediation = 'Toll-free verification is pending. Messaging may have limited throughput until approved.';
+                  } else if (status === 'TWILIO_REJECTED') {
+                    complianceRemediation = 'Toll-free verification was rejected. Check rejection reasons and resubmit.';
+                  } else {
+                    complianceRemediation = 'Submit a toll-free verification to enable full messaging throughput.';
+                  }
+                } else {
+                  complianceStatus = 'unverified';
+                  complianceDetail = 'Toll-free number without verification';
+                  complianceRemediation = 'Submit a toll-free verification request to avoid filtering.';
+                }
+              } catch {
+                complianceStatus = 'check_failed';
+                complianceDetail = 'Could not retrieve toll-free verification status';
+              }
+            } else {
+              complianceStatus = 'local_10dlc';
+              complianceDetail = 'Local/10DLC number — carrier registration handled externally';
+            }
+          } else {
+            complianceStatus = 'no_number';
+            complianceDetail = 'No phone number assigned';
+            complianceRemediation = 'Assign a phone number via the twilio-setup skill.';
+          }
+        } catch {
+          complianceStatus = 'check_failed';
+          complianceDetail = 'Could not determine compliance status';
+        }
+      } else {
+        complianceStatus = 'no_credentials';
+        complianceDetail = 'Twilio credentials are not configured';
+        complianceRemediation = 'Set Twilio credentials via the twilio-setup skill.';
+      }
+
+      // 3. Last send test result
+      let lastSend: { status: string; errorCode?: string; remediation?: string } | undefined;
+      if (_lastTestResult) {
+        lastSend = {
+          status: _lastTestResult.finalStatus,
+          ...((_lastTestResult.errorCode) ? { errorCode: _lastTestResult.errorCode } : {}),
+          ...((_lastTestResult.errorCode) ? { remediation: mapTwilioErrorRemediation(_lastTestResult.errorCode) } : {}),
+        };
+      }
+
+      // 4. Determine overall status
+      const actionItems: string[] = [];
+      let overallStatus: 'healthy' | 'degraded' | 'broken' = 'healthy';
+
+      if (!hasCredentials) {
+        overallStatus = 'broken';
+        actionItems.push('Configure Twilio credentials.');
+      }
+      if (!readinessReady) {
+        overallStatus = 'broken';
+        for (const issue of readinessIssues) actionItems.push(issue);
+      }
+      if (complianceStatus === 'unverified' || complianceStatus === 'PENDING_REVIEW' || complianceStatus === 'IN_REVIEW') {
+        if (overallStatus === 'healthy') overallStatus = 'degraded';
+        if (complianceRemediation) actionItems.push(complianceRemediation);
+      }
+      if (complianceStatus === 'TWILIO_REJECTED' || complianceStatus === 'no_number') {
+        overallStatus = 'broken';
+        if (complianceRemediation) actionItems.push(complianceRemediation);
+      }
+      if (_lastTestResult && ['failed', 'undelivered'].includes(_lastTestResult.finalStatus)) {
+        if (overallStatus === 'healthy') overallStatus = 'degraded';
+        const remediation = mapTwilioErrorRemediation(_lastTestResult.errorCode);
+        actionItems.push(remediation || `Last test SMS ${_lastTestResult.finalStatus}. Check Twilio logs for details.`);
+      }
+
+      ctx.send(socket, {
+        type: 'twilio_config_response',
+        success: true,
+        hasCredentials,
+        diagnostics: {
+          readiness: { ready: readinessReady, issues: readinessIssues },
+          compliance: {
+            status: complianceStatus,
+            ...(complianceDetail ? { detail: complianceDetail } : {}),
+            ...(complianceRemediation ? { remediation: complianceRemediation } : {}),
+          },
+          ...(lastSend ? { lastSend } : {}),
+          overallStatus,
+          actionItems,
+        },
+      });
+
     } else {
       ctx.send(socket, {
         type: 'twilio_config_response',
@@ -1484,12 +2142,12 @@ export function handleGuardianVerification(
   socket: net.Socket,
   ctx: HandlerContext,
 ): void {
-  try {
-    // Use the assistant ID from the request when available; fall back to
-    // 'self' for backward compatibility with single-assistant mode.
-    const assistantId = msg.assistantId ?? 'self';
-    const channel = msg.channel ?? 'telegram';
+  // Use the assistant ID from the request when available; fall back to
+  // 'self' for backward compatibility with single-assistant mode.
+  const assistantId = msg.assistantId ?? 'self';
+  const channel = msg.channel ?? 'telegram';
 
+  try {
     if (msg.action === 'create_challenge') {
       const result = createVerificationChallenge(assistantId, channel, msg.sessionId);
 
@@ -1498,14 +2156,47 @@ export function handleGuardianVerification(
         success: true,
         secret: result.secret,
         instruction: result.instruction,
+        channel,
       });
     } else if (msg.action === 'status') {
       const binding = getGuardianBinding(assistantId, channel);
+      let guardianUsername: string | undefined;
+      let guardianDisplayName: string | undefined;
+      if (binding?.metadataJson) {
+        try {
+          const parsed = JSON.parse(binding.metadataJson) as Record<string, unknown>;
+          if (typeof parsed.username === 'string' && parsed.username.trim().length > 0) {
+            guardianUsername = parsed.username.trim();
+          }
+          if (typeof parsed.displayName === 'string' && parsed.displayName.trim().length > 0) {
+            guardianDisplayName = parsed.displayName.trim();
+          }
+        } catch {
+          // ignore malformed metadata
+        }
+      }
+      if (binding?.guardianDeliveryChatId && (!guardianUsername || !guardianDisplayName)) {
+        const ext = externalConversationStore.getBindingByChannelChat(
+          channel,
+          binding.guardianDeliveryChatId,
+        );
+        if (!guardianUsername && ext?.username) {
+          guardianUsername = ext.username;
+        }
+        if (!guardianDisplayName && ext?.displayName) {
+          guardianDisplayName = ext.displayName;
+        }
+      }
       ctx.send(socket, {
         type: 'guardian_verification_response',
         success: true,
         bound: binding !== null,
         guardianExternalUserId: binding?.guardianExternalUserId,
+        guardianUsername,
+        guardianDisplayName,
+        channel,
+        assistantId,
+        guardianDeliveryChatId: binding?.guardianDeliveryChatId,
       });
     } else if (msg.action === 'revoke') {
       revokeGuardianBinding(assistantId, channel);
@@ -1513,12 +2204,14 @@ export function handleGuardianVerification(
         type: 'guardian_verification_response',
         success: true,
         bound: false,
+        channel,
       });
     } else {
       ctx.send(socket, {
         type: 'guardian_verification_response',
         success: false,
         error: `Unknown action: ${String(msg.action)}`,
+        channel,
       });
     }
   } catch (err) {
@@ -1528,6 +2221,58 @@ export function handleGuardianVerification(
       type: 'guardian_verification_response',
       success: false,
       error: message,
+      channel,
+    });
+  }
+}
+
+// Lazy singleton — created on first use so module-load stays lightweight.
+let _readinessService: ChannelReadinessService | undefined;
+function getReadinessService(): ChannelReadinessService {
+  if (!_readinessService) {
+    _readinessService = createReadinessService();
+  }
+  return _readinessService;
+}
+
+export async function handleChannelReadiness(
+  msg: ChannelReadinessRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): Promise<void> {
+  try {
+    const service = getReadinessService();
+
+    if (msg.action === 'refresh') {
+      if (msg.channel) {
+        service.invalidateChannel(msg.channel);
+      } else {
+        service.invalidateAll();
+      }
+    }
+
+    const snapshots = await service.getReadiness(msg.channel, msg.includeRemote);
+
+    ctx.send(socket, {
+      type: 'channel_readiness_response',
+      success: true,
+      snapshots: snapshots.map((s) => ({
+        channel: s.channel,
+        ready: s.ready,
+        checkedAt: s.checkedAt,
+        stale: s.stale,
+        reasons: s.reasons,
+        localChecks: s.localChecks,
+        remoteChecks: s.remoteChecks,
+      })),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err }, 'Failed to handle channel readiness');
+    ctx.send(socket, {
+      type: 'channel_readiness_response',
+      success: false,
+      error: message,
     });
   }
 }
@@ -1540,6 +2285,32 @@ export function handleEnvVarsRequest(socket: net.Socket, ctx: HandlerContext): v
   ctx.send(socket, { type: 'env_vars_response', vars });
 }
 
+/**
+ * Look up manifest metadata for a tool that isn't in the live registry.
+ * Searches all installed skills' TOOLS.json manifests for a matching tool name.
+ */
+function resolveManifestOverride(toolName: string): ManifestOverride | undefined {
+  if (getTool(toolName)) return undefined;
+  try {
+    const catalog = loadSkillCatalog();
+    for (const skill of catalog) {
+      if (!skill.toolManifest?.present || !skill.toolManifest.valid) continue;
+      try {
+        const manifest = parseToolManifestFile(join(skill.directoryPath, 'TOOLS.json'));
+        const entry = manifest.tools.find((t) => t.name === toolName);
+        if (entry) {
+          return { risk: entry.risk, execution_target: entry.execution_target };
+        }
+      } catch {
+        // Skip unparseable manifests
+      }
+    }
+  } catch {
+    // Non-fatal
+  }
+  return undefined;
+}
+
 export async function handleToolPermissionSimulate(
   msg: ToolPermissionSimulateRequest,
   socket: net.Socket,
@@ -1565,13 +2336,15 @@ export async function handleToolPermissionSimulate(
 
     const workingDir = msg.workingDir ?? process.cwd();
 
-    // Resolve execution target using manifest metadata or prefix heuristics.
-    // resolveExecutionTarget handles unregistered tools via prefix fallback.
-    const executionTarget = resolveExecutionTarget(msg.toolName);
+    // For unregistered skill tools, resolve manifest metadata so the simulation
+    // uses accurate risk/execution_target values instead of falling back to defaults.
+    const manifestOverride = resolveManifestOverride(msg.toolName);
+
+    const executionTarget = resolveExecutionTarget(msg.toolName, manifestOverride);
     const policyContext = { executionTarget };
 
-    const riskLevel = await classifyRisk(msg.toolName, msg.input, workingDir);
-    const result = await check(msg.toolName, msg.input, workingDir, policyContext);
+    const riskLevel = await classifyRisk(msg.toolName, msg.input, workingDir, undefined, manifestOverride);
+    const result = await check(msg.toolName, msg.input, workingDir, policyContext, manifestOverride);
 
     // Private-thread override: promote allow → prompt for side-effect tools
     if (
@@ -1629,7 +2402,7 @@ export async function handleToolPermissionSimulate(
 
 export function handleToolNamesList(socket: net.Socket, ctx: HandlerContext): void {
   const tools = getAllTools();
-  const names = tools.map((t) => t.name).sort((a, b) => a.localeCompare(b));
+  const nameSet = new Set(tools.map((t) => t.name));
   const schemas: Record<string, import('../ipc-contract.js').ToolInputSchema> = {};
   for (const tool of tools) {
     try {
@@ -1639,6 +2412,29 @@ export function handleToolNamesList(socket: net.Socket, ctx: HandlerContext): vo
       // Skip tools whose definitions can't be resolved
     }
   }
+
+  // Include tools from all installed skills, even those not currently
+  // activated in any session.
+  try {
+    const catalog = loadSkillCatalog();
+    for (const skill of catalog) {
+      if (!skill.toolManifest?.present || !skill.toolManifest.valid) continue;
+      try {
+        const manifest = parseToolManifestFile(join(skill.directoryPath, 'TOOLS.json'));
+        for (const entry of manifest.tools) {
+          if (nameSet.has(entry.name)) continue;
+          nameSet.add(entry.name);
+          schemas[entry.name] = entry.input_schema as unknown as import('../ipc-contract.js').ToolInputSchema;
+        }
+      } catch {
+        // Skip skills whose manifests can't be parsed
+      }
+    }
+  } catch {
+    // Non-fatal — fall back to registered tools only
+  }
+
+  const names = Array.from(nameSet).sort((a, b) => a.localeCompare(b));
   ctx.send(socket, { type: 'tool_names_list_response', names, schemas });
 }
 
@@ -1663,6 +2459,7 @@ export const configHandlers = defineHandlers({
   twitter_integration_config: handleTwitterIntegrationConfig,
   telegram_config: handleTelegramConfig,
   twilio_config: handleTwilioConfig,
+  channel_readiness: handleChannelReadiness,
   guardian_verification: handleGuardianVerification,
   env_vars_request: (_msg, socket, ctx) => handleEnvVarsRequest(socket, ctx),
   tool_permission_simulate: handleToolPermissionSimulate,