@vellumai/assistant 0.3.13 → 0.3.14

package/src/notifications/decision-engine.ts

@@ -18,7 +18,7 @@ import type { ModelIntent } from '../providers/types.js';
 import { getLogger } from '../util/logger.js';
 import { createDecision } from './decisions-store.js';
 import { getPreferenceSummary } from './preference-summary.js';
-import type { NotificationSignal } from './signal.js';
+import type { NotificationSignal, RoutingIntent } from './signal.js';
 import type { NotificationChannel, NotificationDecision, RenderedChannelCopy } from './types.js';
 
 const log = getLogger('notification-decision-engine');
@@ -56,6 +56,12 @@ function buildSystemPrompt(
     `- For low-urgency background events, suppress unless they match user preferences.`,
     `- Generate a stable dedupeKey derived from the signal context so duplicate signals can be suppressed.`,
     ``,
+    `Routing intent (when present in the signal):`,
+    `- \`all_channels\`: The source explicitly requests notification on ALL connected channels.`,
+    `- \`multi_channel\`: The source prefers 2+ channels when 2+ are connected.`,
+    `- \`single_channel\`: Default routing behavior — use your best judgment (no override).`,
+    `When a routing intent is present, respect it in your channel selection. A post-decision guard will enforce the intent.`,
+    ``,
     `Copy guidelines (three distinct outputs):`,
     `- \`title\` and \`body\` are for native notification popups (e.g. vellum desktop/mobile) — keep them short and glanceable (title ≤ 8 words, body ≤ 2 sentences).`,
     `- \`deliveryText\` is the channel-native message for chat channels (e.g. telegram). It must read naturally as a standalone message.`,
@@ -91,6 +97,14 @@ function buildUserPrompt(signal: NotificationSignal): string {
     parts.push(`Deadline: ${new Date(signal.attentionHints.deadlineAt).toISOString()}`);
   }
 
+  if (signal.routingIntent && signal.routingIntent !== 'single_channel') {
+    parts.push(`Routing intent: ${signal.routingIntent}`);
+  }
+
+  if (signal.routingHints && Object.keys(signal.routingHints).length > 0) {
+    parts.push(`Routing hints: ${JSON.stringify(signal.routingHints)}`);
+  }
+
   const payloadStr = JSON.stringify(signal.contextPayload);
   if (payloadStr.length > 2) {
     parts.push(``, `Context payload:`, payloadStr);
@@ -377,6 +391,61 @@ async function classifyWithLLM(
   }
 }
 
+// ── Post-decision routing intent enforcement ───────────────────────────
+
+/**
+ * Enforce routing intent policy on a decision after the LLM has produced it.
+ * This is a fire-time guard: it overrides channel selection to match the
+ * routing intent specified by the signal source (e.g. a reminder).
+ *
+ * - `all_channels`: force selected channels to all connected channels.
+ * - `multi_channel`: ensure at least 2 channels when 2+ are connected.
+ * - `single_channel`: no override (default behavior).
+ */
+export function enforceRoutingIntent(
+  decision: NotificationDecision,
+  routingIntent: RoutingIntent | undefined,
+  connectedChannels: NotificationChannel[],
+): NotificationDecision {
+  if (!routingIntent || routingIntent === 'single_channel') {
+    return decision;
+  }
+
+  if (!decision.shouldNotify) {
+    return decision;
+  }
+
+  if (routingIntent === 'all_channels') {
+    // Force all connected channels
+    if (connectedChannels.length > 0) {
+      const enforced = { ...decision };
+      enforced.selectedChannels = [...connectedChannels];
+      enforced.reasoningSummary = `${decision.reasoningSummary} [routing_intent=all_channels enforced: ${connectedChannels.join(', ')}]`;
+      log.info(
+        { routingIntent, connectedChannels, originalChannels: decision.selectedChannels },
+        'Routing intent enforcement: all_channels → forced all connected channels',
+      );
+      return enforced;
+    }
+  }
+
+  if (routingIntent === 'multi_channel') {
+    // Ensure at least 2 channels when 2+ are connected
+    if (connectedChannels.length >= 2 && decision.selectedChannels.length < 2) {
+      const enforced = { ...decision };
+      enforced.selectedChannels = [...connectedChannels];
+      enforced.reasoningSummary = `${decision.reasoningSummary} [routing_intent=multi_channel enforced: expanded to ${connectedChannels.join(', ')}]`;
+      log.info(
+        { routingIntent, connectedChannels, originalChannels: decision.selectedChannels },
+        'Routing intent enforcement: multi_channel → expanded to all connected channels',
+      );
+      return enforced;
+    }
+  }
+
+  return decision;
+}
+
 // ── Persistence ────────────────────────────────────────────────────────
 
 function persistDecision(signal: NotificationSignal, decision: NotificationDecision): string | undefined {

package/src/notifications/decisions-store.ts

@@ -79,6 +79,30 @@ export function createDecision(params: CreateDecisionParams): NotificationDecisi
   };
 }
 
+export interface UpdateDecisionParams {
+  selectedChannels?: string[];
+  reasoningSummary?: string;
+  validationResults?: Record<string, unknown>;
+}
+
+/** Update an existing decision row (e.g. after routing intent enforcement). */
+export function updateDecision(id: string, params: UpdateDecisionParams): void {
+  const db = getDb();
+  const updates: Record<string, unknown> = {};
+  if (params.selectedChannels !== undefined) {
+    updates.selectedChannels = JSON.stringify(params.selectedChannels);
+  }
+  if (params.reasoningSummary !== undefined) {
+    updates.reasoningSummary = params.reasoningSummary;
+  }
+  if (params.validationResults !== undefined) {
+    updates.validationResults = JSON.stringify(params.validationResults);
+  }
+  if (Object.keys(updates).length === 0) return;
+
+  db.update(notificationDecisions).set(updates).where(eq(notificationDecisions.id, id)).run();
+}
+
 /** Fetch a single decision by ID. */
 export function getDecisionById(id: string): NotificationDecisionRow | null {
   const db = getDb();

package/src/notifications/destination-resolver.ts

@@ -38,7 +38,8 @@ export function resolveDestinations(
         result.set('vellum', { channel: 'vellum' });
         break;
       }
-      case 'telegram': {
+      case 'telegram':
+      case 'sms': {
         const binding = getActiveBinding(assistantId, channel);
         if (binding) {
           result.set(channel as NotificationChannel, {

package/src/notifications/emit-signal.ts

@@ -15,13 +15,15 @@ import { getDeliverableChannels } from '../channels/config.js';
 import { getActiveBinding } from '../memory/channel-guardian-store.js';
 import { getLogger } from '../util/logger.js';
 import { type BroadcastFn, VellumAdapter } from './adapters/macos.js';
+import { SmsAdapter } from './adapters/sms.js';
 import { TelegramAdapter } from './adapters/telegram.js';
 import { NotificationBroadcaster,type ThreadCreatedInfo } from './broadcaster.js';
-import { evaluateSignal } from './decision-engine.js';
+import { enforceRoutingIntent, evaluateSignal } from './decision-engine.js';
+import { updateDecision } from './decisions-store.js';
 import { type DeterministicCheckContext, runDeterministicChecks } from './deterministic-checks.js';
 import { createEvent, updateEventDedupeKey } from './events-store.js';
 import { dispatchDecision } from './runtime-dispatch.js';
-import type { AttentionHints, NotificationSignal } from './signal.js';
+import type { AttentionHints, NotificationSignal, RoutingIntent } from './signal.js';
 import type { NotificationChannel, NotificationDeliveryResult } from './types.js';
 
 const log = getLogger('emit-signal');
@@ -46,6 +48,7 @@ function getBroadcaster(): NotificationBroadcaster {
   if (!broadcasterInstance) {
     const adapters = [
       new TelegramAdapter(),
+      new SmsAdapter(),
     ];
     if (registeredBroadcastFn) {
       adapters.unshift(new VellumAdapter(registeredBroadcastFn));
@@ -90,6 +93,7 @@ function getConnectedChannels(assistantId: string): NotificationChannel[] {
         channels.push(channel);
         break;
       case 'telegram':
+      case 'sms':
         // Only report binding-based channels as connected when there is
         // an active guardian binding for this assistant. Without a
         // binding, the destination resolver will fail to resolve a
@@ -125,6 +129,10 @@ export interface EmitSignalParams {
   attentionHints: AttentionHints;
   /** Arbitrary context payload passed to the decision engine. */
   contextPayload?: Record<string, unknown>;
+  /** Routing intent from the source (e.g. reminder). Controls post-decision channel enforcement. */
+  routingIntent?: RoutingIntent;
+  /** Free-form hints from the source for the decision engine. */
+  routingHints?: Record<string, unknown>;
   /** Optional deduplication key. */
   dedupeKey?: string;
   /**
@@ -167,6 +175,8 @@ export async function emitNotificationSignal(params: EmitSignalParams): Promise<
     sourceEventName: params.sourceEventName,
     contextPayload: params.contextPayload ?? {},
     attentionHints: params.attentionHints,
+    routingIntent: params.routingIntent,
+    routingHints: params.routingHints,
   };
 
   try {
@@ -195,7 +205,29 @@ export async function emitNotificationSignal(params: EmitSignalParams): Promise<
 
     // Step 2: Evaluate the signal through the decision engine
     const connectedChannels = getConnectedChannels(assistantId);
-    const decision = await evaluateSignal(signal, connectedChannels);
+    let decision = await evaluateSignal(signal, connectedChannels);
+
+    // Step 2.5: Enforce routing intent policy (fire-time guard)
+    const preEnforcementDecision = decision;
+    decision = enforceRoutingIntent(decision, signal.routingIntent, connectedChannels);
+
+    // Re-persist the decision if routing intent enforcement changed it,
+    // so the stored decision row matches what is actually dispatched.
+    if (decision !== preEnforcementDecision && decision.persistedDecisionId) {
+      try {
+        updateDecision(decision.persistedDecisionId, {
+          selectedChannels: decision.selectedChannels,
+          reasoningSummary: decision.reasoningSummary,
+          validationResults: {
+            dedupeKey: decision.dedupeKey,
+            channelCount: decision.selectedChannels.length,
+            hasCopy: Object.keys(decision.renderedCopy).length > 0,
+          },
+        });
+      } catch (err) {
+        log.warn({ err, signalId }, 'Failed to re-persist decision after routing intent enforcement');
+      }
+    }
 
     // Persist model-generated dedupeKey back to the event row so future
     // signals can deduplicate against it (the event was created with

package/src/notifications/signal.ts

@@ -12,6 +12,8 @@ export interface AttentionHints {
   visibleInSourceNow: boolean;
 }
 
+export type RoutingIntent = 'single_channel' | 'multi_channel' | 'all_channels';
+
 export interface NotificationSignal {
   signalId: string;
   assistantId: string;
@@ -21,4 +23,8 @@ export interface NotificationSignal {
   sourceEventName: string; // free-form: 'reminder_fired', 'schedule_complete', 'guardian_question', etc.
   contextPayload: Record<string, unknown>;
   attentionHints: AttentionHints;
+  /** Routing intent from the source (e.g. reminder). Controls post-decision channel enforcement. */
+  routingIntent?: RoutingIntent;
+  /** Free-form hints from the source for the decision engine (e.g. preferred channels). */
+  routingHints?: Record<string, unknown>;
 }

package/src/notifications/types.ts

@@ -54,6 +54,9 @@ export interface ChannelDeliveryPayload {
   /** Delivery audit record ID — passed through to the client for ack correlation. */
   deliveryId?: string;
   sourceEventName: string;
+  /** Originating assistant — used by channel adapters that need assistant-specific
+   *  routing (e.g. SMS outbound number selection via the gateway). */
+  assistantId?: string;
   copy: RenderedChannelCopy;
   deepLinkTarget?: Record<string, unknown>;
 }

package/src/schedule/scheduler.ts

@@ -2,7 +2,7 @@ import { createConversation } from '../memory/conversation-store.js';
 import { GENERATING_TITLE, queueGenerateConversationTitle } from '../memory/conversation-title-service.js';
 import { invalidateAssistantInferredItemsForConversation } from '../memory/task-memory-cleanup.js';
 import { runSequencesOnce } from '../sequence/engine.js';
-import { claimDueReminders, completeReminder, failReminder, setReminderConversationId } from '../tools/reminder/reminder-store.js';
+import { claimDueReminders, completeReminder, failReminder, setReminderConversationId, type RoutingIntent } from '../tools/reminder/reminder-store.js';
 import { getLogger } from '../util/logger.js';
 import { runWatchersOnce, type WatcherEscalator,type WatcherNotifier } from '../watcher/engine.js';
 import { hasSetConstructs } from './recurrence-engine.js';
@@ -19,7 +19,13 @@ export type ScheduleMessageProcessor = (
   message: string,
 ) => Promise<unknown>;
 
-export type ReminderNotifier = (reminder: { id: string; label: string; message: string }) => void;
+export type ReminderNotifier = (reminder: {
+  id: string;
+  label: string;
+  message: string;
+  routingIntent: RoutingIntent;
+  routingHints: Record<string, unknown>;
+}) => void;
 
 export type ScheduleNotifier = (schedule: { id: string; name: string }) => void;
 
@@ -165,7 +171,13 @@ async function runScheduleOnce(
     } else {
       try {
         log.info({ reminderId: reminder.id, label: reminder.label }, 'Firing reminder notification');
-        notifyReminder({ id: reminder.id, label: reminder.label, message: reminder.message });
+        notifyReminder({
+          id: reminder.id,
+          label: reminder.label,
+          message: reminder.message,
+          routingIntent: reminder.routingIntent,
+          routingHints: reminder.routingHints,
+        });
         completeReminder(reminder.id);
       } catch (err) {
         log.warn({ err, reminderId: reminder.id }, 'Reminder notification failed, reverting to pending');

package/src/tools/executor.ts

@@ -15,6 +15,7 @@ import { PermissionDeniedError,ToolError } from '../util/errors.js';
 import { pathExists, safeStatSync } from '../util/fs.js';
 import { getLogger } from '../util/logger.js';
 import { resolveExecutionTarget } from './execution-target.js';
+import { enforceGuardianOnlyPolicy } from './guardian-control-plane-policy.js';
 import { executeWithTimeout,safeTimeoutMs } from './execution-timeout.js';
 import { buildPolicyContext } from './policy-context.js';
 import { getAllTools,getTool } from './registry.js';
@@ -111,6 +112,34 @@ export class ToolExecutor {
       return { content: 'This tool is blocked by parental control settings.', isError: true };
     }
 
+    // Reject tool invocations targeting guardian control-plane endpoints from non-guardian actors.
+    const guardianCheck = enforceGuardianOnlyPolicy(name, input, context.guardianActorRole);
+    if (guardianCheck.denied) {
+      log.warn({
+        toolName: name,
+        sessionId: context.sessionId,
+        conversationId: context.conversationId,
+        actorRole: context.guardianActorRole,
+        reason: 'guardian_only_policy',
+      }, 'Guardian-only policy blocked tool invocation');
+      const durationMs = Date.now() - startTime;
+      emitLifecycleEvent(context, {
+        type: 'permission_denied',
+        toolName: name,
+        executionTarget,
+        input,
+        workingDir: context.workingDir,
+        sessionId: context.sessionId,
+        conversationId: context.conversationId,
+        requestId: context.requestId,
+        riskLevel,
+        decision: 'deny',
+        reason: guardianCheck.reason!,
+        durationMs,
+      });
+      return { content: guardianCheck.reason!, isError: true };
+    }
+
     // Gate tools not active for the current turn
     if (context.allowedToolNames && !context.allowedToolNames.has(name)) {
       const msg = `Tool "${name}" is not currently active. Load the skill that provides this tool first.`;

package/src/tools/guardian-control-plane-policy.ts

@@ -0,0 +1,141 @@
+/**
+ * Guardian control-plane policy \u2014 deterministic gate that prevents non-guardian
+ * and unverified_channel actors from invoking guardian verification endpoints
+ * conversationally via tools.
+ *
+ * Protected endpoints:
+ *   /v1/integrations/guardian/challenge
+ *   /v1/integrations/guardian/status
+ *   /v1/integrations/guardian/outbound/start
+ *   /v1/integrations/guardian/outbound/resend
+ *   /v1/integrations/guardian/outbound/cancel
+ */
+
+const GUARDIAN_ENDPOINT_PATHS = [
+  '/v1/integrations/guardian/challenge',
+  '/v1/integrations/guardian/status',
+  '/v1/integrations/guardian/outbound/start',
+  '/v1/integrations/guardian/outbound/resend',
+  '/v1/integrations/guardian/outbound/cancel',
+] as const;
+
+/**
+ * Broad regex that catches any path targeting the guardian control-plane,
+ * even if the exact sub-path differs from the hardcoded list above.
+ * Anchored on a path separator so it won't match inside unrelated words.
+ */
+const GUARDIAN_PATH_REGEX = /\/v1\/integrations\/guardian\//;
+
+/** Tools whose `input.command` (string) may contain guardian endpoint paths. */
+const COMMAND_TOOLS = new Set(['bash', 'host_bash']);
+
+/** Tools whose `input.url` (string) may contain guardian endpoint paths. */
+const URL_TOOLS = new Set(['network_request', 'web_fetch', 'browser_navigate']);
+
+/**
+ * Normalize a string to defeat common URL obfuscation techniques before matching:
+ * - Decode percent-encoded characters (e.g. %2F → /)
+ * - Collapse consecutive slashes into a single slash (preserving protocol://)
+ * - Lowercase everything
+ */
+function normalizeForMatching(value: string): string {
+  let normalized = value;
+  // Iteratively decode percent-encoding to handle double-encoding (%252F → %2F → /)
+  // Use per-sequence replacement instead of decodeURIComponent to avoid a single
+  // malformed sequence (e.g. %ZZ) preventing all other valid sequences from decoding.
+  let prev = '';
+  while (prev !== normalized) {
+    prev = normalized;
+    normalized = normalized.replace(/%[0-9a-fA-F]{2}/g, (match) => {
+      try {
+        return decodeURIComponent(match);
+      } catch {
+        return match;
+      }
+    });
+  }
+  // Collapse consecutive slashes (but preserve the double slash in protocol e.g. https://)
+  normalized = normalized.replace(/(?<!:)\/{2,}/g, '/');
+  return normalized.toLowerCase();
+}
+
+/**
+ * Check whether a string contains any of the guardian control-plane endpoint paths.
+ * Normalizes the input first to catch percent-encoding, double slashes, and case
+ * variations. Also matches a broad regex pattern to catch paths that target the
+ * guardian control-plane but aren't in the exact hardcoded list.
+ */
+function containsGuardianEndpointPath(value: string): boolean {
+  const normalized = normalizeForMatching(value);
+  // Check exact hardcoded paths against the normalized string
+  for (const path of GUARDIAN_ENDPOINT_PATHS) {
+    if (normalized.includes(path)) return true;
+  }
+  // Broad pattern match to catch any /v1/integrations/guardian/... path
+  if (GUARDIAN_PATH_REGEX.test(normalized)) return true;
+  return false;
+}
+
+/**
+ * Conservative fallback for shell tools: detects when a command contains the
+ * key fragments of a guardian control-plane path even if they are not contiguous
+ * (e.g. constructed via shell variable expansion like `base=/v1/integrations; curl "$base/guardian/status"`).
+ *
+ * Only applied to bash/host_bash — URL tools pass structured URLs that cannot
+ * be split by shell expansion.
+ */
+function containsGuardianFragments(command: string): boolean {
+  const lower = command.toLowerCase();
+  return lower.includes('/v1/integrations') && lower.includes('guardian');
+}
+
+/**
+ * Pure function that determines whether a tool invocation targets a guardian
+ * control-plane endpoint based on the tool name and its input.
+ */
+export function isGuardianControlPlaneInvocation(
+  toolName: string,
+  input: Record<string, unknown>,
+): boolean {
+  if (COMMAND_TOOLS.has(toolName)) {
+    const command = input.command;
+    if (typeof command === 'string') {
+      // Primary: exact/normalized path matching
+      if (containsGuardianEndpointPath(command)) return true;
+      // Fallback: detect shell-expanded construction of guardian paths
+      if (containsGuardianFragments(command)) return true;
+    }
+  }
+
+  if (URL_TOOLS.has(toolName)) {
+    const url = input.url;
+    if (typeof url === 'string' && containsGuardianEndpointPath(url)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Enforce the guardian-only policy: if the invocation targets a guardian
+ * control-plane endpoint and the actor is not a guardian, deny.
+ */
+export function enforceGuardianOnlyPolicy(
+  toolName: string,
+  input: Record<string, unknown>,
+  actorRole: string | undefined,
+): { denied: boolean; reason?: string } {
+  if (!isGuardianControlPlaneInvocation(toolName, input)) {
+    return { denied: false };
+  }
+
+  if (actorRole === 'guardian' || actorRole === undefined) {
+    return { denied: false };
+  }
+
+  return {
+    denied: true,
+    reason: 'Guardian verification control-plane actions are restricted to guardian users. This is a security restriction \u2014 please wait for the designated guardian to perform this action.',
+  };
+}

package/src/tools/types.ts

@@ -136,6 +136,8 @@ export interface ToolContext {
   proxyApprovalCallback?: import('./network/script-proxy/types.js').ProxyApprovalCallback;
   /** Optional principal identifier propagated to sub-tool confirmation flows. */
   principal?: string;
+  /** Guardian actor role for the session — used by the guardian control-plane policy gate. */
+  guardianActorRole?: 'guardian' | 'non-guardian' | 'unverified_channel';
 }
 
 export interface DiffInfo {