@vellumai/assistant 0.8.3 → 0.8.4

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

@@ -2,10 +2,7 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { FeedItem } from "../../home/feed-types.js";
 import type { NotificationSignal } from "../signal.js";
-import type {
-  NotificationDecision,
-  NotificationDeliveryResult,
-} from "../types.js";
+import type { NotificationDecision } from "../types.js";
 
 // ── Module mocks ───────────────────────────────────────────────────────
 //
@@ -97,7 +94,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    const item = await writeHomeFeedItemForSignal(signal, decision);
 
     expect(conversationLookups).toEqual(["conv-source-1"]);
     expect(item).not.toBeNull();
@@ -114,6 +111,10 @@ describe("writeHomeFeedItemForSignal", () => {
     expect(appended.title).toBe("Background job done");
     expect(appended.summary).toBe("Summary of what happened.");
     expect(appended.urgency).toBe("medium");
+    // The button in the home detail panel navigates to the source
+    // conversation that emitted the notification, not the conversation the
+    // notification pipeline spawned to handle it.
+    expect(appended.conversationId).toBe("conv-source-1");
     expect(typeof appended.timestamp).toBe("string");
     expect(appended.createdAt).toBe(appended.timestamp);
   });
@@ -129,15 +130,16 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item).toBeNull();
     expect(appendCalls).toHaveLength(0);
   });
 
   test("isAsyncBackground hint writes even when sourceContextId does not resolve", async () => {
-    // No conversation row matches; the conversation lookup is bypassed
-    // entirely because the hint short-circuits the filter.
+    // Source lookup throws — treated as non-navigable, so the item lands
+    // without a `conversationId` and the "Go to Thread" button hides on the
+    // client. The async-background hint still forces the mirror.
     conversationLookupShouldThrow = true;
     const signal = makeSignal({
       sourceContextId: "not-a-conversation-id",
@@ -154,21 +156,22 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    const item = await writeHomeFeedItemForSignal(signal, decision);
 
     expect(item).not.toBeNull();
     expect(appendCalls).toHaveLength(1);
     expect(appendCalls[0]!.urgency).toBe("high");
-    // The async-background short-circuit must not consult the conversation store.
-    expect(conversationLookups).toHaveLength(0);
+    expect(appendCalls[0]!.conversationId).toBeUndefined();
+    expect(conversationLookups).toEqual(["not-a-conversation-id"]);
   });
 
   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.
+    // `isAsyncBackground: false`. The assistant_tool channel forces the
+    // mirror; the source-id lookup misses so the item lands without a
+    // `conversationId` and the "Go to Thread" button hides on the client.
     conversationRow = null;
     const signal = makeSignal({
       sourceChannel: "assistant_tool",
@@ -188,47 +191,106 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    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);
+    expect(appendCalls[0]!.conversationId).toBeUndefined();
+    expect(conversationLookups).toEqual(["cli-12345"]);
   });
 
-  test("vellum delivery result conversationId propagates onto the feed item", async () => {
-    conversationRow = { conversationType: "background" };
-    const signal = makeSignal();
+  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
+    // via the `isAsyncBackground` hint but `conversationId` stays undefined
+    // so the client hides the "Go to Thread" affordance.
+    conversationRow = null;
+    const signal = makeSignal({
+      sourceContextId: "scheduler-job-42",
+      attentionHints: {
+        requiresAction: false,
+        urgency: "medium",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+    });
     const decision = makeDecision({
       renderedCopy: {
         vellum: { title: "Routed title", body: "Routed body" },
       },
     });
-    const deliveryResults: NotificationDeliveryResult[] = [
-      {
-        channel: "telegram",
-        destination: "chat-1",
-        status: "sent",
-        conversationId: "conv-telegram-1",
+
+    const item = await writeHomeFeedItemForSignal(signal, decision);
+
+    expect(item?.conversationId).toBeUndefined();
+    expect(appendCalls[0]!.conversationId).toBeUndefined();
+    expect(conversationLookups).toEqual(["scheduler-job-42"]);
+  });
+
+  test("falls back to the paired delivery conversation when sourceContextId does not resolve", async () => {
+    // Regression: producers whose `sourceContextId` is a sentinel string
+    // (heartbeat startup `"heartbeat"`, credential health `connectionId`,
+    // watcher `watcher-<ts>`, scheduler retries-exhausted `jobId`, sweep
+    // job id) never resolve via `getConversation`. The notification
+    // broadcaster pairs each vellum delivery with a real conversation
+    // before the home-feed write runs, so the caller threads that paired
+    // id through as the fallback — the "Go to Convo" button now points at
+    // the conversation the notification was actually delivered into.
+    conversationRow = null;
+    const signal = makeSignal({
+      sourceChannel: "assistant_tool",
+      sourceEventName: "assistant.share",
+      sourceContextId: "watcher-1700000000",
+      contextPayload: { title: "Watcher alert" },
+      attentionHints: {
+        requiresAction: false,
+        urgency: "medium",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+    });
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: { title: "Watcher alert", body: "Watcher body" },
       },
-      {
-        channel: "vellum",
-        destination: "vellum-client",
-        status: "sent",
-        conversationId: "conv-vellum-1",
+    });
+
+    const item = await writeHomeFeedItemForSignal(
+      signal,
+      decision,
+      "paired-delivery-conv-id",
+    );
+
+    expect(item).not.toBeNull();
+    expect(appendCalls).toHaveLength(1);
+    expect(appendCalls[0]!.conversationId).toBe("paired-delivery-conv-id");
+  });
+
+  test("source conversation id wins over the paired delivery fallback when both are available", async () => {
+    // When the producer's `sourceContextId` already points at a real
+    // conversation (the canonical "where the work happened"), prefer it
+    // over the paired delivery — the fallback is only meant to fill the
+    // gap for sentinel-id producers.
+    conversationRow = { conversationType: "background" };
+    const signal = makeSignal({
+      contextPayload: { title: "Background job done" },
+    });
+    const decision = makeDecision({
+      renderedCopy: {
+        vellum: { title: "Background job done", body: "Summary." },
       },
-    ];
+    });
 
     const item = await writeHomeFeedItemForSignal(
       signal,
       decision,
-      deliveryResults,
+      "paired-delivery-conv-id",
     );
 
-    expect(item?.conversationId).toBe("conv-vellum-1");
-    expect(appendCalls[0]!.conversationId).toBe("conv-vellum-1");
+    expect(item).not.toBeNull();
+    expect(appendCalls[0]!.conversationId).toBe("conv-source-1");
   });
 
   test("returns null and does not write when no rendered copy or payload title/body is present", async () => {
@@ -238,7 +300,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: {},
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item).toBeNull();
     expect(appendCalls).toHaveLength(0);
@@ -251,7 +313,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Real title" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item).toBeNull();
     expect(appendCalls).toHaveLength(0);
@@ -268,7 +330,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { body: "Real body" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item).not.toBeNull();
     expect(appendCalls).toHaveLength(1);
@@ -294,7 +356,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    const item = await writeHomeFeedItemForSignal(signal, decision);
 
     expect(item).not.toBeNull();
     expect(appendCalls).toHaveLength(1);
@@ -314,7 +376,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    const item = await writeHomeFeedItemForSignal(signal, decision);
 
     expect(item).toBeNull();
     expect(appendCalls).toHaveLength(0);
@@ -340,7 +402,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    const item = await writeHomeFeedItemForSignal(signal, decision);
 
     expect(item).not.toBeNull();
     expect(appendCalls).toHaveLength(1);
@@ -372,7 +434,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    const item = await writeHomeFeedItemForSignal(signal, decision);
 
     expect(item).not.toBeNull();
     expect(appendCalls).toHaveLength(1);
@@ -400,7 +462,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, decision, []);
+    const item = await writeHomeFeedItemForSignal(signal, decision);
 
     expect(item).toBeNull();
     expect(appendCalls).toHaveLength(0);
@@ -423,7 +485,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item).not.toBeNull();
     expect(appendCalls).toHaveLength(1);
@@ -438,7 +500,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Payload title", body: "Payload body" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item).not.toBeNull();
     expect(item?.title).toBe("Payload title");
@@ -456,7 +518,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Tool share", body: "Body" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(true);
     expect(appendCalls[0]!.noteworthy).toBe(true);
@@ -470,7 +532,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Tool share", body: "Body" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.fromAssistant).toBe(true);
     expect(appendCalls[0]!.fromAssistant).toBe(true);
@@ -484,7 +546,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Reminder", body: "Time to do thing" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.fromAssistant).toBe(false);
     expect(appendCalls[0]!.fromAssistant).toBe(false);
@@ -498,7 +560,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Reminder", body: "Time to do thing" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(false);
     expect(appendCalls[0]!.noteworthy).toBe(false);
@@ -512,7 +574,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Question", body: "Approve?" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(true);
     expect(appendCalls[0]!.noteworthy).toBe(true);
@@ -532,7 +594,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(true);
     expect(appendCalls[0]!.noteworthy).toBe(true);
@@ -552,7 +614,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(false);
     expect(appendCalls[0]!.noteworthy).toBe(false);
@@ -578,7 +640,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(false);
     expect(appendCalls[0]!.noteworthy).toBe(false);
@@ -600,7 +662,7 @@ describe("writeHomeFeedItemForSignal", () => {
       },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(true);
     expect(appendCalls[0]!.noteworthy).toBe(true);
@@ -614,7 +676,7 @@ describe("writeHomeFeedItemForSignal", () => {
       contextPayload: { title: "Credential expired", body: "Reconnect" },
     });
 
-    const item = await writeHomeFeedItemForSignal(signal, makeDecision(), []);
+    const item = await writeHomeFeedItemForSignal(signal, makeDecision());
 
     expect(item?.noteworthy).toBe(true);
     expect(appendCalls[0]!.noteworthy).toBe(true);

package/src/notifications/conversation-seed-composer.ts

@@ -156,8 +156,20 @@ export function composeConversationSeed(
 
   if (verbosity === "rich") {
     const parts: string[] = [];
-    if (copy.title && copy.title !== "Notification") parts.push(copy.title);
-    if (copy.body) parts.push(copy.body);
+    const usableTitle =
+      copy.title && copy.title !== "Notification" ? copy.title : "";
+    const hasBody = Boolean(copy.body && copy.body.trim());
+    // copy.title is used as the conversation header in chat surfaces
+    // whenever copy.conversationTitle is absent (see
+    // conversation-pairing.ts), so prepending it here would render it
+    // twice — once in the header bar and once at the start of the
+    // bubble. Skip it in that case, unless there's no body and we'd
+    // otherwise produce an empty seed. Treat whitespace-only bodies as
+    // empty so the title still populates the bubble.
+    if (usableTitle && (copy.conversationTitle || !hasBody)) {
+      parts.push(usableTitle);
+    }
+    if (hasBody) parts.push(copy.body);
     const alreadyMentionsAction = parts.some((part) =>
       /\baction required\b/i.test(part),
     );

package/src/notifications/deferred-emit.ts

@@ -0,0 +1,135 @@
+/**
+ * Per-conversation notification buffer used to keep a background job's
+ * "success" notification from racing the runner's `activity.failed` when
+ * the job times out after the model already invoked `notifications send`.
+ *
+ * `registerDeferredConversation` arms the buffer before the LLM turn.
+ * `bufferIfDeferred` is called from the IPC route handler — it buffers when
+ * armed, swallows when tombstoned (post-discard grace window), and returns
+ * null otherwise so the route emits normally.
+ * `commitDeferredConversation` flushes on success; `discardDeferredConversation`
+ * drops on failure and tombstones briefly to catch late tool calls that
+ * arrive after `processMessage` keeps running past the runner's timeout.
+ */
+
+import { v4 as uuid } from "uuid";
+
+import { getLogger } from "../util/logger.js";
+import {
+  emitNotificationSignal,
+  type EmitSignalParams,
+  type EmitSignalResult,
+} from "./emit-signal.js";
+
+const log = getLogger("notifications-deferred-emit");
+
+// How long after the last observed late notification we keep the tombstone
+// alive. `work` in `runBackgroundJob` is not cancelled on timeout — it can
+// continue running and emit skill calls indefinitely. We refresh the timer
+// on every late arrival, so the tombstone persists as long as the turn is
+// still draining and only expires once the conversation has been quiet for
+// this long.
+const TOMBSTONE_TTL_MS = 5 * 60 * 1000;
+
+type BufferEntry =
+  | { state: "buffered"; items: EmitSignalParams<string>[] }
+  | { state: "tombstoned"; timer: ReturnType<typeof setTimeout> };
+
+const buffers = new Map<string, BufferEntry>();
+
+function scheduleTombstoneEviction(
+  conversationId: string,
+): ReturnType<typeof setTimeout> {
+  const timer = setTimeout(() => {
+    const cur = buffers.get(conversationId);
+    if (cur?.state === "tombstoned") buffers.delete(conversationId);
+  }, TOMBSTONE_TTL_MS);
+  timer.unref?.();
+  return timer;
+}
+
+export function registerDeferredConversation(conversationId: string): void {
+  buffers.set(conversationId, { state: "buffered", items: [] });
+}
+
+/**
+ * Buffer the signal when the originating conversation is armed, swallow it
+ * when tombstoned, otherwise return null so the caller emits normally.
+ */
+export function bufferIfDeferred(
+  originatingConversationId: string | undefined,
+  params: EmitSignalParams<string>,
+): EmitSignalResult | null {
+  if (!originatingConversationId) return null;
+  const entry = buffers.get(originatingConversationId);
+  if (!entry) return null;
+  if (entry.state === "tombstoned") {
+    // Refresh the eviction timer so the tombstone outlives any continuing
+    // turn activity. Otherwise a long-running orphan `processMessage` could
+    // emit a `notifications send` after the fixed TTL elapsed and bypass
+    // buffering, recreating the "success + activity.failed" contradiction.
+    clearTimeout(entry.timer);
+    entry.timer = scheduleTombstoneEviction(originatingConversationId);
+    return {
+      signalId: uuid(),
+      deduplicated: false,
+      dispatched: false,
+      reason: "Notification dropped: background job did not complete",
+      deliveryResults: [],
+    };
+  }
+  entry.items.push(params);
+  return {
+    signalId: uuid(),
+    deduplicated: false,
+    dispatched: false,
+    reason: "Notification deferred until background job completes",
+    deliveryResults: [],
+  };
+}
+
+export async function commitDeferredConversation(
+  conversationId: string,
+): Promise<void> {
+  const entry = buffers.get(conversationId);
+  if (!entry || entry.state !== "buffered") return;
+  buffers.delete(conversationId);
+  for (const params of entry.items) {
+    try {
+      await emitNotificationSignal(params);
+    } catch (err) {
+      log.warn(
+        { err, conversationId },
+        "Buffered notification failed to emit on commit",
+      );
+    }
+  }
+}
+
+/**
+ * Drop any buffered signals and tombstone the conversation. The tombstone
+ * persists until the turn has been quiet for `TOMBSTONE_TTL_MS`; each late
+ * notification observed via `bufferIfDeferred` refreshes the timer.
+ */
+export function discardDeferredConversation(conversationId: string): number {
+  const entry = buffers.get(conversationId);
+  if (!entry) return 0;
+  const droppedCount = entry.state === "buffered" ? entry.items.length : 0;
+  if (entry.state === "tombstoned") clearTimeout(entry.timer);
+  buffers.set(conversationId, {
+    state: "tombstoned",
+    timer: scheduleTombstoneEviction(conversationId),
+  });
+  if (droppedCount > 0) {
+    log.info(
+      { conversationId, droppedCount },
+      "Discarded buffered notifications for failed background job",
+    );
+  }
+  return droppedCount;
+}
+
+/** @internal Test-only reset hook. */
+export function resetDeferredForTest(): void {
+  buffers.clear();
+}

package/src/notifications/emit-signal.ts

@@ -388,10 +388,18 @@ export async function emitNotificationSignal<TEventName extends string>(
     // Step 5: Mirror background-origin signals into the home activity feed.
     // The helper itself decides whether to write (background filter); we
     // catch and log so a feed-write failure cannot poison the dispatch result.
+    // Pass the paired vellum delivery conversation as a fallback so producers
+    // whose `sourceContextId` is a sentinel string (e.g. heartbeat startup,
+    // credential health, watcher emits, scheduler retries-exhausted) still
+    // get a "Go to Convo" button — pointing at the conversation the
+    // broadcaster paired the notification with.
+    const pairedVellumConversationId = dispatchResult.deliveryResults.find(
+      (r) => r.channel === "vellum",
+    )?.conversationId;
     await writeHomeFeedItemForSignal(
       signal,
       decision,
-      dispatchResult.deliveryResults,
+      pairedVellumConversationId,
     ).catch((err) => {
       log.warn({ err, signalId }, "writeHomeFeedItemForSignal threw");
     });