@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/notifications/__tests__/deterministic-checks.test.ts

@@ -107,10 +107,10 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   });
 
   test("fails when body is the raw source event name", async () => {
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       renderedCopy: {
-        vellum: { title: "Reminder", body: "user.send_notification" },
+        vellum: { title: "Reminder", body: "assistant.share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, context);
@@ -119,10 +119,10 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   });
 
   test("fails when body matches the normalized source event name", async () => {
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       renderedCopy: {
-        vellum: { title: "Reminder", body: "user send notification" },
+        vellum: { title: "Reminder", body: "assistant share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, context);
@@ -174,11 +174,11 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   test("still validates body quality for channels with rendered copy", async () => {
     // Even when some channels lack copy (broadcaster fallback territory),
     // channels that DO have copy must still pass the empty/event-name checks.
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       selectedChannels: ["vellum", "telegram"],
       renderedCopy: {
-        telegram: { title: "Reminder", body: "user.send_notification" },
+        telegram: { title: "Reminder", body: "assistant.share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, {
@@ -194,7 +194,7 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
     // a usable body (no template for sourceEventName → buildGenericCopy
     // returns body=""), the gate must fail-closed rather than letting
     // dispatchDecision report 0/N sent.
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       selectedChannels: ["vellum"],
       renderedCopy: {},
@@ -218,7 +218,7 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   });
 
   test("passes when shouldNotify is false regardless of copy contents", async () => {
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       shouldNotify: false,
       // Empty body + event-name body would both fail the copy check if
@@ -286,11 +286,11 @@ describe("checkRenderedCopyQuality (via runDeterministicChecks)", () => {
   test("still fails non-pass-through decision when body matches event name", async () => {
     // Regression guard: the pass-through short-circuit must not weaken
     // the check for LLM/fallback paths.
-    const signal = makeSignal({ sourceEventName: "user.send_notification" });
+    const signal = makeSignal({ sourceEventName: "assistant.share" });
     const decision = makeDecision({
       reasoningSummary: "llm classification",
       renderedCopy: {
-        vellum: { title: "Reminder", body: "user.send_notification" },
+        vellum: { title: "Reminder", body: "assistant.share" },
       },
     });
     const result = await runDeterministicChecks(signal, decision, context);

package/src/notifications/__tests__/home-feed-side-effect.test.ts

@@ -281,7 +281,9 @@ describe("writeHomeFeedItemForSignal", () => {
       "The deployment completed successfully.",
     );
     expect(appendCalls[0]!.conversationId).toBe("conv-source-1");
-    expect(appendCalls[0]!.metadata?.notificationConversationMessageId).toBeUndefined();
+    expect(
+      appendCalls[0]!.metadata?.notificationConversationMessageId,
+    ).toBeUndefined();
     expect(messageAppends).toEqual([]);
     expect(messagesInvalidated).toEqual([]);
     expect(conversationLookups).toEqual(["conv-source-1", "conv-source-1"]);
@@ -352,6 +354,93 @@ describe("writeHomeFeedItemForSignal", () => {
     expect(conversationLookups).toEqual(["cli-12345"]);
   });
 
+  test("assistant_tool source skips the automatic Home mirror when channelAllowlist omits vellum", async () => {
+    conversationRow = null;
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+      contextPayload: {
+        title: "Telegram only",
+        channelAllowlist: ["telegram"],
+      },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "critical",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+    const decision = makeDecision({
+      selectedChannels: ["telegram"],
+      renderedCopy: {
+        telegram: { title: "Telegram only", body: "Alarm body" },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision);
+
+    expect(item).toBeNull();
+    expect(appendCalls).toHaveLength(0);
+  });
+
+  test("assistant_tool source still mirrors when channelAllowlist includes vellum", async () => {
+    conversationRow = null;
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+      contextPayload: {
+        title: "Inbox and telegram",
+        channelAllowlist: ["vellum", "telegram"],
+      },
+    });
+    const decision = makeDecision({
+      selectedChannels: ["vellum", "telegram"],
+      renderedCopy: {
+        vellum: { title: "Inbox and telegram", body: "Shared body" },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+  });
+
+  test("assistant_tool exclusive allowlist still mirrors when isAsyncBackground is set", async () => {
+    conversationRow = null;
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+      contextPayload: {
+        title: "Background telegram",
+        channelAllowlist: ["telegram"],
+      },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "low",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+    });
+    const decision = makeDecision({
+      selectedChannels: ["telegram"],
+      renderedCopy: {
+        telegram: { title: "Background telegram", body: "Still a feed item" },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.noteworthy).toBe(true);
+    expect(appendCalls[0]!.conversationId).toBeUndefined();
+    expect(conversationLookups).toEqual(["cli-12345"]);
+  });
+
   test("source conversation id does not propagate when the lookup misses", async () => {
     // When `sourceContextId` does not resolve to a real conversation row
     // (e.g. scheduler job id, watcher event id), the item is still mirrored
@@ -956,7 +1045,7 @@ describe("writeHomeFeedItemForSignal", () => {
     conversationRow = { conversationType: "background" };
     const signal = makeSignal({
       sourceChannel: "assistant_tool",
-      sourceEventName: "user.send_notification",
+      sourceEventName: "assistant.share",
       contextPayload: { title: "Tool share", body: "Body" },
     });
 
@@ -970,7 +1059,7 @@ describe("writeHomeFeedItemForSignal", () => {
     conversationRow = { conversationType: "background" };
     const signal = makeSignal({
       sourceChannel: "assistant_tool",
-      sourceEventName: "user.send_notification",
+      sourceEventName: "assistant.share",
       contextPayload: { title: "Tool share", body: "Body" },
     });
 
@@ -1126,7 +1215,7 @@ describe("writeHomeFeedItemForSignal", () => {
     conversationRow = { conversationType: "background" };
     const signal = makeSignal({
       sourceChannel: "assistant_tool",
-      sourceEventName: "user.send_notification",
+      sourceEventName: "assistant.share",
       contextPayload: { title: "Tool share", body: "Body" },
     });
 

package/src/notifications/__tests__/notification-utils.test.ts

@@ -5,6 +5,7 @@ import {
   decodeLiteralLineBreaks,
   describeMedia,
   mediaEmbeds,
+  readPayloadStringArray,
   sanitizeMultilineMessagePreview,
   stripMarkdownForPreview,
 } from "../notification-utils.js";
@@ -280,6 +281,23 @@ describe("describeMedia", () => {
   });
 });
 
+describe("readPayloadStringArray", () => {
+  test("returns string entries and drops non-strings", () => {
+    expect(
+      readPayloadStringArray(
+        { channelAllowlist: ["telegram", 1, "slack"] },
+        "channelAllowlist",
+      ),
+    ).toEqual(["telegram", "slack"]);
+  });
+
+  test("returns undefined when the key is missing or not an array", () => {
+    expect(readPayloadStringArray({ channelAllowlist: "telegram" }, "channelAllowlist")).toBeUndefined();
+    expect(readPayloadStringArray({}, "channelAllowlist")).toBeUndefined();
+    expect(readPayloadStringArray(null, "channelAllowlist")).toBeUndefined();
+  });
+});
+
 describe("decodeLiteralLineBreaks", () => {
   test("turns literal newline escapes into real line breaks", () => {
     expect(decodeLiteralLineBreaks("Line one\\n\\nLine two")).toBe(

package/src/notifications/adapters/macos.ts

@@ -2,26 +2,26 @@
  * Vellum channel adapter — delivers notifications to connected desktop
  * and mobile clients via the daemon's event broadcast mechanism.
  *
- * The adapter broadcasts a `notification_intent` message that the Vellum
- * client uses for two distinct purposes: paired-conversation bookkeeping
- * (mark-unseen + history catch-up, fallback dedup) and posting an OS
- * banner via `UNUserNotificationCenter`. The banner posting is gated by
- * the `silent` flag — set to true for non-urgent (`low`/`medium`) signals
- * so the notification center inbox still receives the entry but the OS
- * does not surface a push banner. Urgent signals (`high`/`critical`)
- * broadcast with `silent: false` and fire the banner.
+ * The adapter broadcasts a `notification_intent` message that the client
+ * turns into an OS notification (`use-notification-intent-sync.ts` in the
+ * web client, which every first-party app runs). The `silent` flag is true
+ * for non-urgent (`low`/`medium`) signals, and the client posts nothing for
+ * those: they reach their conversation (and the home feed, for background
+ * work) without a banner.
+ * Urgent signals (`high`/`critical`) broadcast with `silent: false` and
+ * banner.
  *
  * Guardian-sensitive notifications (approval requests, access requests)
- * 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.
+ * are delivered only to connections authenticated as the guardian: the hub
+ * matches `targetActorPrincipalId` against each connection's verified
+ * principal, so no other connection ever receives the title and body. The
+ * payload's `targetGuardianPrincipalId` records that scoping for clients.
  */
 
 import type { AssistantEvent } from "../../api/index.js";
-import type { InterfaceId } from "../../channels/types.js";
 import { getAssistantName } from "../../daemon/identity-helpers.js";
 import { updateMessageContent } from "../../persistence/conversation-crud.js";
+import type { BroadcastMessageOptions } from "../../runtime/assistant-event-hub.js";
 import { publishConversationMessagesChanged } from "../../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../../util/logger.js";
 import type {
@@ -36,28 +36,16 @@ import type {
 
 const log = getLogger("notif-adapter-vellum");
 
-/**
- * Optional targeting/filtering applied at the hub when a broadcast is
- * emitted. Mirrors the third argument of
- * `broadcastMessage()` in `runtime/assistant-event-hub.ts`. Callers can
- * use `targetInterfaceId` to scope a legacy message to a single client
- * surface (e.g. macOS) during a migration window.
- */
-export interface BroadcastFnOptions {
-  targetClientId?: string;
-  targetInterfaceId?: InterfaceId;
-}
-
 export type BroadcastFn = (
   msg: AssistantEvent,
   conversationId?: string,
-  options?: BroadcastFnOptions,
+  options?: BroadcastMessageOptions,
 ) => void;
 
 /**
  * Event name prefixes that carry guardian-sensitive content (approval
- * requests, access requests). Notifications for these events are scoped
- * to bound guardian devices via `targetGuardianPrincipalId`.
+ * requests, access requests). Notifications for these events reach only
+ * the guardian's own connections.
  */
 const GUARDIAN_SENSITIVE_EVENT_PREFIXES = [
   "guardian.question",
@@ -86,10 +74,9 @@ export class VellumAdapter implements ChannelAdapter {
     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.
+      // For guardian-sensitive events, deliver only to the guardian's own
+      // connections. The guardianPrincipalId comes from the vellum binding
+      // resolved by the destination resolver.
       const guardianPrincipalId =
         typeof destination.metadata?.guardianPrincipalId === "string"
           ? destination.metadata.guardianPrincipalId
@@ -104,20 +91,24 @@ export class VellumAdapter implements ChannelAdapter {
         payload.urgency !== "high" && payload.urgency !== "critical";
       const assistantName = getAssistantName()?.trim() || undefined;
 
-      this.broadcast({
-        type: "notification_intent",
-        deliveryId: payload.deliveryId,
-        correlationId: payload.correlationId,
-        sourceEventName: payload.sourceEventName,
-        ...(assistantName ? { assistantName } : {}),
-        title: payload.copy.title,
-        body: payload.copy.body,
-        deepLinkMetadata: payload.deepLinkTarget,
-        targetGuardianPrincipalId,
-        silent,
-        remotePushDispatched: payload.remotePushDispatched,
-        remotePushPlatforms: payload.remotePushPlatforms,
-      } as AssistantEvent);
+      this.broadcast(
+        {
+          type: "notification_intent",
+          deliveryId: payload.deliveryId,
+          correlationId: payload.correlationId,
+          sourceEventName: payload.sourceEventName,
+          ...(assistantName ? { assistantName } : {}),
+          title: payload.copy.title,
+          body: payload.copy.body,
+          deepLinkMetadata: payload.deepLinkTarget,
+          targetGuardianPrincipalId,
+          silent,
+          remotePushDispatched: payload.remotePushDispatched,
+          remotePushPlatforms: payload.remotePushPlatforms,
+        },
+        undefined,
+        { targetActorPrincipalId: targetGuardianPrincipalId },
+      );
 
       log.info(
         {

package/src/notifications/broadcaster.ts

@@ -241,8 +241,8 @@ export interface ConversationCreatedInfo {
   /** Semantic source from the signal producer (e.g. "schedule", "reminder"). */
   source?: string;
   /**
-   * Mirrors the vellum adapter's `silent` flag. When true the client
-   * must skip the fallback OS banner — the sidebar entry still appears.
+   * Mirrors the vellum adapter's `silent` flag (true for low- and
+   * medium-urgency signals).
    */
   silent: boolean;
 }
@@ -354,10 +354,9 @@ export class NotificationBroadcaster {
 
     // Ensure vellum is processed first so the notification_conversation_created
     // event fires immediately, before slower channel sends (e.g. Telegram 30s
-    // timeout) can delay it past the macOS deep-link retry window. Platform
-    // sorts second: the vellum intent carries remotePushDispatched, so its
-    // deferred send (below) flushes right after the platform outcome is known
-    // instead of waiting behind slower channels.
+    // timeout) can delay it. Platform sorts second: the vellum intent carries
+    // remotePushDispatched, so its deferred send (below) flushes right after
+    // the platform outcome is known instead of waiting behind slower channels.
     const dispatchRank = (channel: NotificationChannel): number => {
       if (channel === "vellum") {
         return 0;

package/src/notifications/channel-allowlist.ts

@@ -0,0 +1,44 @@
+/**
+ * Exclusive channel allowlist carried on a signal's `contextPayload`.
+ *
+ * When `channelAllowlist` is a non-empty string array, delivery is restricted
+ * to that set intersected with connected channels. Urgent force and
+ * routing-intent expansion do not add channels outside the allowlist.
+ * `preferredChannels` stays additive and is ignored when an allowlist is
+ * present.
+ */
+
+import { readPayloadStringArray } from "./notification-utils.js";
+import type { NotificationChannel } from "./types.js";
+
+export function readChannelAllowlist(payload: unknown): string[] | undefined {
+  const raw = readPayloadStringArray(payload, "channelAllowlist");
+  if (!raw) {
+    return undefined;
+  }
+  const channels = raw.map((entry) => entry.trim()).filter((entry) => {
+    return entry.length > 0;
+  });
+  return channels.length > 0 ? channels : undefined;
+}
+
+export function hasExclusiveChannelAllowlist(payload: unknown): boolean {
+  return readChannelAllowlist(payload) !== undefined;
+}
+
+export function intersectChannelAllowlist(
+  allowlist: readonly string[],
+  available: readonly NotificationChannel[],
+): NotificationChannel[] {
+  const availableSet = new Set<string>(available);
+  const seen = new Set<string>();
+  const selected: NotificationChannel[] = [];
+  for (const channel of allowlist) {
+    if (!availableSet.has(channel) || seen.has(channel)) {
+      continue;
+    }
+    seen.add(channel);
+    selected.push(channel as NotificationChannel);
+  }
+  return selected;
+}

package/src/notifications/copy-composer.ts

@@ -331,29 +331,24 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     body: str(payload.body, "A watcher event occurred"),
   }),
 
-  "watcher.escalation": (payload) => ({
-    title: str(payload.title, "Watcher Escalation"),
-    body: str(payload.body, "A watcher event requires your attention"),
-  }),
-
-  "tool_confirmation.required_action": (payload) => {
-    const toolName = str(payload.toolName, "A tool");
-    return {
-      title: `${toolName} needs your confirmation`,
-      body: `${toolName} requires your confirmation`,
-    };
-  },
-
   // Titled by what was done rather than by the kind of event: the summary's
   // first sentence is the outcome ("Finished the fuel-system diagnostic app"),
-  // which is what a reader scanning the bell wants to see. A summary without
-  // one still gets a title that says something happened.
+  // which is what a reader scanning the bell wants to see. A producer that
+  // names its subject in the payload keeps that name here, read in the same
+  // order the home feed reads it, so the headline is the same whether or not
+  // the classifier ran. A summary with neither still gets a title that says
+  // something happened.
   "activity.complete": (payload) => {
     const summary = nonEmpty(
       typeof payload.summary === "string" ? payload.summary : undefined,
     );
+    const authored = normalizeTitle(
+      readPayloadString(payload, "title") ??
+        readPayloadString(payload, "requestedTitle") ??
+        "",
+    );
     return {
-      title: summary ? deriveTitle(summary) : "Activity complete",
+      title: authored || (summary ? deriveTitle(summary) : "Activity complete"),
       body: summary ?? "An activity has completed",
     };
   },
@@ -377,16 +372,6 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
       body: summary !== "" ? summary : describeUnclassifiedFailure(payload),
     };
   },
-
-  "quick_chat.response_ready": (payload) => ({
-    title: "Quick chat reply ready",
-    body: str(payload.preview, "Your quick chat response is ready"),
-  }),
-
-  "voice.response_ready": (payload) => ({
-    title: "Voice reply ready",
-    body: str(payload.preview, "A voice response is ready"),
-  }),
 };
 
 /**

package/src/notifications/decision-engine.ts

@@ -35,6 +35,10 @@ import {
   buildAccessRequestSeedContentBlocks,
   buildToolApprovalSeedContentBlocks,
 } from "./approval-card-data.js";
+import {
+  intersectChannelAllowlist,
+  readChannelAllowlist,
+} from "./channel-allowlist.js";
 import {
   buildConversationCandidates,
   type ConversationCandidateSet,
@@ -52,6 +56,7 @@ import {
   nonEmpty,
   readPayloadObject,
   readPayloadString,
+  readPayloadStringArray,
 } from "./notification-utils.js";
 import { getPreferenceSummary } from "./preference-summary.js";
 import type { NotificationSignal, RoutingIntent } from "./signal.js";
@@ -887,22 +892,27 @@ export async function evaluateSignal(
       signal.attentionHints.urgency,
       availableChannels,
     );
-    // Honor `--preferred-channels` as ADDITIVE push targets on top of
-    // the default channel set. The notification center (vellum) is the
-    // always-on canonical inbox; preferred channels add push surfaces
-    // on top, they never replace vellum. Disconnected channels are
-    // filtered out so we never try to deliver on something unavailable.
-    const preferredChannelsRaw = Array.isArray(payload.preferredChannels)
-      ? (payload.preferredChannels as unknown[]).filter(
-          (c): c is string => typeof c === "string",
-        )
-      : undefined;
+    // `channelAllowlist` is exclusive: only those available channels are
+    // selected. `preferredChannels` is additive on top of the default set
+    // (vellum stays the canonical inbox) and is ignored when an allowlist
+    // is present. Disconnected names are dropped so we never deliver on
+    // something unavailable.
+    const exclusiveAllowlist = readChannelAllowlist(payload);
+    const preferredChannelsRaw = readPayloadStringArray(
+      payload,
+      "preferredChannels",
+    );
     let selectedChannels = defaultChannels;
-    if (preferredChannelsRaw && preferredChannelsRaw.length > 0) {
+    if (exclusiveAllowlist) {
+      selectedChannels = intersectChannelAllowlist(
+        exclusiveAllowlist,
+        availableChannels,
+      );
+    } else if (preferredChannelsRaw && preferredChannelsRaw.length > 0) {
       const availableSet = new Set<string>(availableChannels);
-      const preferredAvailable = preferredChannelsRaw.filter((c) =>
-        availableSet.has(c),
-      ) as NotificationChannel[];
+      const preferredAvailable = preferredChannelsRaw.filter((c) => {
+        return availableSet.has(c);
+      }) as NotificationChannel[];
       if (preferredAvailable.length > 0) {
         selectedChannels = Array.from(
           new Set<NotificationChannel>([

package/src/notifications/deterministic-checks.ts

@@ -254,7 +254,7 @@ function checkDedupe(
 /**
  * Fail-closed check that the rendered copy is real text and not an
  * accidental fallback leak (empty body, or body that is just the raw
- * source event name like "user.send_notification").
+ * source event name like "assistant.share").
  *
  * Only validates channels that the decision engine actually emitted
  * copy for. Channels appended after the decision (urgency-forced