@vellumai/assistant 0.3.3 → 0.3.5

package/src/runtime/channel-approvals.ts

@@ -13,6 +13,7 @@
 import { getPendingConfirmationsByConversation, getRun } from '../memory/runs-store.js';
 import type { PendingRunInfo } from '../memory/runs-store.js';
 import { addRule } from '../permissions/trust-store.js';
+import { getTool } from '../tools/registry.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 import { DEFAULT_APPROVAL_ACTIONS } from './channel-approval-types.js';
 import type {
@@ -20,6 +21,7 @@ import type {
   ApprovalUIMetadata,
   ApprovalDecisionResult,
 } from './channel-approval-types.js';
+import { composeApprovalMessage } from './approval-message-composer.js';
 
 // ---------------------------------------------------------------------------
 // 1. Detect pending confirmations and build prompt
@@ -46,13 +48,17 @@ export function getChannelApprovalPrompt(
  * Internal helper: turn a PendingRunInfo into a ChannelApprovalPrompt.
  */
 function buildPromptFromRunInfo(info: PendingRunInfo): ChannelApprovalPrompt {
-  const promptText = `The assistant wants to use the tool "${info.toolName}". Do you want to allow this?`;
+  const promptText = composeApprovalMessage({
+    scenario: 'standard_prompt',
+    toolName: info.toolName,
+  });
 
   // Hide "approve always" when persistent trust rules are disallowed for this invocation.
   const actions = info.persistentDecisionsAllowed === false
     ? DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always')
     : [...DEFAULT_APPROVAL_ACTIONS];
 
+  // Plain-text fallback must remain parser-compatible (contains "yes"/"always"/"no" keywords).
   const plainTextFallback = info.persistentDecisionsAllowed === false
     ? `${promptText}\n\nReply "yes" to approve or "no" to reject.`
     : `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`;
@@ -101,11 +107,17 @@ export function handleChannelDecision(
   conversationId: string,
   decision: ApprovalDecisionResult,
   orchestrator: RunOrchestrator,
+  decisionContext?: string,
 ): HandleDecisionResult {
   const pending = getPendingConfirmationsByConversation(conversationId);
   if (pending.length === 0) return { applied: false };
 
-  const info = pending[0];
+  // Callback-based decisions include a run ID and must resolve to that exact
+  // pending confirmation. Plain-text decisions still apply to the first prompt.
+  const info = decision.runId
+    ? pending.find((candidate) => candidate.runId === decision.runId)
+    : pending[0];
+  if (!info) return { applied: false };
 
   if (decision.action === 'approve_always') {
     // Only persist a trust rule when the confirmation explicitly allows persistence
@@ -121,8 +133,13 @@ export function handleChannelDecision(
     ) {
       const pattern = confirmation.allowlistOptions[0].pattern;
       const scope = confirmation.scopeOptions[0].scope;
+      // Only persist executionTarget for skill-origin tools — core tools don't
+      // set it in their PolicyContext, so a persisted value would prevent the
+      // rule from ever matching on subsequent permission checks.
+      const tool = getTool(confirmation.toolName);
+      const executionTarget = tool?.origin === 'skill' ? confirmation.executionTarget : undefined;
       addRule(confirmation.toolName, pattern, scope, 'allow', 100, {
-        executionTarget: confirmation.executionTarget,
+        executionTarget,
       });
     }
     // When persistence is not allowed or options are missing, the decision
@@ -131,7 +148,9 @@ export function handleChannelDecision(
 
   // Map channel-level action to the permission system's UserDecision type.
   const userDecision = decision.action === 'reject' ? 'deny' as const : 'allow' as const;
-  const result = orchestrator.submitDecision(info.runId, userDecision);
+  const result = decisionContext === undefined
+    ? orchestrator.submitDecision(info.runId, userDecision)
+    : orchestrator.submitDecision(info.runId, userDecision, decisionContext);
 
   return {
     applied: result === 'applied',
@@ -152,8 +171,11 @@ export function buildGuardianApprovalPrompt(
   info: PendingRunInfo,
   requesterIdentifier: string,
 ): ChannelApprovalPrompt {
-  const promptText =
-    `User ${requesterIdentifier} is requesting to run "${info.toolName}". Approve or deny?`;
+  const promptText = composeApprovalMessage({
+    scenario: 'guardian_prompt',
+    toolName: info.toolName,
+    requesterIdentifier,
+  });
 
   // Guardian approvals are always one-time decisions — "approve always"
   // doesn't make sense when the guardian is approving on behalf of someone else.
@@ -197,7 +219,7 @@ export function channelSupportsRichApprovalUI(channel: string): boolean {
 export function buildReminderPrompt(
   pendingPrompt: ChannelApprovalPrompt,
 ): ChannelApprovalPrompt {
-  const reminderPrefix = "I'm still waiting for your decision on the previous request.";
+  const reminderPrefix = composeApprovalMessage({ scenario: 'reminder_prompt' });
   return {
     promptText: `${reminderPrefix}\n\n${pendingPrompt.promptText}`,
     actions: pendingPrompt.actions,

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/gateway-client.ts

@@ -52,7 +52,8 @@ export async function deliverApprovalPrompt(
   chatId: string,
   text: string,
   approval: ApprovalUIMetadata,
+  assistantId?: string,
   bearerToken?: string,
 ): Promise<void> {
-  await deliverChannelReply(callbackUrl, { chatId, text, approval }, bearerToken);
+  await deliverChannelReply(callbackUrl, { chatId, text, approval, assistantId }, bearerToken);
 }