@vellumai/assistant 0.8.2 → 0.8.3

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

@@ -422,13 +422,16 @@ async function executeBatchCall(
 /** Max concurrent individual getMessage requests (matches batch concurrency) */
 const INDIVIDUAL_CONCURRENCY = BATCH_CONCURRENCY;
 
+/** Delay between waves of individual fetches to avoid rate-limit storms (ms). */
+const INTER_WAVE_DELAY_MS = 500;
+
 /**
  * Fetch all messages individually using getMessage (no batch endpoint).
  * Used as a fallback when the batch API is unavailable (e.g. platform connections
  * that cannot expose raw tokens for the multipart batch endpoint).
  *
- * Processes messages in waves of INDIVIDUAL_CONCURRENCY to avoid unbounded
- * parallelism that would trigger 429s on high-volume paths like senderDigest.
+ * Processes messages in waves of INDIVIDUAL_CONCURRENCY with a brief inter-wave
+ * delay to avoid triggering upstream rate limits on high-volume paths.
  */
 async function fetchMessagesIndividually(
   connection: OAuthConnection,
@@ -441,6 +444,10 @@ async function fetchMessagesIndividually(
   const results: GmailMessage[] = [];
   for (let i = 0; i < messageIds.length; i += INDIVIDUAL_CONCURRENCY) {
     signal?.throwIfAborted();
+    // Delay between waves (skip before the first wave)
+    if (i > 0) {
+      await signalAwareSleep(INTER_WAVE_DELAY_MS, signal);
+    }
     const wave = messageIds.slice(i, i + INDIVIDUAL_CONCURRENCY);
     const waveResults = await Promise.all(
       wave.map((id) =>

package/src/messaging/providers/index.ts

@@ -5,7 +5,7 @@
  * matcher and send logic here.  The gateway-client consults
  * `isDirectDelivery()` before falling back to the HTTP proxy path.
  *
- * Currently supported: WhatsApp, Telegram, Slack.
+ * Currently supported: WhatsApp, Telegram, Slack, A2A.
  */
 
 import type {
@@ -15,6 +15,7 @@ import type {
 import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
 
 import { getLogger } from "../../util/logger.js";
+import { deliverA2AReply } from "./a2a/deliver.js";
 import {
   sendSlackAssistantThreadStatus,
   sendSlackAttachments,
@@ -59,6 +60,10 @@ function isSlackCallback(callbackUrl: string): boolean {
   }
 }
 
+function isA2ACallback(callbackUrl: string): boolean {
+  return matchesPathname(callbackUrl, "/deliver/a2a");
+}
+
 function parseSlackCallbackParams(callbackUrl: string): {
   channel?: string;
   threadTs?: string;
@@ -233,7 +238,8 @@ export function isDirectDelivery(callbackUrl: string): boolean {
   return (
     isWhatsAppCallback(callbackUrl) ||
     isTelegramCallback(callbackUrl) ||
-    isSlackCallback(callbackUrl)
+    isSlackCallback(callbackUrl) ||
+    isA2ACallback(callbackUrl)
   );
 }
 
@@ -254,6 +260,9 @@ export async function deliverDirect(
   if (isSlackCallback(callbackUrl)) {
     return deliverSlack(callbackUrl, payload);
   }
+  if (isA2ACallback(callbackUrl)) {
+    return deliverA2AReply(callbackUrl, payload);
+  }
 
   // Defensive — isDirectDelivery should have returned false.
   throw new Error(

package/src/notifications/__tests__/broadcaster.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Verifies the NotificationBroadcaster's fail-closed copy-resolution
+ * invariant: when neither `decision.renderedCopy[channel]` nor
+ * `composeFallbackCopy(...)[channel]` produces usable copy, the channel
+ * must be dropped rather than delivered with a synthesized body.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { NotificationSignal } from "../signal.js";
+import type {
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  DeliveryResult,
+  NotificationDecision,
+} from "../types.js";
+
+// ── Module mocks ────────────────────────────────────────────────────────
+//
+// `mock.module` is hoisted, so these intercepts apply before the module
+// under test resolves its imports. State is reset in `beforeEach`.
+
+let composeFallbackReturn: Record<string, unknown> = {};
+
+mock.module("../copy-composer.js", () => ({
+  composeFallbackCopy: () => composeFallbackReturn,
+}));
+
+mock.module("../destination-resolver.js", () => ({
+  resolveDestinations: (channels: string[]) => {
+    const map = new Map<string, ChannelDestination>();
+    for (const ch of channels) {
+      map.set(ch, { channel: ch as ChannelDestination["channel"] });
+    }
+    return map;
+  },
+}));
+
+mock.module("../conversation-pairing.js", () => ({
+  pairDeliveryWithConversation: async () => ({
+    conversationId: undefined,
+    messageId: undefined,
+    strategy: "start_new_conversation",
+    createdNewConversation: false,
+    conversationFallbackUsed: false,
+  }),
+}));
+
+mock.module("../deliveries-store.js", () => ({
+  createDelivery: () => {},
+  updateDeliveryStatus: () => {},
+  findDeliveryByDecisionAndChannel: () => undefined,
+}));
+
+mock.module("../adapters/macos.js", () => ({
+  isGuardianSensitiveEvent: () => false,
+}));
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+const { NotificationBroadcaster } = await import("../broadcaster.js");
+
+// ── Test fixtures ───────────────────────────────────────────────────────
+
+function makeSignal(
+  overrides: Partial<NotificationSignal> = {},
+): NotificationSignal {
+  return {
+    signalId: "sig-test-1",
+    createdAt: 1700000000000,
+    sourceChannel: "scheduler",
+    sourceContextId: "ctx-1",
+    sourceEventName: "user.send_notification",
+    contextPayload: {},
+    attentionHints: {
+      requiresAction: false,
+      urgency: "medium",
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    ...overrides,
+  };
+}
+
+function makeDecision(
+  overrides: Partial<NotificationDecision> = {},
+): NotificationDecision {
+  return {
+    shouldNotify: true,
+    selectedChannels: ["vellum"],
+    reasoningSummary: "test",
+    renderedCopy: {},
+    dedupeKey: "dk-1",
+    confidence: 1,
+    fallbackUsed: false,
+    persistedDecisionId: "dec-1",
+    ...overrides,
+  };
+}
+
+interface CapturedSend {
+  payload: ChannelDeliveryPayload;
+  destination: ChannelDestination;
+}
+
+function makeCapturingAdapter(channel: "vellum"): {
+  adapter: ChannelAdapter;
+  sends: CapturedSend[];
+} {
+  const sends: CapturedSend[] = [];
+  const adapter: ChannelAdapter = {
+    channel,
+    async send(
+      payload: ChannelDeliveryPayload,
+      destination: ChannelDestination,
+    ): Promise<DeliveryResult> {
+      sends.push({ payload, destination });
+      return { success: true };
+    },
+  };
+  return { adapter, sends };
+}
+
+beforeEach(() => {
+  composeFallbackReturn = {};
+});
+
+// ── Tests ───────────────────────────────────────────────────────────────
+
+describe("NotificationBroadcaster last-resort copy resolution", () => {
+  test(
+    "skips channel and does not leak raw event name when both decision " +
+      "copy and fallback composer return no usable copy",
+    async () => {
+      // Fallback composer returns nothing for the channel — the formerly
+      // leaky `??` branch in broadcaster.ts would synthesize
+      // `{ title: "Notification", body: signal.sourceEventName }`.
+      composeFallbackReturn = {};
+
+      const { adapter, sends } = makeCapturingAdapter("vellum");
+      const broadcaster = new NotificationBroadcaster([adapter]);
+
+      const signal = makeSignal();
+      const decision = makeDecision({ renderedCopy: {} });
+
+      const results = await broadcaster.broadcastDecision(signal, decision);
+
+      // Adapter must NOT receive a payload at all — the channel is skipped
+      // before the adapter is invoked, so the leak path cannot fire.
+      expect(sends.length).toBe(0);
+
+      expect(results.length).toBe(1);
+      expect(results[0]?.status).toBe("skipped");
+      expect(results[0]?.errorMessage).toContain("rendered copy");
+    },
+  );
+
+  test("skips channel when fallback composer returns an entry with an empty body", async () => {
+    // `composeFallbackCopy` can produce empty bodies via `buildGenericCopy`
+    // when no template matches the source event. The broadcaster must
+    // refuse to deliver empty-body copy rather than passing it through.
+    composeFallbackReturn = {
+      vellum: { title: "Notification", body: "" },
+    };
+
+    const { adapter, sends } = makeCapturingAdapter("vellum");
+    const broadcaster = new NotificationBroadcaster([adapter]);
+
+    const signal = makeSignal();
+    const decision = makeDecision({ renderedCopy: {} });
+
+    const results = await broadcaster.broadcastDecision(signal, decision);
+
+    expect(sends.length).toBe(0);
+    expect(results.length).toBe(1);
+    expect(results[0]?.status).toBe("skipped");
+  });
+
+  test("delivers normally when fallback composer returns a usable body", async () => {
+    composeFallbackReturn = {
+      vellum: { title: "Reminder", body: "Time to drink water" },
+    };
+
+    const { adapter, sends } = makeCapturingAdapter("vellum");
+    const broadcaster = new NotificationBroadcaster([adapter]);
+
+    const signal = makeSignal();
+    const decision = makeDecision({ renderedCopy: {} });
+
+    const results = await broadcaster.broadcastDecision(signal, decision);
+
+    expect(sends.length).toBe(1);
+    expect(sends[0]?.payload.copy.body).toBe("Time to drink water");
+    expect(results.length).toBe(1);
+    expect(results[0]?.status).toBe("sent");
+  });
+});

package/src/notifications/__tests__/decision-engine.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Tests for the assistant_tool pass-through path in the notification
+ * decision engine. When a producer hands us a verbatim message via
+ * contextPayload.requestedMessage, the engine must skip the LLM call
+ * entirely and use the producer-supplied copy as-is.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+// ── Mocks (must precede imports from mocked modules) ──────────────────
+
+mock.module("../../channels/config.js", () => ({
+  getDeliverableChannels: () => ["vellum", "telegram"],
+}));
+
+mock.module("../decisions-store.js", () => ({
+  createDecision: () => {},
+}));
+
+mock.module("../preference-summary.js", () => ({
+  getPreferenceSummary: () => undefined,
+}));
+
+mock.module("../conversation-candidates.js", () => ({
+  buildConversationCandidates: () => undefined,
+  serializeCandidatesForPrompt: () => undefined,
+}));
+
+mock.module("../../prompts/persona-resolver.js", () => ({
+  resolveGuardianPersona: () => null,
+}));
+
+mock.module("../../prompts/system-prompt.js", () => ({
+  buildCoreIdentityContext: () => null,
+}));
+
+mock.module("../../contacts/contact-store.js", () => ({
+  listGuardianChannels: () => null,
+}));
+
+// Provider mock — if `getConfiguredProvider` is ever called by the
+// assistant_tool pass-through path, this throw makes the test fail
+// loudly instead of silently exercising the LLM path.
+mock.module("../../providers/provider-send-message.js", () => ({
+  getConfiguredProvider: async () => {
+    throw new Error(
+      "getConfiguredProvider should NOT be invoked for assistant_tool pass-through",
+    );
+  },
+  createTimeout: () => ({
+    signal: new AbortController().signal,
+    cleanup: () => {},
+  }),
+  extractToolUse: () => null,
+  userMessage: (text: string) => ({ role: "user", content: text }),
+}));
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// ── Imports (after all mocks) ─────────────────────────────────────────
+
+import { enforceRoutingIntent, evaluateSignal } from "../decision-engine.js";
+import type { NotificationSignal } from "../signal.js";
+import type { NotificationChannel } from "../types.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function makeAssistantToolSignal(
+  overrides?: Partial<NotificationSignal>,
+): NotificationSignal {
+  return {
+    signalId: "sig-assistant-tool-test-1",
+    createdAt: Date.now(),
+    sourceChannel: "assistant_tool",
+    sourceContextId: "tool-call-1",
+    sourceEventName: "user.send_notification",
+    contextPayload: {
+      requestedMessage: "exact verbatim text here",
+      requestedTitle: "Custom Title",
+    },
+    attentionHints: {
+      requiresAction: false,
+      urgency: "low",
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    ...overrides,
+  };
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────
+
+describe("assistant_tool pass-through in notification decision engine", () => {
+  test("uses producer-supplied title and body verbatim, no LLM call", async () => {
+    const signal = makeAssistantToolSignal();
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+      "telegram",
+    ] as NotificationChannel[]);
+
+    expect(decision.shouldNotify).toBe(true);
+    expect(decision.selectedChannels).toContain("vellum");
+    expect(decision.renderedCopy.vellum?.body).toBe("exact verbatim text here");
+    expect(decision.renderedCopy.vellum?.title).toBe("Custom Title");
+    expect(decision.conversationActions?.vellum?.action).toBe("start_new");
+    expect(decision.reasoningSummary).toBe("assistant_tool pass-through");
+    expect(decision.fallbackUsed).toBe(false);
+    expect(decision.confidence).toBe(1.0);
+    expect(decision.dedupeKey).toBe(signal.signalId);
+  });
+
+  test("derives title from body when requestedTitle is not supplied", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "First sentence. Second sentence follows here.",
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+    ] as NotificationChannel[]);
+
+    expect(decision.shouldNotify).toBe(true);
+    expect(decision.renderedCopy.vellum?.body).toBe(
+      "First sentence. Second sentence follows here.",
+    );
+    expect(decision.renderedCopy.vellum?.title).toBe("First sentence.");
+    expect(decision.reasoningSummary).toBe("assistant_tool pass-through");
+  });
+
+  test("critical urgency selects all available channels", async () => {
+    const signal = makeAssistantToolSignal({
+      attentionHints: {
+        requiresAction: true,
+        urgency: "critical",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+    const availableChannels = ["vellum", "telegram"] as NotificationChannel[];
+    const decision = await evaluateSignal(signal, availableChannels);
+
+    expect(decision.shouldNotify).toBe(true);
+    expect(decision.selectedChannels).toEqual(
+      expect.arrayContaining(availableChannels),
+    );
+    expect(decision.selectedChannels.length).toBe(availableChannels.length);
+    expect(decision.renderedCopy.vellum?.body).toBe("exact verbatim text here");
+    expect(decision.renderedCopy.telegram?.body).toBe(
+      "exact verbatim text here",
+    );
+    expect(decision.conversationActions?.vellum?.action).toBe("start_new");
+    expect(decision.conversationActions?.telegram?.action).toBe("start_new");
+  });
+
+  test("threads contextPayload.deepLinkMetadata through to decision.deepLinkTarget", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "with deep link",
+        deepLinkMetadata: { route: "settings", anchor: "notifications" },
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+    ] as NotificationChannel[]);
+
+    expect(decision.deepLinkTarget).toEqual({
+      route: "settings",
+      anchor: "notifications",
+    });
+  });
+
+  test("omits deepLinkTarget when deepLinkMetadata is not a plain object", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "no deep link",
+        deepLinkMetadata: ["not", "a", "plain", "object"],
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+    ] as NotificationChannel[]);
+
+    expect(decision.deepLinkTarget).toBeUndefined();
+  });
+
+  test("preferredChannels adds to the default channel set (additive, not replacement)", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "also push to telegram",
+        preferredChannels: ["telegram"],
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+      "telegram",
+    ] as NotificationChannel[]);
+
+    // Vellum (canonical inbox) stays in selectedChannels; telegram is
+    // added on top. `--preferred-channels` is additive push, never a
+    // replacement for the inbox.
+    expect(decision.selectedChannels).toContain("vellum");
+    expect(decision.selectedChannels).toContain("telegram");
+    expect(decision.selectedChannels.length).toBe(2);
+    expect(decision.renderedCopy.vellum?.body).toBe("also push to telegram");
+    expect(decision.renderedCopy.telegram?.body).toBe("also push to telegram");
+  });
+
+  test("urgent + preferredChannels keeps urgent's full broadcast intact", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "urgent broadcast",
+        requestedTitle: "Heads up",
+        preferredChannels: ["telegram"],
+      },
+      attentionHints: {
+        requiresAction: true,
+        urgency: "critical",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+    const available = ["vellum", "telegram", "slack"] as NotificationChannel[];
+    const decision = await evaluateSignal(signal, available);
+
+    // Urgent broadcasts to every available channel; the additive union
+    // with preferredChannels is idempotent (telegram already included).
+    expect(decision.selectedChannels).toEqual(
+      expect.arrayContaining(available),
+    );
+    expect(decision.selectedChannels.length).toBe(available.length);
+    for (const ch of available) {
+      expect(decision.renderedCopy[ch]?.body).toBe("urgent broadcast");
+      expect(decision.renderedCopy[ch]?.title).toBe("Heads up");
+    }
+  });
+
+  test("routing-intent expansion to all_channels preserves verbatim copy on added channels", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "verbatim broadcast body",
+        requestedTitle: "verbatim broadcast title",
+      },
+      routingIntent: "all_channels",
+    });
+    const connected = ["vellum", "telegram"] as NotificationChannel[];
+    const decision = await evaluateSignal(signal, connected);
+    const enforced = enforceRoutingIntent(
+      decision,
+      "all_channels",
+      connected,
+      "assistant_tool",
+    );
+
+    expect(enforced.selectedChannels).toEqual(
+      expect.arrayContaining(["vellum", "telegram"]),
+    );
+    for (const ch of enforced.selectedChannels) {
+      expect(enforced.renderedCopy[ch]?.body).toBe("verbatim broadcast body");
+      expect(enforced.renderedCopy[ch]?.title).toBe("verbatim broadcast title");
+    }
+  });
+
+  test("preferredChannels falls back to default channel set when no overlap with availableChannels", async () => {
+    const signal = makeAssistantToolSignal({
+      contextPayload: {
+        requestedMessage: "fyi",
+        preferredChannels: ["disconnected_channel"],
+      },
+    });
+    const decision = await evaluateSignal(signal, [
+      "vellum",
+      "telegram",
+    ] as NotificationChannel[]);
+
+    expect(decision.selectedChannels).toEqual(["vellum"]);
+    expect(decision.renderedCopy.vellum?.body).toBe("fyi");
+  });
+});