@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

package/src/notifications/__tests__/destination-resolver.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Verifies resolveDestinations resolves guardian delivery endpoints from the
+ * gateway-provided guardian list, with shapes identical to the local read, and
+ * falls back to the local contacts read when the list is null.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// Local fallback read; mocked so the null-list path is deterministic.
+let localGuardian:
+  | { contact: { principalId?: string }; channel: { address: string; externalChatId?: string } }
+  | null = null;
+
+mock.module("../../contacts/contact-store.js", () => ({
+  findGuardianForChannel: (_channelType: string) => localGuardian,
+}));
+
+const { resolveDestinations } = await import("../destination-resolver.js");
+
+function guardian(
+  overrides: Partial<GuardianDelivery> & Pick<GuardianDelivery, "channelType" | "address">,
+): GuardianDelivery {
+  return {
+    contactId: "contact-1",
+    status: "active",
+    ...overrides,
+  } as GuardianDelivery;
+}
+
+describe("resolveDestinations — gateway guardian list", () => {
+  beforeEach(() => {
+    localGuardian = null;
+  });
+
+  test("vellum carries guardianPrincipalId from the gateway list", () => {
+    const list = [
+      guardian({ channelType: "vellum", address: "user@example.com", principalId: "prin-1" }),
+    ];
+    const result = resolveDestinations(["vellum"], list);
+    expect(result.get("vellum")).toEqual({
+      channel: "vellum",
+      metadata: { guardianPrincipalId: "prin-1" },
+    });
+  });
+
+  test("platform carries guardianPrincipalId from the vellum guardian", () => {
+    const list = [
+      guardian({ channelType: "vellum", address: "user@example.com", principalId: "prin-1" }),
+    ];
+    const result = resolveDestinations(["platform"], list);
+    expect(result.get("platform")).toEqual({
+      channel: "platform",
+      metadata: { guardianPrincipalId: "prin-1" },
+    });
+  });
+
+  test("telegram resolves endpoint and binding context", () => {
+    const list = [
+      guardian({
+        channelType: "telegram",
+        address: "tg-user",
+        externalChatId: "12345",
+      }),
+    ];
+    const result = resolveDestinations(["telegram"], list);
+    expect(result.get("telegram")).toEqual({
+      channel: "telegram",
+      endpoint: "12345",
+      metadata: { externalUserId: "tg-user" },
+      bindingContext: {
+        sourceChannel: "telegram",
+        externalChatId: "12345",
+        externalUserId: "tg-user",
+      },
+    });
+  });
+
+  test("telegram without externalChatId is omitted", () => {
+    const list = [guardian({ channelType: "telegram", address: "tg-user" })];
+    const result = resolveDestinations(["telegram"], list);
+    expect(result.has("telegram")).toBe(false);
+  });
+
+  test("slack resolves DM endpoint and binding context", () => {
+    const list = [
+      guardian({
+        channelType: "slack",
+        address: "slack-user",
+        externalChatId: "D123",
+      }),
+    ];
+    const result = resolveDestinations(["slack"], list);
+    expect(result.get("slack")).toEqual({
+      channel: "slack",
+      endpoint: "D123",
+      metadata: { externalUserId: "slack-user" },
+      bindingContext: {
+        sourceChannel: "slack",
+        externalChatId: "D123",
+        externalUserId: "slack-user",
+      },
+    });
+  });
+
+  test("slack non-DM channel is dropped", () => {
+    const list = [
+      guardian({
+        channelType: "slack",
+        address: "slack-user",
+        externalChatId: "C123",
+      }),
+    ];
+    const result = resolveDestinations(["slack"], list);
+    expect(result.has("slack")).toBe(false);
+  });
+
+  test("inactive guardian is ignored", () => {
+    const list = [
+      guardian({
+        channelType: "telegram",
+        address: "tg-user",
+        externalChatId: "12345",
+        status: "revoked",
+      }),
+    ];
+    const result = resolveDestinations(["telegram"], list);
+    expect(result.has("telegram")).toBe(false);
+  });
+});
+
+describe("resolveDestinations — null list falls back to local read", () => {
+  beforeEach(() => {
+    localGuardian = null;
+  });
+
+  test("telegram resolves from the local contacts read", () => {
+    localGuardian = {
+      contact: {},
+      channel: { address: "tg-user", externalChatId: "12345" },
+    };
+    const result = resolveDestinations(["telegram"], null);
+    expect(result.get("telegram")).toEqual({
+      channel: "telegram",
+      endpoint: "12345",
+      metadata: { externalUserId: "tg-user" },
+      bindingContext: {
+        sourceChannel: "telegram",
+        externalChatId: "12345",
+        externalUserId: "tg-user",
+      },
+    });
+  });
+
+  test("slack DM resolves from the local contacts read", () => {
+    localGuardian = {
+      contact: {},
+      channel: { address: "slack-user", externalChatId: "D123" },
+    };
+    const result = resolveDestinations(["slack"], null);
+    expect(result.get("slack")).toEqual({
+      channel: "slack",
+      endpoint: "D123",
+      metadata: { externalUserId: "slack-user" },
+      bindingContext: {
+        sourceChannel: "slack",
+        externalChatId: "D123",
+        externalUserId: "slack-user",
+      },
+    });
+  });
+
+  test("vellum carries principalId from the local contacts read", () => {
+    localGuardian = {
+      contact: { principalId: "prin-1" },
+      channel: { address: "user@example.com" },
+    };
+    const result = resolveDestinations(["vellum"], null);
+    expect(result.get("vellum")).toEqual({
+      channel: "vellum",
+      metadata: { guardianPrincipalId: "prin-1" },
+    });
+  });
+});
+
+describe("resolveDestinations — gateway yields no channel match falls back to local", () => {
+  beforeEach(() => {
+    localGuardian = null;
+  });
+
+  test("empty gateway list falls back to local telegram binding", () => {
+    localGuardian = {
+      contact: {},
+      channel: { address: "tg-user", externalChatId: "12345" },
+    };
+    const result = resolveDestinations(["telegram"], []);
+    expect(result.get("telegram")).toEqual({
+      channel: "telegram",
+      endpoint: "12345",
+      metadata: { externalUserId: "tg-user" },
+      bindingContext: {
+        sourceChannel: "telegram",
+        externalChatId: "12345",
+        externalUserId: "tg-user",
+      },
+    });
+  });
+
+  test("gateway list missing the channel falls back to local slack DM", () => {
+    localGuardian = {
+      contact: {},
+      channel: { address: "slack-user", externalChatId: "D123" },
+    };
+    // Gateway returns a telegram guardian but no slack entry.
+    const list = [
+      guardian({ channelType: "telegram", address: "tg", externalChatId: "999" }),
+    ];
+    const result = resolveDestinations(["slack"], list);
+    expect(result.get("slack")).toEqual({
+      channel: "slack",
+      endpoint: "D123",
+      metadata: { externalUserId: "slack-user" },
+      bindingContext: {
+        sourceChannel: "slack",
+        externalChatId: "D123",
+        externalUserId: "slack-user",
+      },
+    });
+  });
+
+  test("empty gateway list falls back to local vellum principalId", () => {
+    localGuardian = {
+      contact: { principalId: "prin-1" },
+      channel: { address: "user@example.com" },
+    };
+    const result = resolveDestinations(["vellum"], []);
+    expect(result.get("vellum")).toEqual({
+      channel: "vellum",
+      metadata: { guardianPrincipalId: "prin-1" },
+    });
+  });
+
+  test("empty gateway list with no local binding omits telegram", () => {
+    localGuardian = null;
+    const result = resolveDestinations(["telegram"], []);
+    expect(result.has("telegram")).toBe(false);
+  });
+});

package/src/notifications/broadcaster.ts

@@ -11,6 +11,7 @@
 
 import { v4 as uuid } from "uuid";
 
+import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
 import { getConversation } from "../memory/conversation-crud.js";
 import type { ApprovalUIMetadata } from "../runtime/channel-approval-types.js";
 import { getLogger } from "../util/logger.js";
@@ -171,7 +172,13 @@ export class NotificationBroadcaster {
     decision: NotificationDecision,
     options?: BroadcastDecisionOptions,
   ): Promise<NotificationDeliveryResult[]> {
-    const destinations = resolveDestinations(decision.selectedChannels);
+    // Pull the guardian list once so the resolver stays pure. A null list
+    // (gateway unreachable) falls back to the local contacts read.
+    const guardians = await getGuardianDelivery();
+    const destinations = resolveDestinations(
+      decision.selectedChannels,
+      guardians,
+    );
 
     // Ensure vellum is processed first so the notification_conversation_created
     // event fires immediately, before slower channel sends (e.g. Telegram 30s

package/src/notifications/decision-engine.ts

@@ -12,7 +12,11 @@
 import { v4 as uuid } from "uuid";
 
 import { getDeliverableChannels } from "../channels/config.js";
-import { listGuardianChannels } from "../contacts/contact-store.js";
+import { findContactInfoById } from "../contacts/contact-store.js";
+import {
+  anyGuardian,
+  getGuardianDelivery,
+} from "../contacts/guardian-delivery-reader.js";
 import { buildCoreIdentityContext } from "../prompts/system-prompt.js";
 import {
   createTimeout,
@@ -963,15 +967,19 @@ async function classifyWithLLM(
     ? truncate(rawIdentityContext, MAX_IDENTITY_CONTEXT_CHARS, "\n…[truncated]")
     : undefined;
 
-  // Resolve guardian contact notes for recipient context. Use the channel-
-  // agnostic guardian lookup so notes are available even when the only
-  // deliverable channel is "vellum" (which has no contact channel type).
+  // Resolve guardian contact notes for recipient context. The guardian's
+  // identity (ACL) comes from the gateway pull, channel-agnostic so notes are
+  // available even when the only deliverable channel is "vellum". Notes (INFO)
+  // stay local and are joined by contactId.
   let recipientNotes: string | undefined;
   try {
-    const guardianResult = listGuardianChannels();
-    if (guardianResult?.contact.notes) {
+    const guardian = anyGuardian((await getGuardianDelivery()) ?? []);
+    const notes = guardian
+      ? findContactInfoById(guardian.contactId)?.notes
+      : undefined;
+    if (notes) {
       recipientNotes = truncate(
-        guardianResult.contact.notes,
+        notes,
         MAX_IDENTITY_CONTEXT_CHARS,
         "\n…[truncated]",
       );

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/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";
@@ -89,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.
@@ -110,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;
@@ -290,7 +315,7 @@ export async function emitNotificationSignal<TEventName extends string>(
     }
 
     // Step 2: Evaluate the signal through the decision engine
-    const connectedChannels = getConnectedChannels();
+    const connectedChannels = await getConnectedChannels();
 
     log.debug(
       {