@vellumai/assistant 0.8.5 → 0.8.6

package/src/memory/v3/validate.ts

@@ -134,58 +134,81 @@ function nodeChildrenOf(tree: TreeIndex, nodeId: string): string[] {
 }
 
 /**
- * Full DFS over `node:` adjacency from `tree.root`. Returns the set of
- * reachable node ids (for orphan-page reachability) and the back-edges that
- * close a cycle. A back-edge is an edge into a node still on the active
- * recursion stack (classic gray-node cycle detection); `visited` (black)
- * prevents re-walking shared DAG sub-nodes.
+ * Full DFS over `node:` adjacency. Returns the set of nodes reachable from
+ * `tree.root` (for orphan-page reachability) and the back-edges that close a
+ * cycle. A back-edge is an edge into a node still on the active recursion stack
+ * (classic gray-node cycle detection); `visited` (black) prevents re-walking
+ * shared DAG sub-nodes.
+ *
+ * The walk runs in two phases. The first seeds from the root and records every
+ * node it reaches in `reachableNodes`. The second sweeps any node still
+ * unvisited — a disconnected component that the root cannot reach — so cycles
+ * living entirely outside the root's reach are still reported. Sweep-only nodes
+ * are deliberately kept out of `reachableNodes`: they are *not* reachable from
+ * the root, and pages hanging off them must still surface as orphans.
  */
 function descend(tree: TreeIndex): {
   reachableNodes: Set<string>;
   cycles: Array<{ from: string; to: string }>;
 } {
   const reachableNodes = new Set<string>();
-  const onStack = new Set<string>();
+  const visited = new Set<string>();
   const cycles: Array<{ from: string; to: string }> = [];
 
   // Iterative DFS with an explicit stack so deep trees don't blow the call
   // stack. Each frame tracks its child cursor; we push a child frame, and on
   // exhaustion pop the parent off the recursion stack (`onStack`).
   type Frame = { node: string; children: string[]; cursor: number };
-  const stack: Frame[] = [];
 
-  function enter(nodeId: string): void {
-    reachableNodes.add(nodeId);
-    onStack.add(nodeId);
-    stack.push({
-      node: nodeId,
-      children: nodeChildrenOf(tree, nodeId),
-      cursor: 0,
-    });
+  function walkFrom(start: string, trackReachable: boolean): void {
+    const onStack = new Set<string>();
+    const stack: Frame[] = [];
+
+    function enter(nodeId: string): void {
+      visited.add(nodeId);
+      if (trackReachable) reachableNodes.add(nodeId);
+      onStack.add(nodeId);
+      stack.push({
+        node: nodeId,
+        children: nodeChildrenOf(tree, nodeId),
+        cursor: 0,
+      });
+    }
+
+    enter(start);
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (frame.cursor >= frame.children.length) {
+        onStack.delete(frame.node);
+        stack.pop();
+        continue;
+      }
+      const child = frame.children[frame.cursor++];
+      if (onStack.has(child)) {
+        // Edge into an ancestor still on the stack → cycle-closing back-edge.
+        cycles.push({ from: frame.node, to: child });
+        continue;
+      }
+      if (visited.has(child)) {
+        // Already fully explored (shared DAG sub-node or an earlier sweep).
+        continue;
+      }
+      enter(child);
+    }
   }
 
   if (tree.nodes.has(tree.root)) {
-    enter(tree.root);
+    walkFrom(tree.root, true);
   }
 
-  while (stack.length > 0) {
-    const frame = stack[stack.length - 1];
-    if (frame.cursor >= frame.children.length) {
-      onStack.delete(frame.node);
-      stack.pop();
-      continue;
-    }
-    const child = frame.children[frame.cursor++];
-    if (onStack.has(child)) {
-      // Edge into an ancestor still on the stack → cycle-closing back-edge.
-      cycles.push({ from: frame.node, to: child });
-      continue;
-    }
-    if (reachableNodes.has(child)) {
-      // Already fully explored via another parent (shared DAG sub-node).
-      continue;
+  // Cover nodes the root never reached (disconnected components) so a cycle
+  // among them is not silently missed. These are not root-reachable, so their
+  // pages stay eligible for the orphan-page report.
+  for (const nodeId of tree.nodes.keys()) {
+    if (!visited.has(nodeId)) {
+      walkFrom(nodeId, false);
     }
-    enter(child);
   }
 
   cycles.sort(

package/src/notifications/__tests__/emit-signal-home-feed.test.ts

@@ -34,6 +34,7 @@ mock.module("../../home/feed-writer.js", () => ({
 // home-feed-side-effect.ts only consumes `getConversation`.
 mock.module("../../memory/conversation-crud.js", () => ({
   getConversation: () => conversationRow,
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 // Stub the broadcaster so emit-signal's `getBroadcaster()` does not need

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

@@ -30,6 +30,7 @@ mock.module("../../memory/conversation-crud.js", () => ({
     }
     return conversationRow;
   },
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 const { writeHomeFeedItemForSignal } =

package/src/notifications/adapters/slack.ts

@@ -16,6 +16,8 @@ import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
   ChannelDestination,
+  ChannelUpdateContext,
+  ChannelUpdatePayload,
   DeliveryResult,
   NotificationChannel,
 } from "../types.js";
@@ -52,9 +54,7 @@ function resolveSlackMessageText(payload: ChannelDeliveryPayload): string {
  * - Optional context: message preview
  * - Context: approval code instructions + invite directive
  */
-function buildAccessRequestBlocks(
-  payload: Record<string, unknown>,
-): unknown[] {
+function buildAccessRequestBlocks(payload: Record<string, unknown>): unknown[] {
   const blocks: unknown[] = [];
 
   // Header
@@ -209,19 +209,18 @@ export class SlackAdapter implements ChannelAdapter {
       payload.contextPayload != null;
 
     try {
-      if (isAccessRequest) {
-        const blocks = buildAccessRequestBlocks(payload.contextPayload!);
-        await sendSlackReply(chatId, messageText, { blocks });
-      } else {
-        await sendSlackReply(chatId, messageText, { useBlocks: true });
-      }
+      const result = isAccessRequest
+        ? await sendSlackReply(chatId, messageText, {
+            blocks: buildAccessRequestBlocks(payload.contextPayload!),
+          })
+        : await sendSlackReply(chatId, messageText, { useBlocks: true });
 
       log.info(
-        { sourceEventName: payload.sourceEventName, chatId },
+        { sourceEventName: payload.sourceEventName, chatId, ts: result.ts },
         "Slack notification delivered",
       );
 
-      return { success: true };
+      return { success: true, messageId: result.ts };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       log.error(
@@ -231,4 +230,39 @@ export class SlackAdapter implements ChannelAdapter {
       return { success: false, error: message };
     }
   }
+
+  async update(
+    delivery: ChannelUpdateContext,
+    patch: ChannelUpdatePayload,
+  ): Promise<DeliveryResult> {
+    if (!delivery.messageId) {
+      return {
+        success: false,
+        error:
+          "missing_message_id: this delivery has no captured Slack ts (sent before edit support landed)",
+      };
+    }
+    const text = patch.body?.trim() || patch.title?.trim();
+    if (!text) {
+      return { success: false, error: "no body or title supplied for update" };
+    }
+    try {
+      const result = await sendSlackReply(delivery.destination, text, {
+        messageTs: delivery.messageId,
+        useBlocks: true,
+      });
+      log.info(
+        { chatId: delivery.destination, messageTs: delivery.messageId },
+        "Slack notification updated",
+      );
+      return { success: true, messageId: result.ts ?? delivery.messageId };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, chatId: delivery.destination, messageTs: delivery.messageId },
+        "Failed to update Slack notification",
+      );
+      return { success: false, error: message };
+    }
+  }
 }

package/src/notifications/broadcaster.ts

@@ -11,6 +11,7 @@
 
 import { v4 as uuid } from "uuid";
 
+import { getConversation } from "../memory/conversation-crud.js";
 import { getLogger } from "../util/logger.js";
 import { isGuardianSensitiveEvent } from "./adapters/macos.js";
 import { pairDeliveryWithConversation } from "./conversation-pairing.js";
@@ -72,6 +73,11 @@ export class NotificationBroadcaster {
     this.onConversationCreated = fn;
   }
 
+  /** Return the registered adapter for a channel, if any. */
+  getAdapter(channel: NotificationChannel): ChannelAdapter | undefined {
+    return this.adapters.get(channel);
+  }
+
   /**
    * Broadcast a notification decision to all selected channels.
    *
@@ -231,78 +237,93 @@ export class NotificationBroadcaster {
       );
 
       // For the vellum channel, merge the conversationId into deep-link metadata
-      // so the macOS client can navigate directly to the notification conversation.
+      // so the macOS client can navigate directly to the conversation. Prefer
+      // the paired conversation (interactive opt-in flows); otherwise fall back
+      // to the originating conversation referenced by `sourceContextId` when it
+      // resolves to a real row. Sentinel context ids (job IDs, call session IDs,
+      // access-req-* strings) leave the deep link without a conversation, and
+      // the macOS handler opens the app to its default landing.
       let deepLinkTarget = decision.deepLinkTarget;
-      if (channel === "vellum" && pairing.conversationId) {
-        deepLinkTarget = {
-          ...deepLinkTarget,
-          conversationId: pairing.conversationId,
-        };
-        if (pairing.messageId) {
-          deepLinkTarget = { ...deepLinkTarget, messageId: pairing.messageId };
-        }
-
-        // Resolve guardian scoping for conversation-created events so clients
-        // can filter guardian-sensitive conversations the same way they filter
-        // guardian-sensitive notification intents.
-        const guardianPrincipalId =
-          typeof destination.metadata?.guardianPrincipalId === "string"
-            ? destination.metadata.guardianPrincipalId
-            : undefined;
-        const targetGuardianPrincipalId =
-          guardianPrincipalId &&
-          isGuardianSensitiveEvent(signal.sourceEventName)
-            ? guardianPrincipalId
-            : undefined;
-
-        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,
-          sourceEventName: signal.sourceEventName,
-          targetGuardianPrincipalId,
-          groupId: signal.conversationMetadata?.groupId,
-          source: signal.conversationMetadata?.source,
-          silent: conversationSilent,
-        };
-
-        // The per-dispatch onConversationCreated callback fires whenever a vellum
-        // conversation is paired (new or reused) because callers like
-        // dispatchGuardianQuestion rely on it to create delivery bookkeeping
-        // rows before emitNotificationSignal() returns.
-        if (options?.onConversationCreated) {
-          try {
-            options.onConversationCreated(info);
-          } catch (err) {
-            log.error(
-              { err, signalId: signal.signalId },
-              "per-dispatch onConversationCreated callback failed — continuing broadcast",
-            );
+      if (channel === "vellum") {
+        const deepLinkConversationId =
+          pairing.conversationId ??
+          resolveSourceConversationId(signal.sourceContextId);
+        if (deepLinkConversationId) {
+          deepLinkTarget = {
+            ...deepLinkTarget,
+            conversationId: deepLinkConversationId,
+          };
+          if (pairing.messageId) {
+            deepLinkTarget = {
+              ...deepLinkTarget,
+              messageId: pairing.messageId,
+            };
           }
         }
 
-        // Emit notification_conversation_created event only when a NEW
-        // conversation was actually created. Reusing an existing conversation
-        // should not fire the event — the client already knows about the
-        // conversation.
-        if (
-          pairing.createdNewConversation &&
-          pairing.strategy === "start_new_conversation"
-        ) {
-          if (this.onConversationCreated) {
+        if (pairing.conversationId) {
+          // Resolve guardian scoping for conversation-created events so clients
+          // can filter guardian-sensitive conversations the same way they filter
+          // guardian-sensitive notification intents.
+          const guardianPrincipalId =
+            typeof destination.metadata?.guardianPrincipalId === "string"
+              ? destination.metadata.guardianPrincipalId
+              : undefined;
+          const targetGuardianPrincipalId =
+            guardianPrincipalId &&
+            isGuardianSensitiveEvent(signal.sourceEventName)
+              ? guardianPrincipalId
+              : undefined;
+
+          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,
+            sourceEventName: signal.sourceEventName,
+            targetGuardianPrincipalId,
+            groupId: signal.conversationMetadata?.groupId,
+            source: signal.conversationMetadata?.source,
+            silent: conversationSilent,
+          };
+
+          // The per-dispatch onConversationCreated callback fires whenever a vellum
+          // conversation is paired (new or reused) because callers like
+          // dispatchGuardianQuestion rely on it to create delivery bookkeeping
+          // rows before emitNotificationSignal() returns.
+          if (options?.onConversationCreated) {
             try {
-              this.onConversationCreated(info);
+              options.onConversationCreated(info);
             } catch (err) {
               log.error(
                 { err, signalId: signal.signalId },
-                "onConversationCreated callback failed — continuing broadcast",
+                "per-dispatch onConversationCreated callback failed — continuing broadcast",
               );
             }
           }
+
+          // Emit notification_conversation_created event only when a NEW
+          // conversation was actually created. Reusing an existing conversation
+          // should not fire the event — the client already knows about the
+          // conversation.
+          if (
+            pairing.createdNewConversation &&
+            pairing.strategy === "start_new_conversation"
+          ) {
+            if (this.onConversationCreated) {
+              try {
+                this.onConversationCreated(info);
+              } catch (err) {
+                log.error(
+                  { err, signalId: signal.signalId },
+                  "onConversationCreated callback failed — continuing broadcast",
+                );
+              }
+            }
+          }
         }
       }
 
@@ -354,8 +375,21 @@ export class NotificationBroadcaster {
         const adapterResult = await adapter.send(payload, destination);
 
         if (adapterResult.success) {
+          // Prefer the channel-native id the adapter just captured (e.g.
+          // Slack `ts`) so later edits can target the same message; fall
+          // back to the pairing-supplied id for channels that surface it
+          // through conversation pairing instead.
+          const resolvedMessageId =
+            adapterResult.messageId ?? pairing.messageId ?? undefined;
           if (hasPersistedDecision) {
-            updateDeliveryStatus(deliveryId, "sent");
+            updateDeliveryStatus(
+              deliveryId,
+              "sent",
+              undefined,
+              adapterResult.messageId
+                ? { messageId: adapterResult.messageId }
+                : undefined,
+            );
           }
           results.push({
             channel,
@@ -363,7 +397,7 @@ export class NotificationBroadcaster {
             status: "sent",
             sentAt: Date.now(),
             conversationId: pairing.conversationId ?? undefined,
-            messageId: pairing.messageId ?? undefined,
+            messageId: resolvedMessageId,
             conversationStrategy: pairing.strategy,
           });
         } else {
@@ -414,3 +448,20 @@ export class NotificationBroadcaster {
     return results;
   }
 }
+
+/**
+ * Resolve a signal's `sourceContextId` to a conversation id if it points at a
+ * real row. Producers may pass sentinels (job IDs, call session IDs,
+ * `access-req-*` strings) here; those simply return undefined so the deep
+ * link omits the conversation target.
+ */
+function resolveSourceConversationId(
+  sourceContextId: string | undefined,
+): string | undefined {
+  if (!sourceContextId) return undefined;
+  try {
+    return getConversation(sourceContextId) ? sourceContextId : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/notifications/conversation-pairing.ts

@@ -113,6 +113,29 @@ export async function pairDeliveryWithConversation(
       };
     }
 
+    const conversationAction = options?.conversationAction;
+    const bindingContext = options?.bindingContext;
+
+    // Passive vellum notifications surface via the home feed alone and link
+    // back to the originating conversation via `signal.sourceContextId`.
+    // Materializing a fresh per-notification conversation just to host the
+    // seed message leaves a graveyard entry in the sidebar; skip it unless
+    // the producer opted in via `requiresConversation` or the decision engine
+    // requested explicit reuse of a target conversation.
+    if (
+      strategy === "start_new_conversation" &&
+      !signal.requiresConversation &&
+      conversationAction?.action !== "reuse_existing"
+    ) {
+      return {
+        conversationId: null,
+        messageId: null,
+        strategy,
+        createdNewConversation: false,
+        conversationFallbackUsed: false,
+      };
+    }
+
     const title =
       copy.conversationTitle ?? copy.title ?? signal.sourceEventName;
 
@@ -130,9 +153,6 @@ export async function pairDeliveryWithConversation(
       ? copy.conversationSeedMessage
       : composeConversationSeed(signal, channel, copy);
 
-    const conversationAction = options?.conversationAction;
-    const bindingContext = options?.bindingContext;
-
     // Attempt to reuse an existing conversation when the model requests it
     if (conversationAction?.action === "reuse_existing") {
       const targetId = conversationAction.conversationId;

package/src/notifications/decisions-store.ts

@@ -7,7 +7,7 @@
  * were routed.
  */
 
-import { eq } from "drizzle-orm";
+import { desc, eq } from "drizzle-orm";
 
 import { getDb } from "../memory/db-connection.js";
 import { notificationDecisions } from "../memory/schema.js";
@@ -94,3 +94,34 @@ export function updateDecision(id: string, params: UpdateDecisionParams): void {
     .where(eq(notificationDecisions.id, id))
     .run();
 }
+
+/**
+ * Return the most recent decision for a given notification event, or
+ * `undefined` if none exists. The decision engine writes exactly one
+ * decision per event today, but ordering by createdAt DESC keeps this
+ * stable if that ever changes (e.g. re-decisions on retry).
+ */
+export function findLatestDecisionByEventId(
+  eventId: string,
+): NotificationDecisionRow | undefined {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(notificationDecisions)
+    .where(eq(notificationDecisions.notificationEventId, eventId))
+    .orderBy(desc(notificationDecisions.createdAt))
+    .get();
+  if (!row) return undefined;
+  return {
+    id: row.id,
+    notificationEventId: row.notificationEventId,
+    shouldNotify: row.shouldNotify === 1,
+    selectedChannels: row.selectedChannels,
+    reasoningSummary: row.reasoningSummary,
+    confidence: row.confidence,
+    fallbackUsed: row.fallbackUsed === 1,
+    promptVersion: row.promptVersion,
+    validationResults: row.validationResults,
+    createdAt: row.createdAt,
+  };
+}

package/src/notifications/deliveries-store.ts

@@ -137,6 +137,7 @@ export function updateDeliveryStatus(
   id: string,
   status: NotificationDeliveryStatus,
   error?: { code?: string; message?: string },
+  patch?: { messageId?: string },
 ): boolean {
   const db = getDb();
   const now = Date.now();
@@ -151,6 +152,9 @@ export function updateDeliveryStatus(
   if (error?.message) {
     updates.errorMessage = error.message;
   }
+  if (patch?.messageId !== undefined) {
+    updates.messageId = patch.messageId;
+  }
 
   db.update(notificationDeliveries)
     .set(updates)
@@ -160,6 +164,34 @@ export function updateDeliveryStatus(
   return rawChanges() > 0;
 }
 
+/**
+ * Update the rendered copy on an existing delivery row.
+ *
+ * Used by the edit pipeline so the delivery audit reflects the latest
+ * title/body shown to the user, not just the original send.
+ */
+export function updateDeliveryRenderedCopy(
+  id: string,
+  patch: { renderedTitle?: string; renderedBody?: string },
+): boolean {
+  const updates: Record<string, unknown> = { updatedAt: Date.now() };
+  if (patch.renderedTitle !== undefined) {
+    updates.renderedTitle = patch.renderedTitle;
+  }
+  if (patch.renderedBody !== undefined) {
+    updates.renderedBody = patch.renderedBody;
+  }
+  if (Object.keys(updates).length === 1) return false;
+
+  getDb()
+    .update(notificationDeliveries)
+    .set(updates)
+    .where(eq(notificationDeliveries.id, id))
+    .run();
+
+  return rawChanges() > 0;
+}
+
 /** Check whether a delivery already exists for a given decision+channel pair. */
 export function findDeliveryByDecisionAndChannel(
   decisionId: string,
@@ -178,3 +210,16 @@ export function findDeliveryByDecisionAndChannel(
     .get();
   return row ? rowToDelivery(row) : undefined;
 }
+
+/** Return every delivery row for a given decision. */
+export function findDeliveriesByDecisionId(
+  decisionId: string,
+): NotificationDeliveryRow[] {
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(notificationDeliveries)
+    .where(eq(notificationDeliveries.notificationDecisionId, decisionId))
+    .all();
+  return rows.map(rowToDelivery);
+}