@vellumai/assistant 0.4.3 → 0.4.4

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,9 +52,11 @@ 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}`,
     };
   },
 
@@ -59,6 +65,9 @@ const TEMPLATES: Record<string, CopyTemplate> = {
     const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
     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
@@ -67,6 +76,9 @@ const TEMPLATES: Record<string, CopyTemplate> = {
     } 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();
@@ -79,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

@@ -24,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');
@@ -67,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',
         );
       });
@@ -117,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. */
@@ -129,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. */
@@ -169,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 ?? 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,