@vellumai/assistant 0.4.2 → 0.4.4

package/src/runtime/channel-readiness-service.ts

@@ -31,41 +31,15 @@ function hasIngressConfigured(): boolean {
   }
 }
 
-function getAssistantMappedPhoneNumber(
-  smsConfig: Record<string, unknown>,
-  assistantId?: string,
-): string | undefined {
-  if (!assistantId) return undefined;
-  const mapping = (smsConfig.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
-  return mapping[assistantId];
-}
-
-function hasAnyAssistantMappedPhoneNumber(smsConfig: Record<string, unknown>): boolean {
-  const mapping = (smsConfig.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
-  return Object.keys(mapping).length > 0;
-}
-
-function hasAnyAssistantMappedPhoneNumberSafe(): boolean {
-  try {
-    const raw = loadRawConfig();
-    const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
-    return hasAnyAssistantMappedPhoneNumber(smsConfig);
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Resolve SMS from-number with canonical precedence:
- * assistant mapping -> env override -> config sms.phoneNumber -> secure key fallback.
+ * env override -> config sms.phoneNumber -> secure key fallback.
  */
-function resolveSmsPhoneNumber(assistantId?: string): string {
+function resolveSmsPhoneNumber(): string {
   try {
     const raw = loadRawConfig();
     const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
-    const mapped = getAssistantMappedPhoneNumber(smsConfig, assistantId);
-    return mapped
-      || getTwilioPhoneNumberEnv()
+    return getTwilioPhoneNumberEnv()
       || (smsConfig.phoneNumber as string)
       || getSecureKey('credential:twilio:phone_number')
       || '';
@@ -78,7 +52,7 @@ function resolveSmsPhoneNumber(assistantId?: string): string {
 
 const smsProbe: ChannelProbe = {
   channel: 'sms',
-  runLocalChecks(context?: ChannelProbeContext): ReadinessCheckResult[] {
+  runLocalChecks(): ReadinessCheckResult[] {
     const results: ReadinessCheckResult[] = [];
 
     const hasCreds = hasTwilioCredentials();
@@ -90,18 +64,14 @@ const smsProbe: ChannelProbe = {
         : 'Twilio Account SID and Auth Token are not configured',
     });
 
-    const resolvedNumber = resolveSmsPhoneNumber(context?.assistantId);
-    const hasPhone = !!resolvedNumber || (!context?.assistantId && hasAnyAssistantMappedPhoneNumberSafe());
+    const resolvedNumber = resolveSmsPhoneNumber();
+    const hasPhone = !!resolvedNumber;
     results.push({
       name: 'phone_number',
       passed: hasPhone,
       message: hasPhone
-        ? (context?.assistantId && !resolvedNumber
-          ? `Assistant ${context.assistantId} has no direct mapping, but SMS phone numbers are assigned`
-          : 'Phone number is assigned')
-        : (context?.assistantId
-          ? `No phone number assigned for assistant ${context.assistantId}`
-          : 'No phone number assigned'),
+        ? 'Phone number is assigned'
+        : 'No phone number assigned',
     });
 
     const hasIngress = hasIngressConfigured();
@@ -115,14 +85,14 @@ const smsProbe: ChannelProbe = {
 
     return results;
   },
-  async runRemoteChecks(context?: ChannelProbeContext): Promise<ReadinessCheckResult[]> {
+  async runRemoteChecks(): Promise<ReadinessCheckResult[]> {
     if (!hasTwilioCredentials()) return [];
 
     const accountSid = getSecureKey('credential:twilio:account_sid');
     const authToken = getSecureKey('credential:twilio:auth_token');
     if (!accountSid || !authToken) return [];
 
-    const phoneNumber = resolveSmsPhoneNumber(context?.assistantId);
+    const phoneNumber = resolveSmsPhoneNumber();
     if (!phoneNumber) return [];
 
     // Only toll-free numbers need verification checks
@@ -170,18 +140,16 @@ const smsProbe: ChannelProbe = {
 
 /**
  * Resolve voice from-number with the same precedence as SMS:
- * assistant mapping -> env override -> config sms.phoneNumber -> secure key fallback.
+ * env override -> config sms.phoneNumber -> secure key fallback.
  *
  * Voice and SMS share the same Twilio phone number infrastructure, so the
  * resolution logic is identical to resolveSmsPhoneNumber.
  */
-function resolveVoicePhoneNumber(assistantId?: string): string {
+function resolveVoicePhoneNumber(): string {
   try {
     const raw = loadRawConfig();
     const smsConfig = (raw?.sms ?? {}) as Record<string, unknown>;
-    const mapped = getAssistantMappedPhoneNumber(smsConfig, assistantId);
-    return mapped
-      || getTwilioPhoneNumberEnv()
+    return getTwilioPhoneNumberEnv()
       || (smsConfig.phoneNumber as string)
       || getSecureKey('credential:twilio:phone_number')
       || '';
@@ -194,7 +162,7 @@ function resolveVoicePhoneNumber(assistantId?: string): string {
 
 const voiceProbe: ChannelProbe = {
   channel: 'voice',
-  runLocalChecks(context?: ChannelProbeContext): ReadinessCheckResult[] {
+  runLocalChecks(): ReadinessCheckResult[] {
     const results: ReadinessCheckResult[] = [];
 
     const hasCreds = hasTwilioCredentials();
@@ -206,18 +174,14 @@ const voiceProbe: ChannelProbe = {
         : 'Twilio Account SID and Auth Token are not configured',
     });
 
-    const resolvedNumber = resolveVoicePhoneNumber(context?.assistantId);
-    const hasPhone = !!resolvedNumber || (!context?.assistantId && hasAnyAssistantMappedPhoneNumberSafe());
+    const resolvedNumber = resolveVoicePhoneNumber();
+    const hasPhone = !!resolvedNumber;
     results.push({
       name: 'phone_number',
       passed: hasPhone,
       message: hasPhone
-        ? (context?.assistantId && !resolvedNumber
-          ? `Assistant ${context.assistantId} has no direct mapping, but phone numbers are assigned`
-          : 'Phone number is assigned for voice calls')
-        : (context?.assistantId
-          ? `No phone number assigned for assistant ${context.assistantId}`
-          : 'No phone number assigned for voice calls'),
+        ? 'Phone number is assigned for voice calls'
+        : 'No phone number assigned for voice calls',
     });
 
     const hasIngress = hasIngressConfigured();
@@ -290,7 +254,6 @@ export class ChannelReadinessService {
   async getReadiness(
     channel?: ChannelId,
     includeRemote?: boolean,
-    assistantId?: string,
   ): Promise<ChannelReadinessSnapshot[]> {
     const channels = channel
       ? [channel]
@@ -304,14 +267,14 @@ export class ChannelReadinessService {
         continue;
       }
 
-      const probeContext: ChannelProbeContext = { assistantId };
+      const probeContext: ChannelProbeContext = {};
       const localChecks = probe.runLocalChecks(probeContext);
       let remoteChecks: ReadinessCheckResult[] | undefined;
       let remoteChecksFreshlyFetched = false;
       let remoteChecksAffectReadiness = false;
       let stale = false;
 
-      const cacheKey = this.snapshotCacheKey(ch, assistantId);
+      const cacheKey = this.snapshotCacheKey(ch);
       const cached = this.snapshots.get(cacheKey);
       const now = Date.now();
 
@@ -372,11 +335,7 @@ export class ChannelReadinessService {
   }
 
   /** Clear cached snapshot for a specific channel, forcing re-evaluation on next call. */
-  invalidateChannel(channel: ChannelId, assistantId?: string): void {
-    if (assistantId) {
-      this.snapshots.delete(this.snapshotCacheKey(channel, assistantId));
-      return;
-    }
+  invalidateChannel(channel: ChannelId): void {
     const prefix = `${channel}::`;
     for (const key of this.snapshots.keys()) {
       if (key.startsWith(prefix)) {
@@ -401,8 +360,8 @@ export class ChannelReadinessService {
     };
   }
 
-  private snapshotCacheKey(channel: ChannelId, assistantId?: string): string {
-    return `${channel}::${assistantId ?? '__default__'}`;
+  private snapshotCacheKey(channel: ChannelId): string {
+    return `${channel}::__default__`;
   }
 }
 

package/src/runtime/channel-readiness-types.ts

@@ -22,10 +22,9 @@ export interface ChannelReadinessSnapshot {
   remoteChecks?: ReadinessCheckResult[];
 }
 
-/** Optional probe context for assistant-scoped readiness checks. */
-export interface ChannelProbeContext {
-  assistantId?: string;
-}
+/** Optional probe context for readiness checks. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ChannelProbeContext {}
 
 /** Probe interface that channels implement to provide readiness checks. */
 export interface ChannelProbe {

package/src/runtime/channel-retry-sweep.ts

@@ -7,6 +7,7 @@ import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.
 import * as channelDeliveryStore from '../memory/channel-delivery-store.js';
 import { getLogger } from '../util/logger.js';
 import { deliverReplyViaCallback } from './channel-reply-delivery.js';
+import { resolveRoutingStateFromRuntime } from './guardian-context-resolver.js';
 import type { MessageProcessor } from './http-types.js';
 
 const log = getLogger('runtime-http');
@@ -129,7 +130,9 @@ export async function sweepFailedEvents(
           },
           assistantId,
           guardianContext,
-          isInteractive: guardianContext?.trustClass === 'guardian',
+          isInteractive: guardianContext
+            ? resolveRoutingStateFromRuntime(guardianContext).promptWaitingAllowed
+            : false,
         },
         sourceChannel,
         sourceInterface,

package/src/runtime/confirmation-request-guardian-bridge.ts

@@ -0,0 +1,197 @@
+/**
+ * Bridge trusted-contact confirmation_request events to guardian.question notifications.
+ *
+ * When a trusted-contact channel session creates a confirmation_request (tool approval),
+ * this helper emits a guardian.question notification signal and persists canonical
+ * delivery rows to guardian destinations (Telegram/SMS/Vellum), enabling the guardian
+ * to approve via callback/request-code path.
+ *
+ * Modeled after the tool-grant-request-helper pattern. Designed to be called from
+ * both the daemon event registrar (server.ts) and the HTTP hub publisher
+ * (conversation-routes.ts) — the two paths that create confirmation_request
+ * canonical records.
+ */
+
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import {
+  type CanonicalGuardianRequest,
+  createCanonicalGuardianDelivery,
+} from '../memory/canonical-guardian-store.js';
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
+import { canonicalizeInboundIdentity } from '../util/canonicalize-identity.js';
+import { getLogger } from '../util/logger.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
+import { getGuardianBinding } from './channel-guardian-service.js';
+
+const log = getLogger('confirmation-request-guardian-bridge');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BridgeConfirmationRequestParams {
+  /** The canonical guardian request already persisted for this confirmation_request. */
+  canonicalRequest: CanonicalGuardianRequest;
+  /** Guardian runtime context from the session. */
+  guardianContext: GuardianRuntimeContext;
+  /** Conversation ID where the confirmation_request was emitted. */
+  conversationId: string;
+  /** Tool name from the confirmation_request. */
+  toolName: string;
+  /** Logical assistant ID (defaults to 'self'). */
+  assistantId?: string;
+}
+
+export type BridgeConfirmationRequestResult =
+  | { bridged: true; signalId: string }
+  | { skipped: true; reason: 'not_trusted_contact' | 'no_guardian_binding' | 'missing_guardian_identity' | 'binding_identity_mismatch' };
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a trusted-contact confirmation_request to a guardian.question notification.
+ *
+ * Only emits when the session belongs to a trusted-contact actor with a
+ * resolvable guardian binding. Guardian and unknown actors are skipped — guardians
+ * self-approve, and unknown actors are already fail-closed by the routing layer.
+ *
+ * Fire-and-forget safe: notification emission errors are logged but not propagated.
+ */
+export function bridgeConfirmationRequestToGuardian(
+  params: BridgeConfirmationRequestParams,
+): BridgeConfirmationRequestResult {
+  const {
+    canonicalRequest,
+    guardianContext,
+    conversationId,
+    toolName,
+    assistantId = DAEMON_INTERNAL_ASSISTANT_ID,
+  } = params;
+
+  // Only bridge for trusted-contact sessions. Guardians self-approve and
+  // unknown actors are fail-closed by the routing layer.
+  if (guardianContext.trustClass !== 'trusted_contact') {
+    return { skipped: true, reason: 'not_trusted_contact' };
+  }
+
+  if (!guardianContext.guardianExternalUserId) {
+    log.debug(
+      { conversationId, sourceChannel: guardianContext.sourceChannel },
+      'Skipping guardian bridge: no guardian identity on trusted-contact context',
+    );
+    return { skipped: true, reason: 'missing_guardian_identity' };
+  }
+
+  const sourceChannel = guardianContext.sourceChannel;
+  const binding = getGuardianBinding(assistantId, sourceChannel);
+  if (!binding) {
+    log.debug(
+      { sourceChannel, assistantId },
+      'No guardian binding for confirmation request bridge',
+    );
+    return { skipped: true, reason: 'no_guardian_binding' };
+  }
+
+  // Validate that the binding's guardian identity matches the canonical request's
+  // guardian identity. A mismatch can occur if a guardian rebind happens between
+  // message ingress and confirmation emission — sending the notification to the
+  // new binding would leak requester/tool metadata to the wrong recipient.
+  //
+  // Both sides are canonicalized before comparison because the canonical request
+  // value was normalized by resolveGuardianContext() while the binding stores the
+  // raw identity. On phone channels the same guardian can have format variance
+  // (e.g. "+1 555-123-4567" vs "+15551234567") that would cause a false mismatch.
+  const canonicalBindingId = canonicalizeInboundIdentity(sourceChannel, binding.guardianExternalUserId);
+  const canonicalRequestId = canonicalRequest.guardianExternalUserId
+    ? canonicalizeInboundIdentity(sourceChannel, canonicalRequest.guardianExternalUserId)
+    : null;
+  if (
+    canonicalRequestId &&
+    canonicalBindingId !== canonicalRequestId
+  ) {
+    log.warn(
+      {
+        sourceChannel,
+        assistantId,
+        bindingGuardianId: binding.guardianExternalUserId,
+        expectedGuardianId: canonicalRequest.guardianExternalUserId,
+        requestId: canonicalRequest.id,
+      },
+      'Guardian binding identity does not match canonical request guardian — skipping notification to prevent misrouting',
+    );
+    return { skipped: true, reason: 'binding_identity_mismatch' };
+  }
+
+  const senderLabel = guardianContext.requesterIdentifier
+    || guardianContext.requesterExternalUserId
+    || 'unknown';
+
+  const questionText = `Tool approval request: ${toolName}`;
+
+  // Emit guardian.question notification so the guardian is alerted.
+  const signalPromise = emitNotificationSignal({
+    sourceEventName: 'guardian.question',
+    sourceChannel,
+    sourceSessionId: conversationId,
+    assistantId,
+    attentionHints: {
+      requiresAction: true,
+      urgency: 'high',
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    contextPayload: {
+      requestKind: 'tool_approval' as const,
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode ?? canonicalRequest.id.slice(0, 6).toUpperCase(),
+      sourceChannel,
+      requesterExternalUserId: guardianContext.requesterExternalUserId,
+      requesterChatId: guardianContext.requesterChatId ?? null,
+      requesterIdentifier: senderLabel,
+      toolName,
+      questionText,
+    },
+    dedupeKey: `tc-confirmation-request:${canonicalRequest.id}`,
+    onThreadCreated: (info) => {
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: 'vellum',
+        destinationConversationId: info.conversationId,
+      });
+    },
+  });
+
+  // Record channel deliveries from the notification pipeline (fire-and-forget).
+  void signalPromise.then((signalResult) => {
+    for (const result of signalResult.deliveryResults) {
+      if (result.channel === 'vellum') continue; // handled in onThreadCreated
+      if (result.channel !== 'telegram' && result.channel !== 'sms') continue;
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: result.channel,
+        destinationChatId: result.destination.length > 0 ? result.destination : undefined,
+      });
+    }
+  }).catch((err) => {
+    log.warn({ err, requestId: canonicalRequest.id }, 'Failed to record channel deliveries for guardian bridge');
+  });
+
+  log.info(
+    {
+      sourceChannel,
+      requesterExternalUserId: guardianContext.requesterExternalUserId,
+      toolName,
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode,
+    },
+    'Guardian notified of trusted-contact confirmation request',
+  );
+
+  // Return the signal ID synchronously from the promise-producing call.
+  // The actual signal ID is not available until the promise resolves, but
+  // callers only need to know it was bridged — the ID is for diagnostics.
+  // We use the canonical request ID as a stable correlation key.
+  return { bridged: true, signalId: canonicalRequest.id };
+}

package/src/runtime/guardian-action-followup-executor.ts

@@ -1,7 +1,7 @@
 /**
  * Guardian action follow-up executor.
  *
- * After the conversation engine (M5) classifies the guardian's reply as
+ * After the conversation engine classifies the guardian's reply as
  * `call_back` or `message_back` and transitions the follow-up state to
  * `dispatching`, this module executes the actual action:
  *

package/src/runtime/guardian-context-resolver.ts

@@ -62,6 +62,88 @@ export function resolveGuardianContext(input: ResolveGuardianContextInput): Guar
   };
 }
 
+// ---------------------------------------------------------------------------
+// Routing-state helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Routing state for a channel actor turn.
+ *
+ * Determines whether a turn should be treated as interactive (the caller
+ * can be kept waiting for a guardian to respond to an approval prompt) by
+ * combining trust class with guardian route resolvability.
+ *
+ * A guardian route is "resolvable" when a verified guardian binding exists
+ * for the channel — meaning there is a concrete destination to deliver
+ * approval notifications to. Without a resolvable guardian route, entering
+ * an interactive wait (up to 300s) is a dead-end: no guardian will ever
+ * see the prompt.
+ */
+export interface RoutingState {
+  /** Whether the actor's trust class alone permits interactive waits. */
+  canBeInteractive: boolean;
+  /** Whether a verified guardian destination exists for this channel. */
+  guardianRouteResolvable: boolean;
+  /**
+   * Whether the turn should actually enter an interactive prompt wait.
+   * True only when the actor can be interactive AND a guardian route is
+   * resolvable. This is the canonical decision used by processMessage.
+   */
+  promptWaitingAllowed: boolean;
+}
+
+/**
+ * Compute the routing state for a channel actor turn.
+ *
+ * Guardian actors are always interactive (they self-approve).
+ * Trusted contacts are only interactive when a guardian binding exists
+ * to receive approval notifications. Unknown actors are never interactive.
+ */
+export function resolveRoutingState(ctx: GuardianContext): RoutingState {
+  const isGuardian = ctx.trustClass === 'guardian';
+  const isTrustedContact = ctx.trustClass === 'trusted_contact';
+
+  // Guardians self-approve — they are always interactive and route-resolvable.
+  if (isGuardian) {
+    return {
+      canBeInteractive: true,
+      guardianRouteResolvable: true,
+      promptWaitingAllowed: true,
+    };
+  }
+
+  // Trusted contacts can be interactive only if a guardian destination
+  // exists. The guardian binding populates guardianExternalUserId during
+  // trust resolution; its presence means there is a verified guardian
+  // to route approval notifications to.
+  const guardianRouteResolvable = !!ctx.guardianExternalUserId;
+  if (isTrustedContact) {
+    return {
+      canBeInteractive: true,
+      guardianRouteResolvable,
+      promptWaitingAllowed: guardianRouteResolvable,
+    };
+  }
+
+  // Unknown actors are never interactive.
+  return {
+    canBeInteractive: false,
+    guardianRouteResolvable: !!ctx.guardianExternalUserId,
+    promptWaitingAllowed: false,
+  };
+}
+
+/**
+ * Convenience: compute routing state from a GuardianRuntimeContext
+ * (the shape persisted in stored payloads and used by the retry sweep).
+ */
+export function resolveRoutingStateFromRuntime(ctx: GuardianRuntimeContext): RoutingState {
+  return resolveRoutingState({
+    trustClass: ctx.trustClass,
+    guardianExternalUserId: ctx.guardianExternalUserId,
+  });
+}
+
 export function toGuardianRuntimeContext(sourceChannel: ChannelId, ctx: GuardianContext): GuardianRuntimeContext {
   return {
     sourceChannel,

package/src/runtime/guardian-outbound-actions.ts

@@ -16,7 +16,8 @@ import { sendMessage as sendSms } from '../messaging/providers/sms/client.js';
 import { getCredentialMetadata } from '../tools/credentials/metadata-store.js';
 import { getLogger } from '../util/logger.js';
 import { normalizePhoneNumber } from '../util/phone.js';
-import { normalizeAssistantId, readHttpToken } from '../util/platform.js';
+import { readHttpToken } from '../util/platform.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
 import {
   countRecentSendsToDestination,
   createOutboundSession,
@@ -93,7 +94,6 @@ function getTelegramBotUsername(): string | undefined {
 
 export interface StartOutboundParams {
   channel: ChannelId;
-  assistantId?: string;
   destination?: string;
   rebind?: boolean;
   /** Origin conversation ID so completion/failure pointers can route back. */
@@ -102,14 +102,12 @@ export interface StartOutboundParams {
 
 export interface ResendOutboundParams {
   channel: ChannelId;
-  assistantId?: string;
   /** Origin conversation ID so completion/failure pointers can route back on resend. */
   originConversationId?: string;
 }
 
 export interface CancelOutboundParams {
   channel: ChannelId;
-  assistantId?: string;
 }
 
 /**
@@ -243,7 +241,7 @@ function initiateGuardianVoiceCall(
 // ---------------------------------------------------------------------------
 
 export function startOutbound(params: StartOutboundParams): OutboundActionResult {
-  const assistantId = normalizeAssistantId(params.assistantId ?? 'self');
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
   const channel = params.channel;
   const originConversationId = params.originConversationId;
 
@@ -541,7 +539,7 @@ function startOutboundVoice(
 // ---------------------------------------------------------------------------
 
 export function resendOutbound(params: ResendOutboundParams): OutboundActionResult {
-  const assistantId = normalizeAssistantId(params.assistantId ?? 'self');
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
   const channel = params.channel;
   const originConversationId = params.originConversationId;
 
@@ -707,7 +705,7 @@ export function resendOutbound(params: ResendOutboundParams): OutboundActionResu
 // ---------------------------------------------------------------------------
 
 export function cancelOutbound(params: CancelOutboundParams): OutboundActionResult {
-  const assistantId = normalizeAssistantId(params.assistantId ?? 'self');
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
   const channel = params.channel;
 
   const session = findActiveSession(assistantId, channel);