@vellumai/assistant 0.3.5 → 0.3.6

package/src/runtime/channel-approval-parser.ts

@@ -4,6 +4,11 @@
  * Parses inbound user text to determine whether it matches an approval,
  * rejection, or "approve always" intent. This module is transport-agnostic
  * and can be used by any channel adapter (Telegram, SMS, etc.).
+ *
+ * Both the standard and guardian approval flows now use the conversational
+ * approval engine as the primary classifier. This deterministic parser is
+ * retained only as a legacy fallback for when the conversational engine is
+ * not injected (i.e. approvalConversationGenerator is undefined).
  */
 
 import type { ApprovalAction, ApprovalDecisionResult } from './channel-approval-types.js';
@@ -44,6 +49,30 @@ const PHRASE_MAP = buildPhraseMap();
 // Public API
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Run-reference tag extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Pattern matching a `[ref:<runId>]` disambiguation tag appended to
+ * plain-text approval prompts. Guardians can include this tag in their
+ * reply so that `handleApprovalInterception` can resolve the correct
+ * pending approval when multiple approvals target the same chat.
+ */
+const REF_TAG_RE = /\[ref:([^\]]+)\]/i;
+
+/**
+ * Extract a run-reference tag from the text and return the cleaned
+ * decision text plus the extracted runId (if any).
+ */
+function extractRefTag(text: string): { cleaned: string; runId?: string } {
+  const match = REF_TAG_RE.exec(text);
+  if (!match) return { cleaned: text };
+  const runId = match[1].trim();
+  const cleaned = text.replace(REF_TAG_RE, '').trim();
+  return { cleaned, runId: runId || undefined };
+}
+
 /**
  * Parse a plain-text message into an approval decision.
  *
@@ -51,10 +80,15 @@ const PHRASE_MAP = buildPhraseMap();
  * of the known intent phrases, or `null` if it does not match.
  *
  * Matching is case-insensitive with leading/trailing whitespace trimmed.
+ *
+ * When the text contains a `[ref:<runId>]` tag (appended by the
+ * plain-text fallback path), the extracted runId is included in the
+ * result so the caller can disambiguate among multiple pending approvals.
  */
 export function parseApprovalDecision(text: string): ApprovalDecisionResult | null {
-  const normalised = text.trim().toLowerCase();
+  const { cleaned, runId } = extractRefTag(text);
+  const normalised = cleaned.trim().toLowerCase();
   const action = PHRASE_MAP.get(normalised);
   if (!action) return null;
-  return { action, source: 'plain_text' };
+  return { action, source: 'plain_text', ...(runId ? { runId } : {}) };
 }

package/src/runtime/channel-approvals.ts

@@ -7,7 +7,6 @@
  *   1. Detect pending confirmations for a conversation
  *   2. Build human-readable approval prompts with action buttons
  *   3. Consume user decisions and apply them to the underlying run
- *   4. Build reminder prompts when non-decision messages arrive
  */
 
 import { getPendingConfirmationsByConversation, getRun } from '../memory/runs-store.js';
@@ -206,23 +205,3 @@ const RICH_APPROVAL_CHANNELS: ReadonlySet<string> = new Set(['telegram']);
 export function channelSupportsRichApprovalUI(channel: string): boolean {
   return RICH_APPROVAL_CHANNELS.has(channel);
 }
-
-// ---------------------------------------------------------------------------
-// 6. Reminder prompt for non-decision messages
-// ---------------------------------------------------------------------------
-
-/**
- * Build a reminder prompt when the user sends a non-decision message while
- * an approval is pending. Reuses the original actions and fallback text
- * but prefixes the prompt text with a reminder.
- */
-export function buildReminderPrompt(
-  pendingPrompt: ChannelApprovalPrompt,
-): ChannelApprovalPrompt {
-  const reminderPrefix = composeApprovalMessage({ scenario: 'reminder_prompt' });
-  return {
-    promptText: `${reminderPrefix}\n\n${pendingPrompt.promptText}`,
-    actions: pendingPrompt.actions,
-    plainTextFallback: `${reminderPrefix}\n\n${pendingPrompt.plainTextFallback}`,
-  };
-}

package/src/runtime/channel-guardian-service.ts

@@ -12,14 +12,16 @@ import {
   createBinding,
   getActiveBinding,
   revokeBinding as storeRevokeBinding,
+  revokePendingChallenges as storeRevokePendingChallenges,
   createChallenge,
   findPendingChallengeByHash,
+  findPendingChallengeForChannel,
   consumeChallenge,
   getRateLimit,
   recordInvalidAttempt,
   resetRateLimit,
 } from '../memory/channel-guardian-store.js';
-import type { GuardianBinding } from '../memory/channel-guardian-store.js';
+import type { GuardianBinding, VerificationChallenge } from '../memory/channel-guardian-store.js';
 import { composeApprovalMessage } from './approval-message-composer.js';
 
 // ---------------------------------------------------------------------------
@@ -66,19 +68,33 @@ function hashSecret(secret: string): string {
 // Service
 // ---------------------------------------------------------------------------
 
+/**
+ * Generate a six-digit numeric secret for voice channel challenges.
+ * Uses cryptographic randomness to pick a number in [100000, 999999].
+ */
+function generateVoiceSecret(): string {
+  const buf = randomBytes(4);
+  const num = buf.readUInt32BE(0);
+  // Map to the range [100000, 999999] (900000 possible values)
+  return String(100000 + (num % 900000));
+}
+
 /**
  * Create a new verification challenge for a guardian candidate.
  *
- * Generates a random secret, hashes it (SHA-256), and stores the
- * challenge record with a 10-minute TTL. The raw secret is returned
- * so it can be displayed to the user; only the hash is persisted.
+ * For voice channels, generates a six-digit numeric secret that can be
+ * spoken aloud. For all other channels, generates a 32-byte hex secret.
+ *
+ * Hashes the secret (SHA-256) and stores the challenge record with a
+ * 10-minute TTL. The raw secret is returned so it can be displayed to
+ * the user; only the hash is persisted.
  */
 export function createVerificationChallenge(
   assistantId: string,
   channel: string,
   sessionId?: string,
 ): CreateChallengeResult {
-  const secret = randomBytes(32).toString('hex');
+  const secret = channel === 'voice' ? generateVoiceSecret() : randomBytes(32).toString('hex');
   const challengeHash = hashSecret(secret);
   const challengeId = uuid();
   const expiresAt = Date.now() + CHALLENGE_TTL_MS;
@@ -102,6 +118,7 @@ export function createVerificationChallenge(
     ttlSeconds,
     instruction: composeApprovalMessage({
       scenario: 'guardian_verify_challenge_setup',
+      channel,
       verifyCommand,
       ttlSeconds,
     }),
@@ -131,7 +148,7 @@ export function validateAndConsumeChallenge(
 ): ValidateChallengeResult {
   // ── Rate-limit check ──
   const existing = getRateLimit(assistantId, channel, actorExternalUserId, actorChatId);
-  if (existing && existing.lockedUntil !== null && Date.now() < existing.lockedUntil) {
+  if (existing && existing.lockedUntil != null && Date.now() < existing.lockedUntil) {
     // Use the same generic failure message to avoid leaking whether the
     // actor is rate-limited vs. the code is genuinely wrong.
     return {
@@ -224,7 +241,7 @@ export function isGuardian(
   externalUserId: string,
 ): boolean {
   const binding = getActiveBinding(assistantId, channel);
-  return binding !== null && binding.guardianExternalUserId === externalUserId;
+  return binding != null && binding.guardianExternalUserId === externalUserId;
 }
 
 /**
@@ -236,3 +253,27 @@ export function revokeBinding(
 ): boolean {
   return storeRevokeBinding(assistantId, channel);
 }
+
+/**
+ * Revoke all pending challenges for a given assistant and channel.
+ * Called when the user cancels verification so that stale challenges
+ * don't gate inbound calls.
+ */
+export function revokePendingChallenges(
+  assistantId: string,
+  channel: string,
+): void {
+  storeRevokePendingChallenges(assistantId, channel);
+}
+
+/**
+ * Look up a pending (non-expired) verification challenge for a given
+ * assistant and channel. Used by relay setup to detect whether an active
+ * voice verification session exists.
+ */
+export function getPendingChallenge(
+  assistantId: string,
+  channel: string,
+): VerificationChallenge | null {
+  return findPendingChallengeForChannel(assistantId, channel);
+}

package/src/runtime/channel-readiness-service.ts

@@ -1,6 +1,7 @@
 import type {
   ChannelId,
   ChannelProbe,
+  ChannelProbeContext,
   ChannelReadinessSnapshot,
   ReadinessCheckResult,
 } from './channel-readiness-types.js';
@@ -11,6 +12,7 @@ import {
 } from '../calls/twilio-rest.js';
 import { getSecureKey } from '../security/secure-keys.js';
 import { loadRawConfig } from '../config/loader.js';
+import { getTwilioPhoneNumberEnv } from '../config/env.js';
 
 /** Remote check results are cached for 5 minutes before being considered stale. */
 export const REMOTE_TTL_MS = 5 * 60 * 1000;
@@ -29,9 +31,54 @@ function hasIngressConfigured(): boolean {
   }
 }
 
+function getAssistantMappedPhoneNumber(
+  smsConfig: Record<string, unknown>,
+  assistantId?: string,
+): string | undefined {
+  if (!assistantId) return undefined;
+  const mapping = (smsConfig.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
+  return mapping[assistantId];
+}
+
+function hasAnyAssistantMappedPhoneNumber(smsConfig: Record<string, unknown>): boolean {
+  const mapping = (smsConfig.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
+  return Object.keys(mapping).length > 0;
+}
+
+function hasAnyAssistantMappedPhoneNumberSafe(): boolean {
+  try {
+    const raw = loadRawConfig();
+    const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
+    return hasAnyAssistantMappedPhoneNumber(smsConfig);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve SMS from-number with canonical precedence:
+ * assistant mapping -> env override -> config sms.phoneNumber -> secure key fallback.
+ */
+function resolveSmsPhoneNumber(assistantId?: string): string {
+  try {
+    const raw = loadRawConfig();
+    const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
+    const mapped = getAssistantMappedPhoneNumber(smsConfig, assistantId);
+    return mapped
+      || getTwilioPhoneNumberEnv()
+      || (smsConfig.phoneNumber as string)
+      || getSecureKey('credential:twilio:phone_number')
+      || '';
+  } catch {
+    return getTwilioPhoneNumberEnv()
+      || getSecureKey('credential:twilio:phone_number')
+      || '';
+  }
+}
+
 const smsProbe: ChannelProbe = {
   channel: 'sms',
-  runLocalChecks(): ReadinessCheckResult[] {
+  runLocalChecks(context?: ChannelProbeContext): ReadinessCheckResult[] {
     const results: ReadinessCheckResult[] = [];
 
     const hasCreds = hasTwilioCredentials();
@@ -43,23 +90,18 @@ const smsProbe: ChannelProbe = {
         : 'Twilio Account SID and Auth Token are not configured',
     });
 
-    let hasPhone = !!process.env.TWILIO_PHONE_NUMBER;
-    if (!hasPhone) {
-      try {
-        const raw = loadRawConfig();
-        const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
-        hasPhone = !!(smsConfig.phoneNumber as string);
-      } catch { /* ignore */ }
-    }
-    if (!hasPhone) {
-      hasPhone = !!getSecureKey('credential:twilio:phone_number');
-    }
+    const resolvedNumber = resolveSmsPhoneNumber(context?.assistantId);
+    const hasPhone = !!resolvedNumber || (!context?.assistantId && hasAnyAssistantMappedPhoneNumberSafe());
     results.push({
       name: 'phone_number',
       passed: hasPhone,
       message: hasPhone
-        ? 'Phone number is assigned'
-        : 'No phone number assigned',
+        ? (context?.assistantId && !resolvedNumber
+          ? `Assistant ${context.assistantId} has no direct mapping, but SMS phone numbers are assigned`
+          : 'Phone number is assigned')
+        : (context?.assistantId
+          ? `No phone number assigned for assistant ${context.assistantId}`
+          : 'No phone number assigned'),
     });
 
     const hasIngress = hasIngressConfigured();
@@ -73,20 +115,14 @@ const smsProbe: ChannelProbe = {
 
     return results;
   },
-  async runRemoteChecks(): Promise<ReadinessCheckResult[]> {
+  async runRemoteChecks(context?: ChannelProbeContext): Promise<ReadinessCheckResult[]> {
     if (!hasTwilioCredentials()) return [];
 
     const accountSid = getSecureKey('credential:twilio:account_sid');
     const authToken = getSecureKey('credential:twilio:auth_token');
     if (!accountSid || !authToken) return [];
 
-    // Resolve the assigned phone number using fallback chain
-    const raw = loadRawConfig();
-    const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
-    const phoneNumber = (smsConfig.phoneNumber as string)
-      || getSecureKey('credential:twilio:phone_number')
-      || process.env.TWILIO_PHONE_NUMBER
-      || '';
+    const phoneNumber = resolveSmsPhoneNumber(context?.assistantId);
     if (!phoneNumber) return [];
 
     // Only toll-free numbers need verification checks
@@ -130,6 +166,73 @@ const smsProbe: ChannelProbe = {
   },
 };
 
+// ── Voice Probe ─────────────────────────────────────────────────────────────
+
+/**
+ * Resolve voice from-number with the same precedence as SMS:
+ * assistant mapping -> env override -> config sms.phoneNumber -> secure key fallback.
+ *
+ * Voice and SMS share the same Twilio phone number infrastructure, so the
+ * resolution logic is identical to resolveSmsPhoneNumber.
+ */
+function resolveVoicePhoneNumber(assistantId?: string): string {
+  try {
+    const raw = loadRawConfig();
+    const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
+    const mapped = getAssistantMappedPhoneNumber(smsConfig, assistantId);
+    return mapped
+      || getTwilioPhoneNumberEnv()
+      || (smsConfig.phoneNumber as string)
+      || getSecureKey('credential:twilio:phone_number')
+      || '';
+  } catch {
+    return getTwilioPhoneNumberEnv()
+      || getSecureKey('credential:twilio:phone_number')
+      || '';
+  }
+}
+
+const voiceProbe: ChannelProbe = {
+  channel: 'voice',
+  runLocalChecks(context?: ChannelProbeContext): ReadinessCheckResult[] {
+    const results: ReadinessCheckResult[] = [];
+
+    const hasCreds = hasTwilioCredentials();
+    results.push({
+      name: 'twilio_credentials',
+      passed: hasCreds,
+      message: hasCreds
+        ? 'Twilio credentials are configured'
+        : 'Twilio Account SID and Auth Token are not configured',
+    });
+
+    const resolvedNumber = resolveVoicePhoneNumber(context?.assistantId);
+    const hasPhone = !!resolvedNumber || (!context?.assistantId && hasAnyAssistantMappedPhoneNumberSafe());
+    results.push({
+      name: 'phone_number',
+      passed: hasPhone,
+      message: hasPhone
+        ? (context?.assistantId && !resolvedNumber
+          ? `Assistant ${context.assistantId} has no direct mapping, but phone numbers are assigned`
+          : 'Phone number is assigned for voice calls')
+        : (context?.assistantId
+          ? `No phone number assigned for assistant ${context.assistantId}`
+          : 'No phone number assigned for voice calls'),
+    });
+
+    const hasIngress = hasIngressConfigured();
+    results.push({
+      name: 'ingress',
+      passed: hasIngress,
+      message: hasIngress
+        ? 'Public ingress URL is configured'
+        : 'Public ingress URL is not configured or disabled',
+    });
+
+    return results;
+  },
+};
+
 // ── Telegram Probe ──────────────────────────────────────────────────────────
 
 const telegramProbe: ChannelProbe = {
@@ -173,7 +276,7 @@ const telegramProbe: ChannelProbe = {
 
 export class ChannelReadinessService {
   private probes = new Map<ChannelId, ChannelProbe>();
-  private snapshots = new Map<ChannelId, ChannelReadinessSnapshot>();
+  private snapshots = new Map<string, ChannelReadinessSnapshot>();
 
   registerProbe(probe: ChannelProbe): void {
     this.probes.set(probe.channel, probe);
@@ -187,6 +290,7 @@ export class ChannelReadinessService {
   async getReadiness(
     channel?: ChannelId,
     includeRemote?: boolean,
+    assistantId?: string,
   ): Promise<ChannelReadinessSnapshot[]> {
     const channels = channel
       ? [channel]
@@ -200,32 +304,40 @@ export class ChannelReadinessService {
         continue;
       }
 
-      const localChecks = probe.runLocalChecks();
+      const probeContext: ChannelProbeContext = { assistantId };
+      const localChecks = probe.runLocalChecks(probeContext);
       let remoteChecks: ReadinessCheckResult[] | undefined;
       let remoteChecksFreshlyFetched = false;
+      let remoteChecksAffectReadiness = false;
       let stale = false;
 
-      const cached = this.snapshots.get(ch);
+      const cacheKey = this.snapshotCacheKey(ch, assistantId);
+      const cached = this.snapshots.get(cacheKey);
       const now = Date.now();
 
       if (includeRemote && probe.runRemoteChecks) {
         const cacheExpired = !cached || !cached.remoteChecks || (now - cached.checkedAt) >= REMOTE_TTL_MS;
         if (cacheExpired) {
-          remoteChecks = await probe.runRemoteChecks();
+          remoteChecks = await probe.runRemoteChecks(probeContext);
           remoteChecksFreshlyFetched = true;
+          remoteChecksAffectReadiness = true;
         } else {
           // Reuse cached remote checks
           remoteChecks = cached.remoteChecks;
+          remoteChecksAffectReadiness = true;
         }
       } else if (cached?.remoteChecks) {
-        // Surface cached remote checks even when not explicitly requested,
-        // but mark stale if TTL has elapsed
+        // Surface cached remote checks for visibility but never let them affect
+        // readiness when the caller explicitly opted out of remote checks.
         remoteChecks = cached.remoteChecks;
         stale = (now - cached.checkedAt) >= REMOTE_TTL_MS;
+        remoteChecksAffectReadiness = false;
       }
 
       const allLocalPassed = localChecks.every((c) => c.passed);
-      const allRemotePassed = remoteChecks ? remoteChecks.every((c) => c.passed) : true;
+      const allRemotePassed = (remoteChecks && remoteChecksAffectReadiness)
+        ? remoteChecks.every((c) => c.passed)
+        : true;
       const ready = allLocalPassed && allRemotePassed;
 
       const reasons: Array<{ code: string; text: string }> = [];
@@ -234,7 +346,7 @@ export class ChannelReadinessService {
           reasons.push({ code: check.name, text: check.message });
         }
       }
-      if (remoteChecks) {
+      if (remoteChecks && remoteChecksAffectReadiness) {
         for (const check of remoteChecks) {
           if (!check.passed) {
             reasons.push({ code: check.name, text: check.message });
@@ -252,7 +364,7 @@ export class ChannelReadinessService {
         remoteChecks,
       };
 
-      this.snapshots.set(ch, snapshot);
+      this.snapshots.set(cacheKey, snapshot);
       results.push(snapshot);
     }
 
@@ -260,8 +372,17 @@ export class ChannelReadinessService {
   }
 
   /** Clear cached snapshot for a specific channel, forcing re-evaluation on next call. */
-  invalidateChannel(channel: ChannelId): void {
-    this.snapshots.delete(channel);
+  invalidateChannel(channel: ChannelId, assistantId?: string): void {
+    if (assistantId) {
+      this.snapshots.delete(this.snapshotCacheKey(channel, assistantId));
+      return;
+    }
+    const prefix = `${channel}::`;
+    for (const key of this.snapshots.keys()) {
+      if (key.startsWith(prefix)) {
+        this.snapshots.delete(key);
+      }
+    }
   }
 
   /** Clear all cached snapshots. */
@@ -279,14 +400,19 @@ export class ChannelReadinessService {
       localChecks: [],
     };
   }
+
+  private snapshotCacheKey(channel: ChannelId, assistantId?: string): string {
+    return `${channel}::${assistantId ?? '__default__'}`;
+  }
 }
 
 // ── Factory ─────────────────────────────────────────────────────────────────
 
-/** Create a service instance with built-in SMS and Telegram probes registered. */
+/** Create a service instance with built-in SMS, Voice, and Telegram probes registered. */
 export function createReadinessService(): ChannelReadinessService {
   const service = new ChannelReadinessService();
   service.registerProbe(smsProbe);
+  service.registerProbe(voiceProbe);
   service.registerProbe(telegramProbe);
   return service;
 }

package/src/runtime/channel-readiness-types.ts

@@ -1,7 +1,8 @@
 // Channel readiness types — reusable primitive for all channels.
 
-/** Logical channel identifier. Well-known channels have literal types; custom channels use string. */
-export type ChannelId = 'sms' | 'telegram' | string;
+import type { ChannelId } from '../channels/types.js';
+
+export type { ChannelId };
 
 /** Result of a single readiness check (local or remote). */
 export interface ReadinessCheckResult {
@@ -21,9 +22,14 @@ export interface ChannelReadinessSnapshot {
   remoteChecks?: ReadinessCheckResult[];
 }
 
+/** Optional probe context for assistant-scoped readiness checks. */
+export interface ChannelProbeContext {
+  assistantId?: string;
+}
+
 /** Probe interface that channels implement to provide readiness checks. */
 export interface ChannelProbe {
   channel: ChannelId;
-  runLocalChecks(): ReadinessCheckResult[];
-  runRemoteChecks?(): Promise<ReadinessCheckResult[]>;
+  runLocalChecks(context?: ChannelProbeContext): ReadinessCheckResult[];
+  runRemoteChecks?(context?: ChannelProbeContext): Promise<ReadinessCheckResult[]>;
 }