@vellumai/assistant 0.8.2 → 0.8.3

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

@@ -83,9 +83,11 @@ beforeEach(() => {
 });
 
 describe("writeHomeFeedItemForSignal", () => {
-  test("background conversation signal writes a feed item with rendered copy", async () => {
+  test("background conversation signal writes a feed item with payload title + rendered body", async () => {
     conversationRow = { conversationType: "background" };
-    const signal = makeSignal();
+    const signal = makeSignal({
+      contextPayload: { title: "Background job done" },
+    });
     const decision = makeDecision({
       renderedCopy: {
         vellum: {
@@ -146,8 +148,13 @@ describe("writeHomeFeedItemForSignal", () => {
         visibleInSourceNow: false,
       },
     });
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: { title: "Async title", body: "Async body" },
+      },
+    });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
 
     expect(item).not.toBeNull();
     expect(appendCalls).toHaveLength(1);
@@ -156,9 +163,49 @@ describe("writeHomeFeedItemForSignal", () => {
     expect(conversationLookups).toHaveLength(0);
   });
 
+  test("assistant_tool source mirrors to the home feed even without a background conversation or async hint", async () => {
+    // Regression: the `notifications send` CLI/skill emits with
+    // `sourceChannel: "assistant_tool"`, a synthetic `cli-<ts>` source
+    // context id that does not resolve to a conversation, and
+    // `isAsyncBackground: false`. Before the fix, `shouldMirrorToHomeFeed`
+    // returned `false` for this shape and the Inbox stayed empty.
+    conversationRow = null;
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+      contextPayload: { title: "Shared from CLI" },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "low",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: { title: "Shared from CLI", body: "Body from CLI share" },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.title).toBe("Shared from CLI");
+    expect(appendCalls[0]!.noteworthy).toBe(true);
+    // The assistant_tool short-circuit must not consult the conversation store.
+    expect(conversationLookups).toHaveLength(0);
+  });
+
   test("vellum delivery result conversationId propagates onto the feed item", async () => {
     conversationRow = { conversationType: "background" };
     const signal = makeSignal();
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: { title: "Routed title", body: "Routed body" },
+      },
+    });
     const deliveryResults: NotificationDeliveryResult[] = [
       {
         channel: "telegram",
@@ -176,7 +223,7 @@ describe("writeHomeFeedItemForSignal", () => {
 
     const item = await writeHomeFeedItemForSignal(
       signal,
-      makeDecision(),
+      decision,
       deliveryResults,
     );
 
@@ -184,7 +231,7 @@ describe("writeHomeFeedItemForSignal", () => {
     expect(appendCalls[0]!.conversationId).toBe("conv-vellum-1");
   });
 
-  test("falls back to sourceEventName when no rendered copy or payload title is present", async () => {
+  test("returns null and does not write when no rendered copy or payload title/body is present", async () => {
     conversationRow = { conversationType: "scheduled" };
     const signal = makeSignal({
       sourceEventName: "watcher.notification",
@@ -193,7 +240,383 @@ describe("writeHomeFeedItemForSignal", () => {
 
     const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
 
-    expect(item?.title).toBe("watcher.notification");
-    expect(item?.summary).toBe("watcher.notification");
+    expect(item).toBeNull();
+    expect(appendCalls).toHaveLength(0);
+  });
+
+  test("returns null when only the title is available but the summary would fall back to event name", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceEventName: "example.event",
+      contextPayload: { title: "Real title" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item).toBeNull();
+    expect(appendCalls).toHaveLength(0);
+  });
+
+  test("writes a feed item with undefined title when only the body is available", async () => {
+    // Regression: when `notifications send` is called without `--title`, the
+    // notification pipeline must not manufacture a title (the LLM's rendered
+    // copy echoes the body into `renderedCopy.title`). Leave `title`
+    // undefined so renderers fall back to `summary` instead of stuttering.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceEventName: "example.event",
+      contextPayload: { body: "Real body" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.title).toBeUndefined();
+    expect(appendCalls[0]!.summary).toBe("Real body");
+  });
+
+  test("ignores LLM-rendered title when no payload title was supplied", async () => {
+    // The LLM often echoes the body verbatim into `renderedCopy.title` when
+    // the source didn't pass one. The home-feed writer must NOT promote that
+    // echo into the feed item — only an explicit source title is honored.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceEventName: "example.event",
+      contextPayload: { body: "Real body" },
+    });
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: {
+          title: "Real body",
+          body: "Real body",
+        },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.title).toBeUndefined();
+    expect(appendCalls[0]!.summary).toBe("Real body");
+  });
+
+  test("treats whitespace-only rendered copy and payload values as missing and returns null", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceEventName: "example.event",
+      contextPayload: { title: "   ", body: "\t\n" },
+    });
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: { title: "   ", body: "   " },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+
+    expect(item).toBeNull();
+    expect(appendCalls).toHaveLength(0);
+  });
+
+  test("falls back to a non-vellum channel's rendered copy when vellum copy is absent", async () => {
+    // Regression: when `preferredChannels` narrows an assistant_tool signal
+    // to a non-vellum channel (e.g. telegram), the broadcaster ships real
+    // copy on that channel but `renderedCopy.vellum` is undefined. The
+    // guard must still write to the home feed using the first available
+    // rendered copy entry rather than skipping silently.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+      contextPayload: { title: "Telegram title" },
+    });
+    const decision = makeDecision({
+      selectedChannels: ["telegram"],
+      renderedCopy: {
+        telegram: { title: "Telegram title", body: "Telegram body" },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.title).toBe("Telegram title");
+    expect(appendCalls[0]!.summary).toBe("Telegram body");
+  });
+
+  test("ignores rendered copy for channels not in selectedChannels", async () => {
+    // Regression: routing-intent enforcement can prune selectedChannels
+    // without pruning renderedCopy, leaving copy entries for channels that
+    // were never delivered. The fallback must only consider channels that
+    // actually shipped — otherwise an unselected channel's copy can land in
+    // Home in place of the selected channel's copy.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+      contextPayload: { title: "Telegram title" },
+    });
+    const decision = makeDecision({
+      selectedChannels: ["telegram"],
+      renderedCopy: {
+        slack: {
+          title: "Slack title (unselected)",
+          body: "Slack body (unselected)",
+        },
+        telegram: { title: "Telegram title", body: "Telegram body" },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.title).toBe("Telegram title");
+    expect(appendCalls[0]!.summary).toBe("Telegram body");
+  });
+
+  test("skips fallback when only unselected channels have rendered copy", async () => {
+    // Regression: if every renderedCopy entry is for a channel that was
+    // pruned from selectedChannels, treat it as no copy at all rather than
+    // surfacing the stale entry.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+    });
+    const decision = makeDecision({
+      selectedChannels: ["telegram"],
+      renderedCopy: {
+        slack: {
+          title: "Slack title (unselected)",
+          body: "Slack body (unselected)",
+        },
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+
+    expect(item).toBeNull();
+    expect(appendCalls).toHaveLength(0);
+  });
+
+  test("falls back to requestedTitle/requestedMessage payload keys", async () => {
+    // Regression: the `notifications send` CLI surface stores the
+    // user-supplied copy on the signal payload under `requestedTitle` and
+    // `requestedMessage`. If the decision strips renderedCopy.vellum (e.g.
+    // routed only to a non-vellum channel that also lacks renderedCopy),
+    // the home-feed guard must still recover the copy from the payload.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "cli-12345",
+      contextPayload: {
+        requestedTitle: "Requested title",
+        requestedMessage: "Requested message body",
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.title).toBe("Requested title");
+    expect(appendCalls[0]!.summary).toBe("Requested message body");
+  });
+
+  test("uses payload title/body when rendered copy is absent", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceEventName: "watcher.notification",
+      contextPayload: { title: "Payload title", body: "Payload body" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item).not.toBeNull();
+    expect(item?.title).toBe("Payload title");
+    expect(item?.summary).toBe("Payload body");
+    expect(appendCalls).toHaveLength(1);
+  });
+
+  // ── noteworthy derivation ────────────────────────────────────────────
+
+  test("assistant_tool source marks the feed item noteworthy", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "user.send_notification",
+      contextPayload: { title: "Tool share", body: "Body" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(true);
+    expect(appendCalls[0]!.noteworthy).toBe(true);
+  });
+
+  test("assistant_tool source sets fromAssistant=true", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "user.send_notification",
+      contextPayload: { title: "Tool share", body: "Body" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.fromAssistant).toBe(true);
+    expect(appendCalls[0]!.fromAssistant).toBe(true);
+  });
+
+  test("non-assistant_tool source sets fromAssistant=false", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "scheduler",
+      sourceEventName: "schedule.notify",
+      contextPayload: { title: "Reminder", body: "Time to do thing" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.fromAssistant).toBe(false);
+    expect(appendCalls[0]!.fromAssistant).toBe(false);
+  });
+
+  test("scheduler source with schedule.notify is not noteworthy", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "scheduler",
+      sourceEventName: "schedule.notify",
+      contextPayload: { title: "Reminder", body: "Time to do thing" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(false);
+    expect(appendCalls[0]!.noteworthy).toBe(false);
+  });
+
+  test("assistant_tool source with guardian.question event still wins (noteworthy true)", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "guardian.question",
+      contextPayload: { title: "Question", body: "Approve?" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(true);
+    expect(appendCalls[0]!.noteworthy).toBe(true);
+  });
+
+  test("activity.failed with critical urgency is noteworthy (scheduler source)", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "scheduler",
+      sourceEventName: "activity.failed",
+      contextPayload: { title: "Job failed", body: "Critical failure" },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "critical",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(true);
+    expect(appendCalls[0]!.noteworthy).toBe(true);
+  });
+
+  test("activity.failed with low urgency is not noteworthy (scheduler source)", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "scheduler",
+      sourceEventName: "activity.failed",
+      contextPayload: { title: "Job failed", body: "Routine failure" },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "low",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(false);
+    expect(appendCalls[0]!.noteworthy).toBe(false);
+  });
+
+  test("activity.failed from background-job-runner shape (assistant_tool + medium) is NOT noteworthy", async () => {
+    // Regression: `runtime/background-job-runner.ts` emits activity.failed
+    // with `sourceChannel: "assistant_tool"` and `urgency: "medium"`. Before
+    // the fix, the assistant_tool short-circuit short-circuited noteworthy
+    // to true, so every routine watcher/heartbeat failure landed in the
+    // Inbox. The activity.failed rule must run first and require critical
+    // urgency.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "activity.failed",
+      contextPayload: { title: "Job failed", body: "Routine failure" },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "medium",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(false);
+    expect(appendCalls[0]!.noteworthy).toBe(false);
+  });
+
+  test("activity.failed from assistant_tool with critical urgency IS noteworthy", async () => {
+    // Companion to the regression test above: a background-job-runner
+    // shape that opts up to critical urgency should still reach the Inbox.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "activity.failed",
+      contextPayload: { title: "Job failed", body: "Critical failure" },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "critical",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(true);
+    expect(appendCalls[0]!.noteworthy).toBe(true);
+  });
+
+  test("credential.health_alert is noteworthy regardless of source channel", async () => {
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      sourceChannel: "watcher",
+      sourceEventName: "credential.health_alert",
+      contextPayload: { title: "Credential expired", body: "Reconnect" },
+    });
+
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+
+    expect(item?.noteworthy).toBe(true);
+    expect(appendCalls[0]!.noteworthy).toBe(true);
   });
 });

package/src/notifications/adapters/macos.ts

@@ -3,8 +3,13 @@
  * and mobile clients via the daemon's event broadcast mechanism.
  *
  * The adapter broadcasts a `notification_intent` message that the Vellum
- * client can use to display a native notification (e.g. NSUserNotification
- * or UNUserNotificationCenter).
+ * 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.
  *
  * Guardian-sensitive notifications (approval requests, escalation alerts)
  * are annotated with `targetGuardianPrincipalId` so that only clients
@@ -75,6 +80,9 @@ export class VellumAdapter implements ChannelAdapter {
           ? guardianPrincipalId
           : undefined;
 
+      const silent =
+        payload.urgency !== "high" && payload.urgency !== "critical";
+
       this.broadcast({
         type: "notification_intent",
         deliveryId: payload.deliveryId,
@@ -83,6 +91,7 @@ export class VellumAdapter implements ChannelAdapter {
         body: payload.copy.body,
         deepLinkMetadata: payload.deepLinkTarget,
         targetGuardianPrincipalId,
+        silent,
       } as ServerMessage);
 
       log.info(
@@ -90,6 +99,7 @@ export class VellumAdapter implements ChannelAdapter {
           sourceEventName: payload.sourceEventName,
           title: payload.copy.title,
           guardianScoped: targetGuardianPrincipalId != null,
+          silent,
         },
         "Vellum notification intent broadcast",
       );

package/src/notifications/broadcaster.ts

@@ -45,6 +45,11 @@ export interface ConversationCreatedInfo {
   groupId?: string;
   /** 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.
+   */
+  silent: boolean;
 }
 export type OnConversationCreatedFn = (info: ConversationCreatedInfo) => void;
 export interface BroadcastDecisionOptions {
@@ -145,10 +150,25 @@ export class NotificationBroadcaster {
         if (!fallbackCopy) {
           fallbackCopy = composeFallbackCopy(signal, decision.selectedChannels);
         }
-        copy = fallbackCopy[channel] ?? {
-          title: "Notification",
-          body: signal.sourceEventName,
-        };
+        copy = fallbackCopy[channel];
+      }
+
+      // Fail closed: if neither the decision nor the fallback composer produced
+      // a usable body, skip the channel rather than leaking the raw event name
+      // as placeholder text. The pre-send `checkRenderedCopyQuality` only sees
+      // `decision.renderedCopy`, so this is the last guard before delivery.
+      if (!copy || !copy.body?.trim()) {
+        log.warn(
+          { channel, signalId: signal.signalId },
+          "No usable rendered copy available -- skipping channel to avoid leaking event name",
+        );
+        results.push({
+          channel,
+          destination: destination.endpoint ?? channel,
+          status: "skipped",
+          errorMessage: `No usable rendered copy for channel: ${channel}`,
+        });
+        continue;
       }
 
       // For tool_grant_request signals, prefer the deterministic template seed
@@ -237,6 +257,9 @@ export class NotificationBroadcaster {
 
         const conversationTitle =
           copy.conversationTitle ?? copy.title ?? signal.sourceEventName;
+        const conversationSilent =
+          signal.attentionHints.urgency !== "high" &&
+          signal.attentionHints.urgency !== "critical";
         const info: ConversationCreatedInfo = {
           conversationId: pairing.conversationId,
           title: conversationTitle,
@@ -244,6 +267,7 @@ export class NotificationBroadcaster {
           targetGuardianPrincipalId,
           groupId: signal.conversationMetadata?.groupId,
           source: signal.conversationMetadata?.source,
+          silent: conversationSilent,
         };
 
         // The per-dispatch onConversationCreated callback fires whenever a vellum
@@ -291,6 +315,7 @@ export class NotificationBroadcaster {
         copy,
         deepLinkTarget,
         contextPayload: signal.contextPayload,
+        urgency: signal.attentionHints.urgency,
       };
 
       // Compute conversation decision audit fields for the delivery record