@vellumai/assistant 0.3.4 → 0.3.6

package/src/runtime/approval-message-composer.ts

@@ -0,0 +1,253 @@
+/**
+ * Layered approval message composition system.
+ *
+ * Generates approval prompt text through a priority chain:
+ *   1. Assistant preface (macOS parity — reuse existing assistant text)
+ *   2. Generator-produced rewrite of deterministic fallback text (when provided by daemon)
+ *   3. Deterministic fallback templates (natural, scenario-specific messages)
+ */
+import { getLogger } from '../util/logger.js';
+import type { ApprovalCopyGenerator } from './http-types.js';
+
+const log = getLogger('approval-message-composer');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ApprovalMessageScenario =
+  | 'standard_prompt'
+  | 'guardian_prompt'
+  | 'reminder_prompt'
+  | 'guardian_delivery_failed'
+  | 'guardian_request_forwarded'
+  | 'guardian_disambiguation'
+  | 'guardian_identity_mismatch'
+  | 'request_pending_guardian'
+  | 'guardian_decision_outcome'
+  | 'guardian_expired_requester'
+  | 'guardian_expired_guardian'
+  | 'guardian_verify_success'
+  | 'guardian_verify_failed'
+  | 'guardian_verify_challenge_setup'
+  | 'guardian_verify_status_bound'
+  | 'guardian_verify_status_unbound'
+  | 'guardian_deny_no_identity'
+  | 'guardian_deny_no_binding'
+  | 'requester_cancel'
+  | 'approval_already_resolved';
+
+export interface ApprovalMessageContext {
+  scenario: ApprovalMessageScenario;
+  channel?: string;
+  toolName?: string;
+  requesterIdentifier?: string;
+  guardianIdentifier?: string;
+  pendingCount?: number;
+  decision?: 'approved' | 'denied';
+  richUi?: boolean;
+  /** Pre-existing assistant text to reuse (macOS parity). */
+  assistantPreface?: string;
+  verifyCommand?: string;
+  ttlSeconds?: number;
+  failureReason?: string;
+}
+
+export interface ComposeApprovalMessageGenerativeOptions {
+  /**
+   * Optional fallback message to use when generation fails. If omitted,
+   * the deterministic scenario fallback is used.
+   */
+  fallbackText?: string;
+  /**
+   * Require these standalone words in the generated output (case-insensitive).
+   * Useful for plain-text decision flows where parser-compatible keywords
+   * like yes/no/always must be present.
+   */
+  requiredKeywords?: string[];
+  timeoutMs?: number;
+  maxTokens?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose an approval message using layered source selection:
+ *   1. If an assistant preface is provided and non-empty, return it directly.
+ *   2. Otherwise fall back to a deterministic scenario-specific template.
+ */
+export function composeApprovalMessage(context: ApprovalMessageContext): string {
+  if (context.assistantPreface && context.assistantPreface.trim().length > 0) {
+    return context.assistantPreface;
+  }
+
+  return getFallbackMessage(context);
+}
+
+/** @internal Exported for use by the daemon-injected generator implementation. */
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** @internal Exported for use by the daemon-injected generator implementation. */
+export function includesRequiredKeywords(text: string, requiredKeywords: string[] | undefined): boolean {
+  if (!requiredKeywords || requiredKeywords.length === 0) return true;
+  return requiredKeywords.every((keyword) => {
+    const re = new RegExp(`\\b${escapeRegExp(keyword)}\\b`, 'i');
+    return re.test(text);
+  });
+}
+
+/** @internal Exported for use by the daemon-injected generator implementation. */
+export function buildGenerationPrompt(
+  context: ApprovalMessageContext,
+  fallbackText: string,
+  requiredKeywords: string[] | undefined,
+): string {
+  const keywordClause = requiredKeywords && requiredKeywords.length > 0
+    ? `Required words to include (as standalone words): ${requiredKeywords.join(', ')}.\n`
+    : '';
+  return [
+    'Rewrite the following approval/guardian message as a natural assistant reply to the user.',
+    'Keep the same concrete facts and next-step guidance.',
+    keywordClause,
+    `Context JSON: ${JSON.stringify(context)}`,
+    `Fallback message: ${fallbackText}`,
+  ].filter(Boolean).join('\n\n');
+}
+
+/** Constants for the generator implementation (moved to exports for daemon lifecycle). */
+export const APPROVAL_COPY_TIMEOUT_MS = 4_000;
+export const APPROVAL_COPY_MAX_TOKENS = 180;
+export const APPROVAL_COPY_SYSTEM_PROMPT =
+  'You are an assistant writing one user-facing message about permissions/approval state. '
+  + 'Keep it concise, natural, and actionable. Preserve factual details exactly. '
+  + 'Do not mention internal systems, scenario IDs, or policy engine details. '
+  + 'Return plain text only.';
+
+/**
+ * Compose user-facing approval copy using the daemon-injected generator when
+ * available, with deterministic fallback for reliability.
+ *
+ * The generator parameter is the daemon-provided function that knows about
+ * providers. When absent (or in test env), only the deterministic fallback
+ * is used.
+ */
+export async function composeApprovalMessageGenerative(
+  context: ApprovalMessageContext,
+  options: ComposeApprovalMessageGenerativeOptions = {},
+  generator?: ApprovalCopyGenerator,
+): Promise<string> {
+  if (context.assistantPreface && context.assistantPreface.trim().length > 0) {
+    return context.assistantPreface;
+  }
+
+  const fallbackText = options.fallbackText?.trim() || getFallbackMessage(context);
+
+  if (process.env.NODE_ENV === 'test') {
+    return fallbackText;
+  }
+
+  if (generator) {
+    try {
+      const generated = await generator(context, options);
+      if (generated) return generated;
+    } catch (err) {
+      log.warn({ err, scenario: context.scenario }, 'Failed to generate approval copy, using fallback');
+    }
+  }
+
+  return fallbackText;
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic fallback templates
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a scenario-specific deterministic fallback message.
+ *
+ * Each template is slightly more conversational than the old hard-coded
+ * strings while preserving all required semantic content (tool name,
+ * who must approve, next action, etc.).
+ */
+export function getFallbackMessage(context: ApprovalMessageContext): string {
+  switch (context.scenario) {
+    case 'standard_prompt':
+      return `I'd like to use the tool "${context.toolName ?? 'unknown'}". Would you like to allow this?`;
+
+    case 'guardian_prompt':
+      return `${context.requesterIdentifier ?? 'A user'} is requesting to use "${context.toolName ?? 'unknown'}". Please approve or deny this request.`;
+
+    case 'reminder_prompt':
+      return 'There is a pending approval request. Ask a follow-up question or say approve/deny when you are ready.';
+
+    case 'guardian_delivery_failed':
+      return context.toolName
+        ? `Your request to run "${context.toolName}" could not be sent to the guardian for approval. The request has been denied for safety.`
+        : "I wasn't able to reach the guardian to request approval. The request has been denied for safety.";
+
+    case 'guardian_request_forwarded':
+      return `Your request to use "${context.toolName ?? 'unknown'}" has been forwarded to the guardian for approval. I'll let you know once they decide.`;
+
+    case 'guardian_disambiguation':
+      return `There are ${context.pendingCount ?? 'multiple'} pending approval requests. Please use the approval buttons to specify which request you're responding to.`;
+
+    case 'guardian_identity_mismatch':
+      return 'This approval request can only be handled by the designated guardian.';
+
+    case 'request_pending_guardian':
+      return 'Your request is pending guardian approval. Please wait for the guardian to respond.';
+
+    case 'guardian_decision_outcome':
+      return `The guardian has ${context.decision ?? 'decided on'} your request to use "${context.toolName ?? 'unknown'}".`;
+
+    case 'guardian_expired_requester':
+      return `The approval request for "${context.toolName ?? 'unknown'}" has expired without a guardian response. The request has been denied.`;
+
+    case 'guardian_expired_guardian':
+      return `The approval request from ${context.requesterIdentifier ?? 'the requester'} for "${context.toolName ?? 'unknown'}" has expired.`;
+
+    case 'guardian_verify_success':
+      return 'Guardian verification successful! You are now set as the guardian for this channel.';
+
+    case 'guardian_verify_failed':
+      return `Verification failed. ${context.failureReason ?? 'Please try again.'}`;
+
+    case 'guardian_verify_challenge_setup':
+      if (context.channel === 'voice') {
+        // Voice challenges use a six-digit numeric code that can be spoken aloud
+        const code = context.verifyCommand?.replace('/guardian_verify ', '') ?? 'the verification code';
+        return `To complete guardian verification, speak or enter the six-digit code: ${code}. This code expires in ${Math.round((context.ttlSeconds ?? 600) / 60)} minutes.`;
+      }
+      return `To complete guardian verification, send ${context.verifyCommand ?? 'the verification command'} within ${context.ttlSeconds ?? 60} seconds.`;
+
+    case 'guardian_verify_status_bound':
+      return 'A guardian is currently active for this channel.';
+
+    case 'guardian_verify_status_unbound':
+      return 'No guardian is currently configured for this channel.';
+
+    case 'guardian_deny_no_identity':
+      return 'This action requires approval, but your identity could not be verified. The request has been denied for safety.';
+
+    case 'guardian_deny_no_binding':
+      return 'This action requires guardian approval, but no guardian has been configured for this channel. The request has been denied for safety.';
+
+    case 'requester_cancel':
+      return context.toolName
+        ? `Your request to use "${context.toolName}" has been cancelled.`
+        : 'Your pending request has been cancelled.';
+
+    case 'approval_already_resolved':
+      return 'This approval request has already been resolved.';
+
+    default: {
+      // Exhaustive check — TypeScript will flag if a scenario is missing.
+      const _exhaustive: never = context.scenario;
+      return `Approval required. ${String(_exhaustive)}`;
+    }
+  }
+}

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';
@@ -21,6 +20,7 @@ import type {
   ApprovalUIMetadata,
   ApprovalDecisionResult,
 } from './channel-approval-types.js';
+import { composeApprovalMessage } from './approval-message-composer.js';
 
 // ---------------------------------------------------------------------------
 // 1. Detect pending confirmations and build prompt
@@ -47,13 +47,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.`;
@@ -166,8 +170,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.
@@ -198,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 = "I'm still waiting for your decision on the previous request.";
-  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,17 @@ 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';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -44,6 +47,8 @@ const RATE_LIMIT_LOCKOUT_MS = 30 * 60 * 1000;
 export interface CreateChallengeResult {
   challengeId: string;
   secret: string;
+  verifyCommand: string;
+  ttlSeconds: number;
   instruction: string;
 }
 
@@ -64,31 +69,32 @@ function hashSecret(secret: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Build a human-readable channel label for use in guardian challenge
- * instructions. Avoids hardcoding "Telegram" so SMS and future
- * channels get appropriate wording.
+ * Generate a six-digit numeric secret for voice channel challenges.
+ * Uses cryptographic randomness to pick a number in [100000, 999999].
  */
-function channelLabel(channel: string): string {
-  switch (channel) {
-    case 'telegram': return 'Telegram';
-    case 'sms': return 'SMS';
-    default: return channel;
-  }
+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,12 +108,20 @@ 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',
+      channel,
+      verifyCommand,
+      ttlSeconds,
+    }),
   };
 }
 
@@ -129,13 +143,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) {
+  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 +168,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 +182,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 +200,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 +215,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 };
@@ -198,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;
 }
 
 /**
@@ -210,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);
+}