@vellumai/assistant 0.3.4 → 0.3.6

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

@@ -0,0 +1,418 @@
+import type {
+  ChannelId,
+  ChannelProbe,
+  ChannelProbeContext,
+  ChannelReadinessSnapshot,
+  ReadinessCheckResult,
+} from './channel-readiness-types.js';
+import {
+  hasTwilioCredentials,
+  getTollFreeVerificationStatus,
+  getPhoneNumberSid,
+} 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;
+
+// ── SMS Probe ───────────────────────────────────────────────────────────────
+
+function hasIngressConfigured(): boolean {
+  try {
+    const raw = loadRawConfig();
+    const ingress = (raw?.ingress ?? {}) as Record<string, unknown>;
+    const publicBaseUrl = (ingress.publicBaseUrl as string) ?? '';
+    const enabled = (ingress.enabled as boolean | undefined) ?? (publicBaseUrl ? true : false);
+    return enabled && publicBaseUrl.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+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(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 = resolveSmsPhoneNumber(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 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();
+    results.push({
+      name: 'ingress',
+      passed: hasIngress,
+      message: hasIngress
+        ? 'Public ingress URL is configured'
+        : 'Public ingress URL is not configured or disabled',
+    });
+
+    return results;
+  },
+  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 [];
+
+    const phoneNumber = resolveSmsPhoneNumber(context?.assistantId);
+    if (!phoneNumber) return [];
+
+    // Only toll-free numbers need verification checks
+    const tollFreePrefixes = ['+1800', '+1833', '+1844', '+1855', '+1866', '+1877', '+1888'];
+    const isTollFree = tollFreePrefixes.some((prefix) => phoneNumber.startsWith(prefix));
+    if (!isTollFree) return [];
+
+    try {
+      const phoneSid = await getPhoneNumberSid(accountSid, authToken, phoneNumber);
+      if (!phoneSid) {
+        return [{
+          name: 'toll_free_verification',
+          passed: false,
+          message: `Phone number ${phoneNumber} not found on Twilio account`,
+        }];
+      }
+
+      const verification = await getTollFreeVerificationStatus(accountSid, authToken, phoneSid);
+      if (!verification) {
+        return [{
+          name: 'toll_free_verification',
+          passed: false,
+          message: 'No toll-free verification submitted. Verification is required for SMS sending.',
+        }];
+      }
+
+      const approved = verification.status === 'TWILIO_APPROVED';
+      return [{
+        name: 'toll_free_verification',
+        passed: approved,
+        message: `toll_free_verification: ${verification.status}`,
+      }];
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return [{
+        name: 'toll_free_verification',
+        passed: false,
+        message: `Failed to check toll-free verification: ${message}`,
+      }];
+    }
+  },
+};
+
+// ── 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 = {
+  channel: 'telegram',
+  runLocalChecks(): ReadinessCheckResult[] {
+    const results: ReadinessCheckResult[] = [];
+
+    const hasBotToken = !!getSecureKey('credential:telegram:bot_token');
+    results.push({
+      name: 'bot_token',
+      passed: hasBotToken,
+      message: hasBotToken
+        ? 'Telegram bot token is configured'
+        : 'Telegram bot token is not configured',
+    });
+
+    const hasWebhookSecret = !!getSecureKey('credential:telegram:webhook_secret');
+    results.push({
+      name: 'webhook_secret',
+      passed: hasWebhookSecret,
+      message: hasWebhookSecret
+        ? 'Telegram webhook secret is configured'
+        : 'Telegram webhook secret is not configured',
+    });
+
+    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 has no remote checks currently
+};
+
+// ── Service ─────────────────────────────────────────────────────────────────
+
+export class ChannelReadinessService {
+  private probes = new Map<ChannelId, ChannelProbe>();
+  private snapshots = new Map<string, ChannelReadinessSnapshot>();
+
+  registerProbe(probe: ChannelProbe): void {
+    this.probes.set(probe.channel, probe);
+  }
+
+  /**
+   * Get readiness snapshots for the specified channel (or all registered channels).
+   * Local checks always run inline. Remote checks run only when `includeRemote`
+   * is true and the cache is stale or missing.
+   */
+  async getReadiness(
+    channel?: ChannelId,
+    includeRemote?: boolean,
+    assistantId?: string,
+  ): Promise<ChannelReadinessSnapshot[]> {
+    const channels = channel
+      ? [channel]
+      : Array.from(this.probes.keys());
+
+    const results: ChannelReadinessSnapshot[] = [];
+    for (const ch of channels) {
+      const probe = this.probes.get(ch);
+      if (!probe) {
+        results.push(this.unsupportedSnapshot(ch));
+        continue;
+      }
+
+      const probeContext: ChannelProbeContext = { assistantId };
+      const localChecks = probe.runLocalChecks(probeContext);
+      let remoteChecks: ReadinessCheckResult[] | undefined;
+      let remoteChecksFreshlyFetched = false;
+      let remoteChecksAffectReadiness = false;
+      let stale = false;
+
+      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(probeContext);
+          remoteChecksFreshlyFetched = true;
+          remoteChecksAffectReadiness = true;
+        } else {
+          // Reuse cached remote checks
+          remoteChecks = cached.remoteChecks;
+          remoteChecksAffectReadiness = true;
+        }
+      } else if (cached?.remoteChecks) {
+        // 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 && remoteChecksAffectReadiness)
+        ? remoteChecks.every((c) => c.passed)
+        : true;
+      const ready = allLocalPassed && allRemotePassed;
+
+      const reasons: Array<{ code: string; text: string }> = [];
+      for (const check of localChecks) {
+        if (!check.passed) {
+          reasons.push({ code: check.name, text: check.message });
+        }
+      }
+      if (remoteChecks && remoteChecksAffectReadiness) {
+        for (const check of remoteChecks) {
+          if (!check.passed) {
+            reasons.push({ code: check.name, text: check.message });
+          }
+        }
+      }
+
+      const snapshot: ChannelReadinessSnapshot = {
+        channel: ch,
+        ready,
+        checkedAt: (remoteChecks && cached && !remoteChecksFreshlyFetched) ? cached.checkedAt : now,
+        stale,
+        reasons,
+        localChecks,
+        remoteChecks,
+      };
+
+      this.snapshots.set(cacheKey, snapshot);
+      results.push(snapshot);
+    }
+
+    return results;
+  }
+
+  /** Clear cached snapshot for a specific channel, forcing re-evaluation on next call. */
+  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. */
+  invalidateAll(): void {
+    this.snapshots.clear();
+  }
+
+  private unsupportedSnapshot(channel: ChannelId): ChannelReadinessSnapshot {
+    return {
+      channel,
+      ready: false,
+      checkedAt: Date.now(),
+      stale: false,
+      reasons: [{ code: 'unsupported_channel', text: `Channel ${channel} is not supported` }],
+      localChecks: [],
+    };
+  }
+
+  private snapshotCacheKey(channel: ChannelId, assistantId?: string): string {
+    return `${channel}::${assistantId ?? '__default__'}`;
+  }
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+/** 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

@@ -0,0 +1,35 @@
+// Channel readiness types — reusable primitive for all channels.
+
+import type { ChannelId } from '../channels/types.js';
+
+export type { ChannelId };
+
+/** Result of a single readiness check (local or remote). */
+export interface ReadinessCheckResult {
+  name: string;
+  passed: boolean;
+  message: string;
+}
+
+/** Point-in-time snapshot of a channel's readiness state. */
+export interface ChannelReadinessSnapshot {
+  channel: ChannelId;
+  ready: boolean;
+  checkedAt: number;
+  stale: boolean;
+  reasons: Array<{ code: string; text: string }>;
+  localChecks: ReadinessCheckResult[];
+  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(context?: ChannelProbeContext): ReadinessCheckResult[];
+  runRemoteChecks?(context?: ChannelProbeContext): Promise<ReadinessCheckResult[]>;
+}

package/src/runtime/channel-retry-sweep.ts

@@ -0,0 +1,184 @@
+/**
+ * Periodic retry sweep for failed channel inbound events.
+ */
+
+import { parseChannelId, isChannelId } from '../channels/types.js';
+import { getLogger } from '../util/logger.js';
+import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
+import * as conversationStore from '../memory/conversation-store.js';
+import * as attachmentsStore from '../memory/attachments-store.js';
+import { renderHistoryContent } from '../daemon/handlers.js';
+import { deliverChannelReply } from './gateway-client.js';
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import type { MessageProcessor } from './http-types.js';
+
+const log = getLogger('runtime-http');
+
+function parseGuardianRuntimeContext(value: unknown): GuardianRuntimeContext | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const raw = value as Record<string, unknown>;
+  const actorRole = raw.actorRole;
+  if (
+    actorRole !== 'guardian'
+    && actorRole !== 'non-guardian'
+    && actorRole !== 'unverified_channel'
+  ) {
+    return undefined;
+  }
+  const rawSourceChannel = typeof raw.sourceChannel === 'string' && raw.sourceChannel.trim().length > 0
+    ? raw.sourceChannel
+    : undefined;
+  if (!rawSourceChannel || !isChannelId(rawSourceChannel)) return undefined;
+  const sourceChannel = rawSourceChannel;
+  const denialReason =
+    raw.denialReason === 'no_binding' || raw.denialReason === 'no_identity'
+      ? raw.denialReason
+      : undefined;
+  return {
+    sourceChannel,
+    actorRole,
+    guardianChatId: typeof raw.guardianChatId === 'string' ? raw.guardianChatId : undefined,
+    guardianExternalUserId: typeof raw.guardianExternalUserId === 'string' ? raw.guardianExternalUserId : undefined,
+    requesterIdentifier: typeof raw.requesterIdentifier === 'string' ? raw.requesterIdentifier : undefined,
+    requesterExternalUserId: typeof raw.requesterExternalUserId === 'string' ? raw.requesterExternalUserId : undefined,
+    requesterChatId: typeof raw.requesterChatId === 'string' ? raw.requesterChatId : undefined,
+    denialReason,
+  };
+}
+
+/**
+ * Periodically retry failed channel inbound events that have passed
+ * their exponential backoff delay.
+ */
+export async function sweepFailedEvents(
+  processMessage: MessageProcessor,
+  bearerToken: string | undefined,
+): Promise<void> {
+  const events = channelDeliveryStore.getRetryableEvents();
+  if (events.length === 0) return;
+
+  log.info({ count: events.length }, 'Retrying failed channel inbound events');
+
+  for (const event of events) {
+    if (!event.rawPayload) {
+      // No payload stored -- can't replay, move to dead letter
+      channelDeliveryStore.recordProcessingFailure(
+        event.id,
+        new Error('No raw payload stored for replay'),
+      );
+      continue;
+    }
+
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(event.rawPayload) as Record<string, unknown>;
+    } catch {
+      channelDeliveryStore.recordProcessingFailure(
+        event.id,
+        new Error('Failed to parse stored raw payload'),
+      );
+      continue;
+    }
+
+    const content = typeof payload.content === 'string' ? payload.content.trim() : '';
+    const attachmentIds = Array.isArray(payload.attachmentIds) ? payload.attachmentIds as string[] : undefined;
+    const sourceChannel = parseChannelId(payload.sourceChannel);
+    if (!sourceChannel) {
+      channelDeliveryStore.recordProcessingFailure(
+        event.id,
+        new Error(`Invalid sourceChannel: ${String(payload.sourceChannel)}`),
+      );
+      continue;
+    }
+    const sourceMetadata = payload.sourceMetadata as Record<string, unknown> | undefined;
+    const assistantId = typeof payload.assistantId === 'string'
+      ? payload.assistantId
+      : undefined;
+    const guardianContext = parseGuardianRuntimeContext(payload.guardianCtx);
+
+    const metadataHintsRaw = sourceMetadata?.hints;
+    const metadataHints = Array.isArray(metadataHintsRaw)
+      ? metadataHintsRaw.filter((h): h is string => typeof h === 'string' && h.trim().length > 0)
+      : [];
+    const metadataUxBrief = typeof sourceMetadata?.uxBrief === 'string' && sourceMetadata.uxBrief.trim().length > 0
+      ? sourceMetadata.uxBrief.trim()
+      : undefined;
+
+    try {
+      const { messageId: userMessageId } = await processMessage(
+        event.conversationId,
+        content,
+        attachmentIds,
+        {
+          transport: {
+            channelId: sourceChannel,
+            hints: metadataHints.length > 0 ? metadataHints : undefined,
+            uxBrief: metadataUxBrief,
+          },
+          assistantId,
+          guardianContext,
+        },
+      );
+      channelDeliveryStore.linkMessage(event.id, userMessageId);
+      channelDeliveryStore.markProcessed(event.id);
+      log.info({ eventId: event.id }, 'Successfully replayed failed channel event');
+
+      const replyCallbackUrl = typeof payload.replyCallbackUrl === 'string'
+        ? payload.replyCallbackUrl
+        : undefined;
+      if (replyCallbackUrl) {
+        const externalChatId = typeof payload.externalChatId === 'string'
+          ? payload.externalChatId
+          : undefined;
+        if (externalChatId) {
+          await deliverReplyViaCallback(
+            event.conversationId,
+            externalChatId,
+            replyCallbackUrl,
+            bearerToken,
+            assistantId,
+          );
+        }
+      }
+    } catch (err) {
+      log.error({ err, eventId: event.id }, 'Retry failed for channel event');
+      channelDeliveryStore.recordProcessingFailure(event.id, err);
+    }
+  }
+}
+
+async function deliverReplyViaCallback(
+  conversationId: string,
+  externalChatId: string,
+  callbackUrl: string,
+  bearerToken: string | undefined,
+  assistantId?: string,
+): Promise<void> {
+  const msgs = conversationStore.getMessages(conversationId);
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    if (msgs[i].role === 'assistant') {
+      let parsed: unknown;
+      try { parsed = JSON.parse(msgs[i].content); } catch { parsed = msgs[i].content; }
+      const rendered = renderHistoryContent(parsed);
+
+      const linked = attachmentsStore.getAttachmentMetadataForMessage(msgs[i].id);
+      const replyAttachments = linked.map((a) => ({
+        id: a.id,
+        filename: a.originalFilename,
+        mimeType: a.mimeType,
+        sizeBytes: a.sizeBytes,
+        kind: a.kind,
+      }));
+
+      if (rendered.text || replyAttachments.length > 0) {
+        await deliverChannelReply(callbackUrl, {
+          chatId: externalChatId,
+          text: rendered.text || undefined,
+          attachments: replyAttachments.length > 0 ? replyAttachments : undefined,
+          assistantId,
+        }, bearerToken);
+      }
+      break;
+    }
+  }
+}