@vellumai/assistant 0.10.0 → 0.10.1-dev.202606240317.ea25efe

package/src/notifications/destination-resolver.ts

@@ -1,7 +1,7 @@
 /**
  * Resolves per-channel destination endpoints for notification delivery.
  *
- * Reads guardian delivery info from the contacts table.
+ * Reads guardian delivery info from the gateway-backed guardian list.
  *
  * - Vellum: no external endpoint needed — delivery goes through the event
  *   broadcast mechanism to connected desktop/mobile clients. The
@@ -11,14 +11,54 @@
  *   sourced from the guardian contact's channel record.
  */
 
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
 import { isNotificationDeliverable } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
+import { guardianForChannel } from "../contacts/guardian-delivery-reader.js";
 import { getLogger } from "../util/logger.js";
 import type { ChannelDestination, NotificationChannel } from "./types.js";
 
 const log = getLogger("destination-resolver");
 
+/** Guardian delivery endpoint for a channel, flattened from either source. */
+interface ResolvedGuardian {
+  principalId?: string;
+  address: string;
+  externalChatId?: string;
+}
+
+/**
+ * Resolve the guardian delivery endpoint for a channel: gateway list first,
+ * else the local contacts read. The local read is the transitional
+ * dual-written mirror and covers a transient gateway failure (null list) or a
+ * gateway list missing this channel, so a soft-failed gateway read does not
+ * drop a binding the local store still holds. Removed in Combo 11.
+ */
+function resolveGuardian(
+  guardians: GuardianDelivery[] | null,
+  channelType: string,
+): ResolvedGuardian | undefined {
+  const g = guardians
+    ? guardianForChannel(guardians, channelType)
+    : undefined;
+  if (g) {
+    return {
+      principalId: g.principalId ?? undefined,
+      address: g.address,
+      externalChatId: g.externalChatId ?? undefined,
+    };
+  }
+  const local = findGuardianForChannel(channelType);
+  if (!local) return undefined;
+  return {
+    principalId: local.contact.principalId ?? undefined,
+    address: local.channel.address,
+    externalChatId: local.channel.externalChatId ?? undefined,
+  };
+}
+
 /**
  * Resolve destination information for each requested channel.
  *
@@ -26,9 +66,14 @@ const log = getLogger("destination-resolver");
  * the function skips non-deliverable channels via `isNotificationDeliverable`.
  * Returns a map keyed by `NotificationChannel`. Channels that cannot be
  * resolved (e.g. no Telegram binding configured) are omitted from the result.
+ *
+ * `guardians` is the gateway-resolved guardian list; per channel, a missing
+ * match (null list or no entry for the channel) falls back to the local
+ * contacts read for this release.
  */
 export function resolveDestinations(
   channels: readonly (ChannelId | NotificationChannel)[],
+  guardians: GuardianDelivery[] | null,
 ): Map<NotificationChannel, ChannelDestination> {
   const result = new Map<NotificationChannel, ChannelDestination>();
 
@@ -43,10 +88,10 @@ export function resolveDestinations(
         // Vellum delivery is local — no external endpoint required.
         // Include the guardianPrincipalId so the adapter can annotate
         // guardian-sensitive notifications for scoped delivery.
-        const guardianResult = findGuardianForChannel("vellum");
+        const guardian = resolveGuardian(guardians, "vellum");
         const metadata: Record<string, unknown> = {};
-        if (guardianResult) {
-          metadata.guardianPrincipalId = guardianResult.contact.principalId;
+        if (guardian?.principalId) {
+          metadata.guardianPrincipalId = guardian.principalId;
         }
         result.set("vellum", {
           channel: "vellum",
@@ -55,7 +100,7 @@ export function resolveDestinations(
         log.debug(
           {
             channel: "vellum",
-            source: "contacts",
+            source: "guardian-delivery",
             hasEndpoint: false,
           },
           "destination resolved",
@@ -63,52 +108,52 @@ export function resolveDestinations(
         break;
       }
       case "telegram": {
-        const guardianResult = findGuardianForChannel(channel);
-        if (guardianResult && guardianResult.channel.externalChatId) {
-          const externalChatId = guardianResult.channel.externalChatId;
+        const guardian = resolveGuardian(guardians, channel);
+        if (guardian?.externalChatId) {
+          const externalChatId = guardian.externalChatId;
           result.set(channel as NotificationChannel, {
             channel: channel as NotificationChannel,
             endpoint: externalChatId,
             metadata: {
-              externalUserId: guardianResult.channel.address,
+              externalUserId: guardian.address,
             },
             bindingContext: {
               sourceChannel: channel as NotificationChannel,
               externalChatId,
-              externalUserId: guardianResult.channel.address,
+              externalUserId: guardian.address,
             },
           });
         }
         log.debug(
           {
             channel,
-            source: "contacts",
-            hasEndpoint: !!guardianResult?.channel.externalChatId,
+            source: "guardian-delivery",
+            hasEndpoint: !!guardian?.externalChatId,
           },
           "destination resolved",
         );
         break;
       }
       case "slack": {
-        const guardianResult = findGuardianForChannel("slack");
-        const chatId = guardianResult?.channel.externalChatId;
+        const guardian = resolveGuardian(guardians, "slack");
+        const chatId = guardian?.externalChatId;
         // Slack bindings can originate from app_mention in shared channels.
         // Only route notifications to DM channels (IDs starting with "D")
         // to prevent leaking notifications into shared workspaces.
-        if (guardianResult && chatId && isSlackDmChannel(chatId)) {
+        if (guardian && chatId && isSlackDmChannel(chatId)) {
           result.set("slack", {
             channel: "slack",
             endpoint: chatId,
             metadata: {
-              externalUserId: guardianResult.channel.address,
+              externalUserId: guardian.address,
             },
             bindingContext: {
               sourceChannel: "slack",
               externalChatId: chatId,
-              externalUserId: guardianResult.channel.address,
+              externalUserId: guardian.address,
             },
           });
-        } else if (guardianResult && chatId) {
+        } else if (guardian && chatId) {
           log.warn(
             { channel: "slack", chatId },
             "skipping non-DM Slack channel for notification delivery",
@@ -117,7 +162,7 @@ export function resolveDestinations(
         log.debug(
           {
             channel: "slack",
-            source: "contacts",
+            source: "guardian-delivery",
             hasEndpoint: !!(chatId && isSlackDmChannel(chatId)),
           },
           "destination resolved",
@@ -128,11 +173,10 @@ export function resolveDestinations(
         // Platform delivery goes through the daemon's VellumPlatformClient —
         // no external binding needed. Include guardianPrincipalId so the
         // adapter can scope guardian-sensitive notifications.
-        const platformGuardian = findGuardianForChannel("vellum");
+        const platformGuardian = resolveGuardian(guardians, "vellum");
         const platformMeta: Record<string, unknown> = {};
-        if (platformGuardian) {
-          platformMeta.guardianPrincipalId =
-            platformGuardian.contact.principalId;
+        if (platformGuardian?.principalId) {
+          platformMeta.guardianPrincipalId = platformGuardian.principalId;
         }
         result.set("platform", {
           channel: "platform",
@@ -140,7 +184,7 @@ export function resolveDestinations(
             Object.keys(platformMeta).length > 0 ? platformMeta : undefined,
         });
         log.debug(
-          { channel: "platform", source: "contacts", hasEndpoint: false },
+          { channel: "platform", source: "guardian-delivery", hasEndpoint: false },
           "destination resolved",
         );
         break;

package/src/notifications/deterministic-checks.ts

@@ -3,8 +3,13 @@
  *
  * These checks run after the decision engine produces a NotificationDecision
  * and before the broadcaster dispatches. They enforce hard invariants that
- * the LLM cannot override: channel availability, source-active suppression,
- * deduplication, and schema validity.
+ * the LLM cannot override: channel availability, deduplication, schema
+ * validity, and rendered-copy quality.
+ *
+ * Source-active suppression is also a hard invariant, but it depends only on
+ * the signal — not on the decision — so `emitNotificationSignal` runs it as a
+ * pre-decision gate, short-circuiting before the expensive LLM stage rather
+ * than discarding the decision after it. See `checkSourceActiveSuppression`.
  */
 
 import { and, eq } from "drizzle-orm";
@@ -52,17 +57,7 @@ export async function runDeterministicChecks(
     return schemaCheck;
   }
 
-  // Check 2: Source-active suppression
-  const sourceActiveCheck = checkSourceActiveSuppression(signal);
-  if (!sourceActiveCheck.passed) {
-    log.info(
-      { signalId: signal.signalId, reason: sourceActiveCheck.reason },
-      "Deterministic check failed: source active",
-    );
-    return sourceActiveCheck;
-  }
-
-  // Check 3: Channel availability
+  // Check 2: Channel availability
   const channelCheck = checkChannelAvailability(
     decision,
     context.connectedChannels,
@@ -75,7 +70,7 @@ export async function runDeterministicChecks(
     return channelCheck;
   }
 
-  // Check 4: Dedupe
+  // Check 3: Dedupe
   const dedupeCheck = checkDedupe(
     signal,
     decision,
@@ -89,7 +84,7 @@ export async function runDeterministicChecks(
     return dedupeCheck;
   }
 
-  // Check 5: Rendered copy quality (fail-closed)
+  // Check 4: Rendered copy quality (fail-closed)
   const copyCheck = checkRenderedCopyQuality(signal, decision);
   if (!copyCheck.passed) {
     log.info(
@@ -151,8 +146,16 @@ function checkDecisionSchema(decision: NotificationDecision): CheckResult {
 /**
  * If the user is already looking at the source context (visibleInSourceNow),
  * suppress the notification to avoid redundant alerts.
+ *
+ * This depends only on the signal, not on the decision, so the outcome is
+ * knowable before the decision engine runs. `emitNotificationSignal` calls it
+ * as a pre-decision gate to short-circuit statically-suppressed signals
+ * (e.g. trusted-contact `verification_sent`) before paying for an LLM
+ * inference whose result would be discarded. Exported for that caller.
  */
-function checkSourceActiveSuppression(signal: NotificationSignal): CheckResult {
+export function checkSourceActiveSuppression(
+  signal: NotificationSignal,
+): CheckResult {
   if (signal.attentionHints.visibleInSourceNow) {
     return {
       passed: false,

package/src/notifications/emit-signal.ts

@@ -9,10 +9,15 @@
  * propagated unless `throwOnError` is enabled.
  */
 
+import type { GuardianDelivery } from "@vellumai/gateway-client";
 import { v4 as uuid } from "uuid";
 
 import { getDeliverableChannels } from "../channels/config.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
+import {
+  getGuardianDelivery,
+  guardianForChannel,
+} from "../contacts/guardian-delivery-reader.js";
 import type { ConversationCreateType } from "../memory/conversation-crud.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
@@ -27,6 +32,7 @@ import {
 import { enforceRoutingIntent, evaluateSignal } from "./decision-engine.js";
 import { updateDecision } from "./decisions-store.js";
 import {
+  checkSourceActiveSuppression,
   type DeterministicCheckContext,
   runDeterministicChecks,
 } from "./deterministic-checks.js";
@@ -88,9 +94,33 @@ export function getBroadcaster(): NotificationBroadcaster {
 
 // ── Connected channels resolution ──────────────────────────────────────
 
-function getConnectedChannels(): NotificationChannel[] {
+/**
+ * Resolve a binding-based channel's delivery endpoint (externalChatId) the
+ * SAME way destination-resolver's `resolveGuardian` does: gateway match first,
+ * falling back to the LOCAL contacts read on ANY per-channel no-match — gateway
+ * list null (unreachable) OR no active gateway entry for this channel. The
+ * local read is the transitional dual-written mirror, removed in Combo 11.
+ * Keeping connectivity aligned with delivery prevents a channel being marked
+ * connected but then skipped with no destination (or vice-versa).
+ */
+function resolveChannelChatId(
+  guardians: GuardianDelivery[] | null,
+  channelType: string,
+): string | undefined {
+  const g = guardians ? guardianForChannel(guardians, channelType) : undefined;
+  if (g) {
+    return g.externalChatId ?? undefined;
+  }
+  return findGuardianForChannel(channelType)?.channel.externalChatId ?? undefined;
+}
+
+export async function getConnectedChannels(): Promise<NotificationChannel[]> {
   const channels: NotificationChannel[] = [];
 
+  // Guardian bindings (ACL) come from the gateway pull; null ⇒ gateway
+  // unreachable, so binding-based connectivity falls back to the local read.
+  const guardians = await getGuardianDelivery();
+
   // getDeliverableChannels() returns ChannelId[] but every returned channel
   // has deliveryEnabled: true, making it a valid NotificationChannel at
   // runtime. We iterate over the broad type and narrow via the switch.
@@ -109,24 +139,20 @@ function getConnectedChannels(): NotificationChannel[] {
         channels.push(channel);
         break;
       case "telegram": {
-        // A binding-based channel is connected when the guardian has an
-        // active channel entry with a valid delivery endpoint. The
-        // externalChatId check ensures we don't report a channel as
-        // connected when the contacts record exists but lacks the
-        // delivery address the destination-resolver needs.
-        const guardian = findGuardianForChannel(channel);
-        if (guardian && guardian.channel.externalChatId) {
+        // Connected when the resolved guardian has a delivery endpoint —
+        // mirroring destination-resolver so we never mark connected what
+        // can't be delivered.
+        if (resolveChannelChatId(guardians, channel)) {
           channels.push(channel);
         }
         break;
       }
       case "slack": {
         // Slack bindings can originate from shared channels (app_mention).
-        // Only consider Slack connected when the stored chat ID is a DM
-        // channel (D-prefixed) to prevent leaking notifications.
-        const slackGuardian = findGuardianForChannel("slack");
-        const chatId = slackGuardian?.channel.externalChatId;
-        if (slackGuardian && chatId && chatId.startsWith("D")) {
+        // Only consider Slack connected when the resolved chat ID is a DM
+        // channel (D-prefixed), matching destination-resolver's DM gate.
+        const chatId = resolveChannelChatId(guardians, "slack");
+        if (chatId && chatId.startsWith("D")) {
           channels.push(channel);
         }
         break;
@@ -209,7 +235,12 @@ export interface EmitSignalResult {
 
 /**
  * Emit a notification signal through the full pipeline:
- * createEvent -> evaluateSignal -> runDeterministicChecks -> dispatchDecision.
+ * createEvent -> (source-active pre-gate) -> evaluateSignal ->
+ * runDeterministicChecks -> dispatchDecision.
+ *
+ * Source-active suppression runs before the decision engine: it depends only
+ * on the signal, so a statically-suppressed signal short-circuits here without
+ * paying for an LLM inference whose result would be discarded downstream.
  *
  * Fire-and-forget safe by default: errors are caught and logged unless
  * `throwOnError` is enabled by the caller.
@@ -261,8 +292,30 @@ export async function emitNotificationSignal<TEventName extends string>(
       };
     }
 
+    // Step 1.5: Source-active pre-gate. visibleInSourceNow is a hard invariant
+    // the decision engine cannot override, and it depends only on the signal —
+    // so when it is set, the outcome is predetermined: suppress. Short-circuit
+    // before the (LLM-backed) decision stage so statically-suppressed signals
+    // (e.g. trusted-contact verification_sent) never incur an inference, a
+    // discarded decision row, or an LLM-dependent home-feed mirror. The event
+    // row persisted above preserves the lifecycle/audit trail.
+    const sourceActiveCheck = checkSourceActiveSuppression(signal);
+    if (!sourceActiveCheck.passed) {
+      log.info(
+        { signalId, reason: sourceActiveCheck.reason },
+        "Signal suppressed before decision stage (source-active)",
+      );
+      return {
+        signalId,
+        deduplicated: false,
+        dispatched: false,
+        reason: `Signal suppressed: ${sourceActiveCheck.reason}`,
+        deliveryResults: [],
+      };
+    }
+
     // Step 2: Evaluate the signal through the decision engine
-    const connectedChannels = getConnectedChannels();
+    const connectedChannels = await getConnectedChannels();
 
     log.debug(
       {

package/src/notifications/trusted-contact-payloads.ts

@@ -0,0 +1,70 @@
+/**
+ * Typed context payloads for the trusted-contact lifecycle notification signals.
+ *
+ * These `ingress.trusted_contact.*` signals are emitted from the canonical
+ * resolver (`approvals/guardian-request-resolvers.ts`), and the decision
+ * payload is read back by the notification copy-composer. A single zod schema
+ * is the source of truth for both sides, so the producer cannot drift from the
+ * consumer.
+ *
+ * Identity fields are nullable: producers populate them (using "" for an
+ * unknown id), but a payload read back off persisted JSON may legitimately
+ * carry a null/absent identity, and the copy-composer degrades per-field. Only
+ * `sourceChannel` and `decision` are strict — they gate routing and rendering.
+ *
+ * Shapes are zod schemas (single source of truth for runtime validation and
+ * TypeScript types), matching the `guardian.question` payload pattern.
+ * https://zod.dev/?id=basic-usage
+ */
+
+import { z } from "zod";
+
+import { NotificationSourceChannelSchema } from "./signal.js";
+
+/** Identity fields shared by every trusted-contact lifecycle payload. */
+const TrustedContactIdentitySchema = z.object({
+  sourceChannel: NotificationSourceChannelSchema,
+  requesterExternalUserId: z.string().nullable(),
+  requesterChatId: z.string().nullable(),
+  requesterDisplayName: z.string().nullable(),
+  decidedByDisplayName: z.string().nullable(),
+});
+
+/**
+ * Payload for `ingress.trusted_contact.guardian_decision` and
+ * `ingress.trusted_contact.denied` — the guardian's verdict on an access
+ * request. The deny path emits both events from one object; the approve path
+ * emits `guardian_decision` with `decision: "approved"` (identical shape).
+ */
+export const TrustedContactDecisionPayloadSchema =
+  TrustedContactIdentitySchema.extend({
+    decidedByExternalUserId: z.string().nullable(),
+    decision: z.enum(["approved", "denied"]),
+  });
+export type TrustedContactDecisionPayload = z.infer<
+  typeof TrustedContactDecisionPayloadSchema
+>;
+
+/**
+ * Payload for `ingress.trusted_contact.verification_sent` — the verification
+ * code was minted and delivered. Carries the session id; no `decision`.
+ */
+export const TrustedContactVerificationSentPayloadSchema =
+  TrustedContactIdentitySchema.extend({
+    verificationSessionId: z.string(),
+  });
+export type TrustedContactVerificationSentPayload = z.infer<
+  typeof TrustedContactVerificationSentPayloadSchema
+>;
+
+/**
+ * Parse an unknown context payload as a trusted-contact decision payload.
+ * Returns the typed payload on success, or `null` when the shape doesn't match
+ * — the copy-composer falls back to generic copy in that case.
+ */
+export function parseTrustedContactDecisionPayload(
+  payload: Record<string, unknown>,
+): TrustedContactDecisionPayload | null {
+  const result = TrustedContactDecisionPayloadSchema.safeParse(payload);
+  return result.success ? result.data : null;
+}

package/src/oauth/byo-connection.test.ts

@@ -113,6 +113,15 @@ mock.module("./oauth-store.js", () => ({
     if (opts?.account && conn.accountInfo !== opts.account) return undefined;
     return conn;
   },
+  getActiveConnections: (
+    service: string,
+    opts?: { clientId?: string; account?: string },
+  ) => {
+    const conn = mockConnections.get(service);
+    if (!conn) return [];
+    if (opts?.account && conn.accountInfo !== opts.account) return [];
+    return [conn];
+  },
   getConnection: (id: string) => {
     for (const conn of mockConnections.values()) {
       if (conn.id === id) return conn;