@vellumai/assistant 0.4.2 → 0.4.4

package/src/messaging/provider.ts

@@ -6,6 +6,7 @@
  */
 
 import type {
+  ArchiveResult,
   ConnectionInfo,
   Conversation,
   HistoryOptions,
@@ -13,6 +14,7 @@ import type {
   Message,
   SearchOptions,
   SearchResult,
+  SenderDigestResult,
   SendOptions,
   SendResult,
 } from './provider-types.js';
@@ -38,6 +40,11 @@ export interface MessagingProvider {
   getThreadReplies?(token: string, conversationId: string, threadId: string, options?: HistoryOptions): Promise<Message[]>;
   markRead?(token: string, conversationId: string, messageId?: string): Promise<void>;
 
+  /** Scan messages and group by sender for bulk cleanup (e.g. newsletter decluttering). */
+  senderDigest?(token: string, query: string, options?: { maxMessages?: number; maxSenders?: number }): Promise<SenderDigestResult>;
+  /** Archive messages matching a search query. */
+  archiveByQuery?(token: string, query: string): Promise<ArchiveResult>;
+
   /**
    * Override the default credential check used by getConnectedProviders().
    * When present, the registry calls this instead of looking for

package/src/messaging/providers/gmail/adapter.ts

@@ -7,6 +7,7 @@
 
 import type { MessagingProvider } from '../../provider.js';
 import type {
+  ArchiveResult,
   ConnectionInfo,
   Conversation,
   HistoryOptions,
@@ -14,6 +15,8 @@ import type {
   Message,
   SearchOptions,
   SearchResult,
+  SenderDigestEntry,
+  SenderDigestResult,
   SendOptions,
   SendResult,
 } from '../../provider-types.js';
@@ -191,4 +194,128 @@ export const gmailMessagingProvider: MessagingProvider = {
     if (!messageId) return;
     await gmail.modifyMessage(token, messageId, { removeLabelIds: ['UNREAD'] });
   },
+
+  async senderDigest(token: string, query: string, options?: { maxMessages?: number; maxSenders?: number }): Promise<SenderDigestResult> {
+    const maxMessages = Math.min(options?.maxMessages ?? 500, 2000);
+    const maxSenders = options?.maxSenders ?? 30;
+    const maxIdsPerSender = 1000;
+
+    const allMessageIds: string[] = [];
+    let pageToken: string | undefined;
+
+    while (allMessageIds.length < maxMessages) {
+      const pageSize = Math.min(100, maxMessages - allMessageIds.length);
+      const listResp = await gmail.listMessages(token, query, pageSize, pageToken);
+      const ids = (listResp.messages ?? []).map((m) => m.id);
+      if (ids.length === 0) break;
+      allMessageIds.push(...ids);
+      pageToken = listResp.nextPageToken ?? undefined;
+      if (!pageToken) break;
+    }
+
+    if (allMessageIds.length === 0) {
+      return { senders: [], totalScanned: 0, queryUsed: query };
+    }
+
+    const messages = await gmail.batchGetMessages(token, allMessageIds, 'metadata', [
+      'From', 'List-Unsubscribe',
+    ]);
+
+    const senderMap = new Map<string, {
+      displayName: string; email: string; messageCount: number;
+      hasUnsubscribe: boolean; newestMessageId: string;
+      newestUnsubscribableMessageId: string | null; newestUnsubscribableEpoch: number;
+      messageIds: string[]; hasMore: boolean;
+    }>();
+
+    for (const msg of messages) {
+      const headers = msg.payload?.headers ?? [];
+      const fromHeader = headers.find((h) => h.name.toLowerCase() === 'from')?.value ?? '';
+      const listUnsub = headers.find((h) => h.name.toLowerCase() === 'list-unsubscribe')?.value;
+
+      const match = fromHeader.match(/^(.+?)\s*<([^>]+)>$/);
+      const email = match ? match[2].toLowerCase() : fromHeader.trim().toLowerCase();
+      const displayName = match ? match[1].replace(/^["']|["']$/g, '').trim() : '';
+      if (!email) continue;
+
+      let agg = senderMap.get(email);
+      if (!agg) {
+        agg = {
+          displayName, email, messageCount: 0, hasUnsubscribe: false,
+          newestMessageId: msg.id, newestUnsubscribableMessageId: null,
+          newestUnsubscribableEpoch: 0, messageIds: [], hasMore: false,
+        };
+        senderMap.set(email, agg);
+      }
+
+      agg.messageCount++;
+      if (listUnsub) agg.hasUnsubscribe = true;
+      if (!agg.displayName && displayName) agg.displayName = displayName;
+
+      if (agg.messageIds.length < maxIdsPerSender) {
+        agg.messageIds.push(msg.id);
+      } else {
+        agg.hasMore = true;
+      }
+
+      const msgEpoch = msg.internalDate ? Number(msg.internalDate) : 0;
+      if (listUnsub && msgEpoch >= agg.newestUnsubscribableEpoch) {
+        agg.newestUnsubscribableMessageId = msg.id;
+        agg.newestUnsubscribableEpoch = msgEpoch;
+      }
+    }
+
+    const sorted = [...senderMap.values()]
+      .sort((a, b) => b.messageCount - a.messageCount)
+      .slice(0, maxSenders);
+
+    const senders: SenderDigestEntry[] = sorted.map((s) => ({
+      id: Buffer.from(s.email).toString('base64url'),
+      displayName: s.displayName || s.email.split('@')[0],
+      email: s.email,
+      messageCount: s.messageCount,
+      hasUnsubscribe: s.hasUnsubscribe,
+      newestMessageId: (s.hasUnsubscribe && s.newestUnsubscribableMessageId)
+        ? s.newestUnsubscribableMessageId
+        : s.newestMessageId,
+      searchQuery: `from:${s.email} ${query}`,
+      messageIds: s.messageIds,
+      hasMore: s.hasMore,
+    }));
+
+    return { senders, totalScanned: allMessageIds.length, queryUsed: query };
+  },
+
+  async archiveByQuery(token: string, query: string): Promise<ArchiveResult> {
+    const maxMessages = 5000;
+    const batchModifyLimit = 1000;
+
+    const allMessageIds: string[] = [];
+    let pageToken: string | undefined;
+    let truncated = false;
+
+    while (allMessageIds.length < maxMessages) {
+      const listResp = await gmail.listMessages(token, query, Math.min(500, maxMessages - allMessageIds.length), pageToken);
+      const ids = (listResp.messages ?? []).map((m) => m.id);
+      if (ids.length === 0) break;
+      allMessageIds.push(...ids);
+      pageToken = listResp.nextPageToken ?? undefined;
+      if (!pageToken) break;
+    }
+
+    if (allMessageIds.length >= maxMessages && pageToken) {
+      truncated = true;
+    }
+
+    if (allMessageIds.length === 0) {
+      return { archived: 0 };
+    }
+
+    for (let i = 0; i < allMessageIds.length; i += batchModifyLimit) {
+      const chunk = allMessageIds.slice(i, i + batchModifyLimit);
+      await gmail.batchModifyMessages(token, chunk, { removeLabelIds: ['INBOX'] });
+    }
+
+    return { archived: allMessageIds.length, truncated };
+  },
 };

package/src/messaging/providers/sms/adapter.ts

@@ -18,6 +18,7 @@ import { getGatewayInternalBaseUrl, getTwilioPhoneNumberEnv } from '../../../con
 import { loadConfig } from '../../../config/loader.js';
 import { getOrCreateConversation } from '../../../memory/conversation-key-store.js';
 import * as externalConversationStore from '../../../memory/external-conversation-store.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../../../runtime/assistant-scope.js';
 import { getSecureKey } from '../../../security/secure-keys.js';
 import { readHttpToken } from '../../../util/platform.js';
 import type { MessagingProvider } from '../../provider.js';
@@ -56,22 +57,8 @@ function hasTwilioCredentials(): boolean {
   );
 }
 
-/**
- * Resolve the configured SMS phone number.
- * Priority: assistant-scoped phone number > TWILIO_PHONE_NUMBER env > config sms.phoneNumber > secure key fallback.
- */
-function getPhoneNumber(assistantId?: string): string | undefined {
-  // Check assistant-scoped phone number first
-  if (assistantId) {
-    try {
-      const config = loadConfig();
-      const assistantPhone = config.sms?.assistantPhoneNumbers?.[assistantId];
-      if (assistantPhone) return assistantPhone;
-    } catch {
-      // Config may not be available yet during early startup
-    }
-  }
-
+/** Resolve the configured SMS phone number. */
+function getPhoneNumber(): string | undefined {
   const fromEnv = getTwilioPhoneNumberEnv();
   if (fromEnv) return fromEnv;
 
@@ -85,15 +72,6 @@ function getPhoneNumber(assistantId?: string): string | undefined {
   return getSecureKey('credential:twilio:phone_number') || undefined;
 }
 
-function hasAnyAssistantPhoneNumber(): boolean {
-  try {
-    const config = loadConfig();
-    return Object.keys(config.sms?.assistantPhoneNumbers ?? {}).length > 0;
-  } catch {
-    return false;
-  }
-}
-
 export const smsMessagingProvider: MessagingProvider = {
   id: 'sms',
   displayName: 'SMS',
@@ -106,7 +84,16 @@ export const smsMessagingProvider: MessagingProvider = {
    * the `from` for outbound messages.
    */
   isConnected(): boolean {
-    return hasTwilioCredentials() && (!!getPhoneNumber() || hasAnyAssistantPhoneNumber());
+    if (!hasTwilioCredentials()) return false;
+    if (getPhoneNumber()) return true;
+    try {
+      const config = loadConfig();
+      const mappings = config.sms?.assistantPhoneNumbers as Record<string, string> | undefined;
+      if (mappings && Object.keys(mappings).length > 0) return true;
+    } catch {
+      // Config may not be available yet
+    }
+    return false;
   },
 
   async testConnection(_token: string): Promise<ConnectionInfo> {
@@ -120,7 +107,26 @@ export const smsMessagingProvider: MessagingProvider = {
     }
 
     const phoneNumber = getPhoneNumber();
-    if (!phoneNumber && !hasAnyAssistantPhoneNumber()) {
+    if (!phoneNumber) {
+      // Mirror isConnected(): fall back to assistant-scoped phone numbers
+      try {
+        const config = loadConfig();
+        const mappings = config.sms?.assistantPhoneNumbers as Record<string, string> | undefined;
+        if (mappings && Object.keys(mappings).length > 0) {
+          const accountSid = getSecureKey('credential:twilio:account_sid')!;
+          return {
+            connected: true,
+            user: 'assistant-scoped',
+            platform: 'sms',
+            metadata: {
+              accountSid: accountSid.slice(0, 6) + '...',
+              assistantPhoneNumbers: Object.keys(mappings).length,
+            },
+          };
+        }
+      } catch {
+        // Config may not be available yet
+      }
       return {
         connected: false,
         user: 'unknown',
@@ -133,12 +139,11 @@ export const smsMessagingProvider: MessagingProvider = {
 
     return {
       connected: true,
-      user: phoneNumber ?? 'assistant-scoped numbers configured',
+      user: phoneNumber,
       platform: 'sms',
       metadata: {
         accountSid: accountSid.slice(0, 6) + '...',
-        ...(phoneNumber ? { phoneNumber } : {}),
-        hasAssistantScopedPhoneNumbers: hasAnyAssistantPhoneNumber(),
+        phoneNumber,
       },
     };
   },
@@ -152,16 +157,14 @@ export const smsMessagingProvider: MessagingProvider = {
 
     // Upsert external conversation binding so the conversation key mapping
     // exists for the next inbound SMS from this number.
+    const isSelfScope = !assistantId || assistantId === DAEMON_INTERNAL_ASSISTANT_ID;
     try {
       const sourceChannel = 'sms';
-      const conversationKey = assistantId && assistantId !== 'self'
-        ? `asst:${assistantId}:${sourceChannel}:${conversationId}`
-        : `${sourceChannel}:${conversationId}`;
+      const conversationKey = isSelfScope
+        ? `${sourceChannel}:${conversationId}`
+        : `asst:${assistantId}:${sourceChannel}:${conversationId}`;
       const { conversationId: internalId } = getOrCreateConversation(conversationKey);
-      // external_conversation_bindings is assistant-agnostic (unique by
-      // sourceChannel + externalChatId). Restrict proactive writes to self so
-      // multi-assistant sends cannot clobber each other's binding metadata.
-      if (!assistantId || assistantId === 'self') {
+      if (isSelfScope) {
         externalConversationStore.upsertOutboundBinding({
           conversationId: internalId,
           sourceChannel,

package/src/notifications/adapters/macos.ts

@@ -5,6 +5,12 @@
  * The adapter broadcasts a `notification_intent` message that the Vellum
  * client can use to display a native notification (e.g. NSUserNotification
  * or UNUserNotificationCenter).
+ *
+ * Guardian-sensitive notifications (approval requests, escalation alerts)
+ * are annotated with `targetGuardianPrincipalId` so that only clients
+ * bound to the guardian identity display them. Non-guardian clients
+ * should ignore notifications with a `targetGuardianPrincipalId` that
+ * does not match their own identity.
  */
 
 import type { ServerMessage } from '../../daemon/ipc-contract.js';
@@ -21,6 +27,24 @@ const log = getLogger('notif-adapter-vellum');
 
 export type BroadcastFn = (msg: ServerMessage) => void;
 
+/**
+ * Event name prefixes that carry guardian-sensitive content (approval
+ * requests, escalation alerts, access requests). Notifications for
+ * these events are scoped to bound guardian devices via
+ * `targetGuardianPrincipalId`.
+ */
+const GUARDIAN_SENSITIVE_EVENT_PREFIXES = [
+  'guardian.question',
+  'ingress.escalation',
+  'ingress.access_request',
+] as const;
+
+export function isGuardianSensitiveEvent(sourceEventName: string): boolean {
+  return GUARDIAN_SENSITIVE_EVENT_PREFIXES.some(
+    (prefix) => sourceEventName === prefix || sourceEventName.startsWith(prefix + '.'),
+  );
+}
+
 export class VellumAdapter implements ChannelAdapter {
   readonly channel: NotificationChannel = 'vellum';
 
@@ -30,8 +54,22 @@ export class VellumAdapter implements ChannelAdapter {
     this.broadcast = broadcast;
   }
 
-  async send(payload: ChannelDeliveryPayload, _destination: ChannelDestination): Promise<DeliveryResult> {
+  async send(payload: ChannelDeliveryPayload, destination: ChannelDestination): Promise<DeliveryResult> {
     try {
+      // For guardian-sensitive events, annotate the outbound message with
+      // the target guardian identity so clients can filter. The
+      // guardianPrincipalId comes from the vellum binding resolved by
+      // the destination resolver.
+      const guardianPrincipalId =
+        typeof destination.metadata?.guardianPrincipalId === 'string'
+          ? destination.metadata.guardianPrincipalId
+          : undefined;
+
+      const targetGuardianPrincipalId =
+        guardianPrincipalId && isGuardianSensitiveEvent(payload.sourceEventName)
+          ? guardianPrincipalId
+          : undefined;
+
       this.broadcast({
         type: 'notification_intent',
         deliveryId: payload.deliveryId,
@@ -39,10 +77,15 @@ export class VellumAdapter implements ChannelAdapter {
         title: payload.copy.title,
         body: payload.copy.body,
         deepLinkMetadata: payload.deepLinkTarget,
+        targetGuardianPrincipalId,
       } as ServerMessage);
 
       log.info(
-        { sourceEventName: payload.sourceEventName, title: payload.copy.title },
+        {
+          sourceEventName: payload.sourceEventName,
+          title: payload.copy.title,
+          guardianScoped: targetGuardianPrincipalId != null,
+        },
         'Vellum notification intent broadcast',
       );
 

package/src/notifications/broadcaster.ts

@@ -12,6 +12,7 @@
 import { v4 as uuid } from 'uuid';
 
 import { getLogger } from '../util/logger.js';
+import { isGuardianSensitiveEvent } from './adapters/macos.js';
 import { pairDeliveryWithConversation } from './conversation-pairing.js';
 import { composeFallbackCopy } from './copy-composer.js';
 import { createDelivery, findDeliveryByDecisionAndChannel, updateDeliveryStatus } from './deliveries-store.js';
@@ -34,6 +35,8 @@ export interface ThreadCreatedInfo {
   conversationId: string;
   title: string;
   sourceEventName: string;
+  /** Present when the thread is for a guardian-sensitive notification. */
+  targetGuardianPrincipalId?: string;
 }
 export type OnThreadCreatedFn = (info: ThreadCreatedInfo) => void;
 export interface BroadcastDecisionOptions {
@@ -163,6 +166,18 @@ export class NotificationBroadcaster {
       if (channel === 'vellum' && pairing.conversationId) {
         deepLinkTarget = { ...deepLinkTarget, conversationId: pairing.conversationId };
 
+        // Resolve guardian scoping for thread-created events so clients
+        // can filter guardian-sensitive threads the same way they filter
+        // guardian-sensitive notification intents.
+        const guardianPrincipalId =
+          typeof destination.metadata?.guardianPrincipalId === 'string'
+            ? destination.metadata.guardianPrincipalId
+            : undefined;
+        const targetGuardianPrincipalId =
+          guardianPrincipalId && isGuardianSensitiveEvent(signal.sourceEventName)
+            ? guardianPrincipalId
+            : undefined;
+
         const threadTitle =
           copy.threadTitle ??
           copy.title ??
@@ -171,6 +186,7 @@ export class NotificationBroadcaster {
           conversationId: pairing.conversationId,
           title: threadTitle,
           sourceEventName: signal.sourceEventName,
+          targetGuardianPrincipalId,
         };
 
         // The per-dispatch onThreadCreated callback fires whenever a vellum

package/src/notifications/copy-composer.ts

@@ -9,6 +9,10 @@
  * values from the context payload.
  */
 
+import {
+  buildGuardianRequestCodeInstruction,
+  resolveGuardianQuestionInstructionMode,
+} from './guardian-question-mode.js';
 import type { NotificationSignal } from './signal.js';
 import type { NotificationChannel, RenderedChannelCopy } from './types.js';
 
@@ -48,16 +52,34 @@ const TEMPLATES: Record<string, CopyTemplate> = {
     }
 
     const normalizedCode = requestCode.toUpperCase();
+    const modeResolution = resolveGuardianQuestionInstructionMode(payload);
+    const instruction = buildGuardianRequestCodeInstruction(normalizedCode, modeResolution.mode);
     return {
       title: 'Guardian Question',
-      body: `${question}\n\nReference code: ${normalizedCode}. Reply "${normalizedCode} approve" or "${normalizedCode} reject".`,
+      body: `${question}\n\n${instruction}`,
     };
   },
 
   'ingress.access_request': (payload) => {
     const requester = str(payload.senderIdentifier, 'Someone');
     const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
-    const lines: string[] = [`${requester} is requesting access to the assistant.`];
+    const sourceChannel = typeof payload.sourceChannel === 'string' ? payload.sourceChannel : undefined;
+    const callerName = nonEmpty(typeof payload.senderName === 'string' ? payload.senderName : undefined);
+    const previousMemberStatus = typeof payload.previousMemberStatus === 'string'
+      ? payload.previousMemberStatus
+      : undefined;
+    const lines: string[] = [];
+
+    // Voice-originated access requests include caller name context
+    if (sourceChannel === 'voice' && callerName) {
+      lines.push(`${callerName} (${str(payload.senderExternalUserId, requester)}) is calling and requesting access to the assistant.`);
+    } else {
+      lines.push(`${requester} is requesting access to the assistant.`);
+    }
+    if (previousMemberStatus === 'revoked') {
+      lines.push('Note: this user was previously revoked.');
+    }
+
     if (requestCode) {
       const code = requestCode.toUpperCase();
       lines.push(`Reply "${code} approve" to grant access or "${code} reject" to deny.`);
@@ -69,6 +91,32 @@ const TEMPLATES: Record<string, CopyTemplate> = {
     };
   },
 
+  'ingress.access_request.callback_handoff': (payload) => {
+    const callerName = nonEmpty(typeof payload.callerName === 'string' ? payload.callerName : undefined);
+    const callerPhone = nonEmpty(typeof payload.callerPhoneNumber === 'string' ? payload.callerPhoneNumber : undefined);
+    const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
+    const memberId = nonEmpty(typeof payload.requesterMemberId === 'string' ? payload.requesterMemberId : undefined);
+
+    const callerIdentity = callerName && callerPhone
+      ? `${callerName} (${callerPhone})`
+      : callerName ?? callerPhone ?? 'An unknown caller';
+
+    const lines: string[] = [];
+    lines.push(`${callerIdentity} called and requested a callback while you were unreachable.`);
+
+    if (requestCode) {
+      lines.push(`Request code: ${requestCode.toUpperCase()}`);
+    }
+    if (memberId) {
+      lines.push(`This caller is a trusted contact (member ID: ${memberId}).`);
+    }
+
+    return {
+      title: 'Callback Requested',
+      body: lines.join('\n'),
+    };
+  },
+
   'ingress.escalation': (payload) => ({
     title: 'Escalation',
     body: str(payload.senderIdentifier, 'An incoming message') + ' needs attention',

package/src/notifications/decision-engine.ts

@@ -18,6 +18,12 @@ import type { ModelIntent } from '../providers/types.js';
 import { getLogger } from '../util/logger.js';
 import { composeFallbackCopy } from './copy-composer.js';
 import { createDecision } from './decisions-store.js';
+import {
+  buildGuardianRequestCodeInstruction,
+  hasGuardianRequestCodeInstruction,
+  resolveGuardianQuestionInstructionMode,
+  stripConflictingGuardianRequestInstructions,
+} from './guardian-question-mode.js';
 import { getPreferenceSummary } from './preference-summary.js';
 import type { NotificationSignal, RoutingIntent } from './signal.js';
 import { buildThreadCandidates, serializeCandidatesForPrompt,type ThreadCandidateSet } from './thread-candidates.js';
@@ -409,18 +415,15 @@ export function validateThreadActions(
 function ensureGuardianRequestCodeInCopy(
   copy: RenderedChannelCopy,
   requestCode: string,
+  mode: 'approval' | 'answer',
 ): RenderedChannelCopy {
-  const instruction = `Reference code: ${requestCode}. Reply "${requestCode} approve" or "${requestCode} reject".`;
-  const hasParserCompatibleInstructions = (text: string | undefined): boolean => {
-    if (typeof text !== 'string') return false;
-    const upper = text.toUpperCase();
-    return upper.includes(`${requestCode} APPROVE`) && upper.includes(`${requestCode} REJECT`);
-  };
+  const instruction = buildGuardianRequestCodeInstruction(requestCode, mode);
 
   const ensureText = (text: string | undefined): string => {
     const base = typeof text === 'string' ? text.trim() : '';
-    if (hasParserCompatibleInstructions(base)) return base;
-    return base.length > 0 ? `${base}\n\n${instruction}` : instruction;
+    const sanitized = stripConflictingGuardianRequestInstructions(base, requestCode, mode);
+    if (hasGuardianRequestCodeInstruction(sanitized, requestCode, mode)) return sanitized;
+    return sanitized.length > 0 ? `${sanitized}\n\n${instruction}` : instruction;
   };
 
   return {
@@ -445,6 +448,16 @@ function enforceGuardianRequestCode(
   if (typeof rawCode !== 'string' || rawCode.trim().length === 0) return decision;
 
   const requestCode = rawCode.trim().toUpperCase();
+  const modeResolution = resolveGuardianQuestionInstructionMode(signal.contextPayload);
+  if (modeResolution.legacyFallbackUsed) {
+    log.warn(
+      {
+        signalId: signal.signalId,
+        requestKind: modeResolution.requestKind,
+      },
+      'guardian.question payload missing/invalid typed fields; using legacy instruction-mode fallback',
+    );
+  }
   const nextCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {
     ...decision.renderedCopy,
   };
@@ -452,7 +465,7 @@ function enforceGuardianRequestCode(
   for (const channel of Object.keys(nextCopy) as NotificationChannel[]) {
     const copy = nextCopy[channel];
     if (!copy) continue;
-    nextCopy[channel] = ensureGuardianRequestCodeInCopy(copy, requestCode);
+    nextCopy[channel] = ensureGuardianRequestCodeInCopy(copy, requestCode, modeResolution.mode);
   }
 
   return {

package/src/notifications/destination-resolver.ts

@@ -2,7 +2,10 @@
  * Resolves per-channel destination endpoints for notification delivery.
  *
  * - Vellum: no external endpoint needed — delivery goes through the IPC
- *   broadcast mechanism to connected desktop/mobile clients.
+ *   broadcast mechanism to connected desktop/mobile clients. The
+ *   guardianPrincipalId from the vellum binding is included in metadata
+ *   so downstream adapters can scope guardian-sensitive notifications to
+ *   bound guardian devices only.
  * - Binding-based channels (telegram, sms): require a chat/delivery ID
  *   sourced from the guardian binding for the assistant.
  */
@@ -35,7 +38,18 @@ export function resolveDestinations(
     switch (channel as NotificationChannel) {
       case 'vellum': {
         // Vellum delivery is local IPC — no external endpoint required.
-        result.set('vellum', { channel: 'vellum' });
+        // Include the guardianPrincipalId from the vellum binding so the
+        // adapter can annotate guardian-sensitive notifications for scoped
+        // delivery to bound guardian devices.
+        const vellumBinding = getActiveBinding(assistantId, 'vellum');
+        const metadata: Record<string, unknown> = {};
+        if (vellumBinding) {
+          metadata.guardianPrincipalId = vellumBinding.guardianExternalUserId;
+        }
+        result.set('vellum', {
+          channel: 'vellum',
+          metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        });
         break;
       }
       case 'telegram':

package/src/notifications/emit-signal.ts

@@ -13,6 +13,7 @@ import { v4 as uuid } from 'uuid';
 
 import { getDeliverableChannels } from '../channels/config.js';
 import { getActiveBinding } from '../memory/channel-guardian-store.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../runtime/assistant-scope.js';
 import { getLogger } from '../util/logger.js';
 import { type BroadcastFn, VellumAdapter } from './adapters/macos.js';
 import { SmsAdapter } from './adapters/sms.js';
@@ -23,7 +24,12 @@ 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, RoutingIntent } from './signal.js';
+import type {
+  AttentionHints,
+  NotificationContextPayload,
+  NotificationSignal,
+  RoutingIntent,
+} from './signal.js';
 import type { NotificationChannel, NotificationDeliveryResult } from './types.js';
 
 const log = getLogger('emit-signal');
@@ -66,9 +72,10 @@ function getBroadcaster(): NotificationBroadcaster {
           conversationId: info.conversationId,
           title: info.title,
           sourceEventName: info.sourceEventName,
+          targetGuardianPrincipalId: info.targetGuardianPrincipalId,
         });
         log.info(
-          { conversationId: info.conversationId },
+          { conversationId: info.conversationId, guardianScoped: info.targetGuardianPrincipalId != null },
           'Emitted notification_thread_created push event',
         );
       });
@@ -116,9 +123,9 @@ function getConnectedChannels(assistantId: string): NotificationChannel[] {
 
 // ── Public API ─────────────────────────────────────────────────────────
 
-export interface EmitSignalParams {
+export interface EmitSignalParams<TEventName extends string = string> {
   /** Free-form event name, e.g. 'reminder.fired', 'schedule.complete'. */
-  sourceEventName: string;
+  sourceEventName: TEventName;
   /** Source channel that produced the event. */
   sourceChannel: string;
   /** Session or conversation ID from the source context. */
@@ -128,7 +135,7 @@ export interface EmitSignalParams {
   /** Attention hints for the decision engine. */
   attentionHints: AttentionHints;
   /** Arbitrary context payload passed to the decision engine. */
-  contextPayload?: Record<string, unknown>;
+  contextPayload?: NotificationContextPayload<TEventName>;
   /** 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. */
@@ -168,18 +175,20 @@ export interface EmitSignalResult {
  * Fire-and-forget safe by default: errors are caught and logged unless
  * `throwOnError` is enabled by the caller.
  */
-export async function emitNotificationSignal(params: EmitSignalParams): Promise<EmitSignalResult> {
+export async function emitNotificationSignal<TEventName extends string>(
+  params: EmitSignalParams<TEventName>,
+): Promise<EmitSignalResult> {
   const signalId = uuid();
-  const assistantId = params.assistantId ?? 'self';
+  const assistantId = params.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
 
-  const signal: NotificationSignal = {
+  const signal: NotificationSignal<TEventName> = {
     signalId,
     assistantId,
     createdAt: Date.now(),
     sourceChannel: params.sourceChannel,
     sourceSessionId: params.sourceSessionId,
     sourceEventName: params.sourceEventName,
-    contextPayload: params.contextPayload ?? {},
+    contextPayload: (params.contextPayload ?? {}) as NotificationContextPayload<TEventName>,
     attentionHints: params.attentionHints,
     routingIntent: params.routingIntent,
     routingHints: params.routingHints,