@vellumai/assistant 0.3.4 → 0.3.5

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

@@ -20,6 +20,7 @@ import {
   resetRateLimit,
 } from '../memory/channel-guardian-store.js';
 import type { GuardianBinding } from '../memory/channel-guardian-store.js';
+import { composeApprovalMessage } from './approval-message-composer.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -44,6 +45,8 @@ const RATE_LIMIT_LOCKOUT_MS = 30 * 60 * 1000;
 export interface CreateChallengeResult {
   challengeId: string;
   secret: string;
+  verifyCommand: string;
+  ttlSeconds: number;
   instruction: string;
 }
 
@@ -63,19 +66,6 @@ function hashSecret(secret: string): string {
 // Service
 // ---------------------------------------------------------------------------
 
-/**
- * Build a human-readable channel label for use in guardian challenge
- * instructions. Avoids hardcoding "Telegram" so SMS and future
- * channels get appropriate wording.
- */
-function channelLabel(channel: string): string {
-  switch (channel) {
-    case 'telegram': return 'Telegram';
-    case 'sms': return 'SMS';
-    default: return channel;
-  }
-}
-
 /**
  * Create a new verification challenge for a guardian candidate.
  *
@@ -102,12 +92,19 @@ export function createVerificationChallenge(
     createdBySessionId: sessionId,
   });
 
-  const label = channelLabel(channel);
+  const verifyCommand = `/guardian_verify ${secret}`;
+  const ttlSeconds = CHALLENGE_TTL_MS / 1000;
 
   return {
     challengeId,
     secret,
-    instruction: `Send \`/guardian_verify ${secret}\` to your bot via ${label} within 10 minutes.`,
+    verifyCommand,
+    ttlSeconds,
+    instruction: composeApprovalMessage({
+      scenario: 'guardian_verify_challenge_setup',
+      verifyCommand,
+      ttlSeconds,
+    }),
   };
 }
 
@@ -129,13 +126,21 @@ export function validateAndConsumeChallenge(
   secret: string,
   actorExternalUserId: string,
   actorChatId: string,
+  actorUsername?: string,
+  actorDisplayName?: string,
 ): ValidateChallengeResult {
   // ── Rate-limit check ──
   const existing = getRateLimit(assistantId, channel, actorExternalUserId, actorChatId);
   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 { success: false, reason: 'Verification failed. Please try again later.' };
+    return {
+      success: false,
+      reason: composeApprovalMessage({
+        scenario: 'guardian_verify_failed',
+        failureReason: 'The verification code is invalid or has expired.',
+      }),
+    };
   }
 
   const challengeHash = hashSecret(secret);
@@ -146,7 +151,13 @@ export function validateAndConsumeChallenge(
       assistantId, channel, actorExternalUserId, actorChatId,
       RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX_ATTEMPTS, RATE_LIMIT_LOCKOUT_MS,
     );
-    return { success: false, reason: 'Verification failed. Please try again later.' };
+    return {
+      success: false,
+      reason: composeApprovalMessage({
+        scenario: 'guardian_verify_failed',
+        failureReason: 'The verification code is invalid or has expired.',
+      }),
+    };
   }
 
   if (Date.now() > challenge.expiresAt) {
@@ -154,7 +165,13 @@ export function validateAndConsumeChallenge(
       assistantId, channel, actorExternalUserId, actorChatId,
       RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX_ATTEMPTS, RATE_LIMIT_LOCKOUT_MS,
     );
-    return { success: false, reason: 'Verification failed. Please try again later.' };
+    return {
+      success: false,
+      reason: composeApprovalMessage({
+        scenario: 'guardian_verify_failed',
+        failureReason: 'The verification code is invalid or has expired.',
+      }),
+    };
   }
 
   // Consume the challenge so it cannot be reused
@@ -166,6 +183,14 @@ export function validateAndConsumeChallenge(
   // Revoke any existing active binding before creating a new one
   storeRevokeBinding(assistantId, channel);
 
+  const metadata: Record<string, string> = {};
+  if (actorUsername && actorUsername.trim().length > 0) {
+    metadata.username = actorUsername.trim();
+  }
+  if (actorDisplayName && actorDisplayName.trim().length > 0) {
+    metadata.displayName = actorDisplayName.trim();
+  }
+
   // Create the new guardian binding
   const binding = createBinding({
     assistantId,
@@ -173,6 +198,7 @@ export function validateAndConsumeChallenge(
     guardianExternalUserId: actorExternalUserId,
     guardianDeliveryChatId: actorChatId,
     verifiedVia: 'challenge',
+    metadataJson: Object.keys(metadata).length > 0 ? JSON.stringify(metadata) : null,
   });
 
   return { success: true, bindingId: binding.id };

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

@@ -0,0 +1,292 @@
+import type {
+  ChannelId,
+  ChannelProbe,
+  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';
+
+/** 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;
+  }
+}
+
+const smsProbe: ChannelProbe = {
+  channel: 'sms',
+  runLocalChecks(): 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',
+    });
+
+    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');
+    }
+    results.push({
+      name: 'phone_number',
+      passed: hasPhone,
+      message: hasPhone
+        ? 'Phone number is assigned'
+        : '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(): 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
+      || '';
+    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}`,
+      }];
+    }
+  },
+};
+
+// ── 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<ChannelId, 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,
+  ): 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 localChecks = probe.runLocalChecks();
+      let remoteChecks: ReadinessCheckResult[] | undefined;
+      let remoteChecksFreshlyFetched = false;
+      let stale = false;
+
+      const cached = this.snapshots.get(ch);
+      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();
+          remoteChecksFreshlyFetched = true;
+        } else {
+          // Reuse cached remote checks
+          remoteChecks = cached.remoteChecks;
+        }
+      } else if (cached?.remoteChecks) {
+        // Surface cached remote checks even when not explicitly requested,
+        // but mark stale if TTL has elapsed
+        remoteChecks = cached.remoteChecks;
+        stale = (now - cached.checkedAt) >= REMOTE_TTL_MS;
+      }
+
+      const allLocalPassed = localChecks.every((c) => c.passed);
+      const allRemotePassed = remoteChecks ? 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) {
+        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(ch, snapshot);
+      results.push(snapshot);
+    }
+
+    return results;
+  }
+
+  /** Clear cached snapshot for a specific channel, forcing re-evaluation on next call. */
+  invalidateChannel(channel: ChannelId): void {
+    this.snapshots.delete(channel);
+  }
+
+  /** 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: [],
+    };
+  }
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+/** Create a service instance with built-in SMS and Telegram probes registered. */
+export function createReadinessService(): ChannelReadinessService {
+  const service = new ChannelReadinessService();
+  service.registerProbe(smsProbe);
+  service.registerProbe(telegramProbe);
+  return service;
+}

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

@@ -0,0 +1,29 @@
+// 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;
+
+/** 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[];
+}
+
+/** Probe interface that channels implement to provide readiness checks. */
+export interface ChannelProbe {
+  channel: ChannelId;
+  runLocalChecks(): ReadinessCheckResult[];
+  runRemoteChecks?(): Promise<ReadinessCheckResult[]>;
+}

package/src/runtime/http-server.ts

@@ -11,7 +11,7 @@ import { fileURLToPath } from 'node:url';
 import { timingSafeEqual } from 'node:crypto';
 import { ConfigError, IngressBlockedError } from '../util/errors.js';
 import { getLogger } from '../util/logger.js';
-import { getWorkspacePromptPath } from '../util/platform.js';
+import { getWorkspacePromptPath, readLockfile } from '../util/platform.js';
 import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
 import { loadConfig } from '../config/loader.js';
 import { getPublicBaseUrl } from '../inbound/public-ingress-urls.js';
@@ -74,6 +74,7 @@ import { RelayConnection, activeRelayConnections } from '../calls/relay-server.j
 import type { RelayWebSocketData } from '../calls/relay-server.js';
 import { handleSubscribeAssistantEvents } from './routes/events-routes.js';
 import { consumeCallback, consumeCallbackError } from '../security/oauth-callback-registry.js';
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 
 // Re-export shared types so existing consumers don't need to update imports
 export type {
@@ -107,6 +108,37 @@ function getGatewayBaseUrl(): string {
 /** Global hard cap on request body size (50 MB). Bun rejects larger payloads before they reach handlers. */
 const MAX_REQUEST_BODY_BYTES = 50 * 1024 * 1024;
 
+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 sourceChannel = typeof raw.sourceChannel === 'string' && raw.sourceChannel.trim().length > 0
+    ? raw.sourceChannel
+    : undefined;
+  if (!sourceChannel) return undefined;
+  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,
+  };
+}
+
 interface DiskSpaceInfo {
   path: string;
   totalMb: number;
@@ -762,7 +794,7 @@ export class RuntimeHttpServer {
 
       // ── Call API routes ───────────────────────────────────────────
       if (endpoint === 'calls/start' && req.method === 'POST') {
-        return await handleStartCall(req);
+        return await handleStartCall(req, assistantId);
       }
 
       // Match calls/:callSessionId and calls/:callSessionId/cancel, calls/:callSessionId/answer, calls/:callSessionId/instruction
@@ -907,6 +939,10 @@ export class RuntimeHttpServer {
       const attachmentIds = Array.isArray(payload.attachmentIds) ? payload.attachmentIds as string[] : undefined;
       const sourceChannel = payload.sourceChannel as string;
       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)
@@ -927,6 +963,8 @@ export class RuntimeHttpServer {
               hints: metadataHints.length > 0 ? metadataHints : undefined,
               uxBrief: metadataUxBrief,
             },
+            assistantId,
+            guardianContext,
           },
         );
         channelDeliveryStore.linkMessage(event.id, userMessageId);
@@ -940,9 +978,6 @@ export class RuntimeHttpServer {
           const externalChatId = typeof payload.externalChatId === 'string'
             ? payload.externalChatId
             : undefined;
-          const assistantId = typeof payload.assistantId === 'string'
-            ? payload.assistantId
-            : undefined;
           if (externalChatId) {
             await this.deliverReplyViaCallback(
               event.conversationId,
@@ -1046,28 +1081,19 @@ export class RuntimeHttpServer {
     let cloud: string | undefined;
     let originSystem: string | undefined;
     try {
-      const homedir = process.env.HOME ?? process.env.USERPROFILE ?? '';
-      const lockfilePaths = [
-        join(homedir, '.vellum.lock.json'),
-        join(homedir, '.vellum.lockfile.json'),
-      ];
-      for (const lockPath of lockfilePaths) {
-        if (!existsSync(lockPath)) continue;
-        const lockData = JSON.parse(readFileSync(lockPath, 'utf-8'));
-        const assistants = lockData.assistants as Array<Record<string, unknown>> | undefined;
-        if (assistants && assistants.length > 0) {
-          // Use the most recently hatched assistant
-          const sorted = [...assistants].sort((a, b) => {
-            const dateA = new Date(a.hatchedAt as string || 0).getTime();
-            const dateB = new Date(b.hatchedAt as string || 0).getTime();
-            return dateB - dateA;
-          });
-          const latest = sorted[0];
-          assistantId = latest.assistantId as string | undefined;
-          cloud = latest.cloud as string | undefined;
-          originSystem = cloud === 'local' ? 'local' : cloud;
-        }
-        break;
+      const lockData = readLockfile();
+      const assistants = lockData?.assistants as Array<Record<string, unknown>> | undefined;
+      if (assistants && assistants.length > 0) {
+        // Use the most recently hatched assistant
+        const sorted = [...assistants].sort((a, b) => {
+          const dateA = new Date(a.hatchedAt as string || 0).getTime();
+          const dateB = new Date(b.hatchedAt as string || 0).getTime();
+          return dateB - dateA;
+        });
+        const latest = sorted[0];
+        assistantId = latest.assistantId as string | undefined;
+        cloud = latest.cloud as string | undefined;
+        originSystem = cloud === 'local' ? 'local' : cloud;
       }
     } catch {
       // ignore — lockfile may not exist

package/src/runtime/http-types.ts

@@ -2,6 +2,7 @@
  * Shared types for the runtime HTTP server and its route handlers.
  */
 import type { RunOrchestrator } from './run-orchestrator.js';
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 
 export interface RuntimeMessageSessionOptions {
   transport?: {
@@ -9,6 +10,8 @@ export interface RuntimeMessageSessionOptions {
     hints?: string[];
     uxBrief?: string;
   };
+  assistantId?: string;
+  guardianContext?: GuardianRuntimeContext;
 }
 
 export type MessageProcessor = (

package/src/runtime/routes/call-routes.ts

@@ -17,7 +17,7 @@ import { VALID_CALLER_IDENTITY_MODES } from '../../config/schema.js';
  *
  * Body: { phoneNumber: string; task: string; context?: string; conversationId: string; callerIdentityMode?: 'assistant_number' | 'user_number' }
  */
-export async function handleStartCall(req: Request): Promise<Response> {
+export async function handleStartCall(req: Request, assistantId: string = 'self'): Promise<Response> {
   if (!getConfig().calls.enabled) {
     return Response.json(
       { error: 'Calls feature is disabled via configuration. Set calls.enabled to true to use this feature.' },
@@ -59,6 +59,7 @@ export async function handleStartCall(req: Request): Promise<Response> {
     task: body.task ?? '',
     context: body.context,
     conversationId: body.conversationId,
+    assistantId,
     callerIdentityMode: body.callerIdentityMode,
   });