@vellumai/assistant 0.8.5 → 0.8.7

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

@@ -21,6 +21,7 @@
 import type { ConversationStrategy } from "../channels/config.js";
 import { getConversationStrategy } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
+import { isHomePageEnabled } from "../home/feature-gate.js";
 import {
   addMessage,
   createConversation,
@@ -113,6 +114,35 @@ 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.
+    //
+    // Gated on `home-page`: the home feed is the surface that hosts passive
+    // notifications, so when the flag is off there is nowhere for them to
+    // land — fall through and create a conversation (the pre-home-feed
+    // behavior) to preserve the notification's only surface.
+    if (
+      strategy === "start_new_conversation" &&
+      !signal.requiresConversation &&
+      conversationAction?.action !== "reuse_existing" &&
+      isHomePageEnabled()
+    ) {
+      return {
+        conversationId: null,
+        messageId: null,
+        strategy,
+        createdNewConversation: false,
+        conversationFallbackUsed: false,
+      };
+    }
+
     const title =
       copy.conversationTitle ?? copy.title ?? signal.sourceEventName;
 
@@ -130,9 +160,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;
@@ -146,7 +173,6 @@ export async function pairDeliveryWithConversation(
           existing.id,
           "assistant",
           messageContent,
-          undefined,
           { skipIndexing: true },
         );
 
@@ -205,7 +231,6 @@ export async function pairDeliveryWithConversation(
         conversation.id,
         "assistant",
         messageContent,
-        undefined,
         { skipIndexing: true },
       );
 
@@ -263,7 +288,6 @@ export async function pairDeliveryWithConversation(
             inboundConversation.id,
             "assistant",
             messageContent,
-            undefined,
             { skipIndexing: true },
           );
 
@@ -312,7 +336,6 @@ export async function pairDeliveryWithConversation(
             boundConversation.id,
             "assistant",
             messageContent,
-            undefined,
             { skipIndexing: true },
           );
 
@@ -376,7 +399,6 @@ export async function pairDeliveryWithConversation(
       conversation.id,
       "assistant",
       messageContent,
-      undefined,
       { skipIndexing: true },
     );
 

package/src/notifications/decision-engine.ts

@@ -957,22 +957,19 @@ async function classifyWithLLM(
   const tool = buildDecisionTool(availableChannels);
 
   try {
-    const response = await provider.sendMessage(
-      [userMessage(prompt)],
-      [tool],
+    const response = await provider.sendMessage([userMessage(prompt)], {
+      tools: [tool],
       systemPrompt,
-      {
-        config: {
-          callSite: "notificationDecision",
-          max_tokens: 2048,
-          tool_choice: {
-            type: "tool" as const,
-            name: "record_notification_decision",
-          },
+      config: {
+        callSite: "notificationDecision",
+        max_tokens: 2048,
+        tool_choice: {
+          type: "tool" as const,
+          name: "record_notification_decision",
         },
-        signal: abortSignal,
       },
-    );
+      signal: abortSignal,
+    });
     cleanup();
 
     const toolBlock = extractToolUse(response);

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);
+}

package/src/notifications/edit-notification.ts

@@ -0,0 +1,201 @@
+/**
+ * Edit an already-sent notification.
+ *
+ * Patches the home-feed entry the user actually sees, then attempts a
+ * best-effort update of any per-channel deliveries that support
+ * in-place edits (Slack via chat.update today). Feed-only fields
+ * (`urgency`, `status`) skip the channel hop — channel messages don't
+ * carry that metadata, only body/title.
+ */
+
+import {
+  type FeedItem,
+  type FeedItemStatus,
+  type FeedItemUrgency,
+} from "../home/feed-types.js";
+import { patchFeedItemContent } from "../home/feed-writer.js";
+import { getLogger } from "../util/logger.js";
+import { findLatestDecisionByEventId } from "./decisions-store.js";
+import {
+  findDeliveriesByDecisionId,
+  type NotificationDeliveryRow,
+  updateDeliveryRenderedCopy,
+} from "./deliveries-store.js";
+import { getBroadcaster } from "./emit-signal.js";
+import type { NotificationChannel } from "./types.js";
+
+const log = getLogger("edit-notification");
+
+/** Prefix used by `home-feed-side-effect` when minting feed item ids. */
+export const FEED_ITEM_ID_PREFIX = "notif:";
+
+export interface EditNotificationParams {
+  /** Feed item id (`notif:<uuid>`) or bare signal uuid. */
+  id: string;
+  title?: string;
+  body?: string;
+  urgency?: FeedItemUrgency;
+  status?: FeedItemStatus;
+}
+
+export type ChannelEditOutcome =
+  | "updated"
+  | "unsupported"
+  | "skipped"
+  | "failed";
+
+export interface ChannelEditResult {
+  channel: NotificationChannel;
+  deliveryId: string;
+  outcome: ChannelEditOutcome;
+  /** Reason for skip/failure when `outcome` is not `"updated"`. */
+  reason?: string;
+}
+
+export interface EditNotificationResult {
+  feedItem: FeedItem;
+  channels: ChannelEditResult[];
+}
+
+/**
+ * Normalize a user-supplied id into the canonical feed-item form
+ * (`notif:<uuid>`). Accepts either the full prefixed id or a bare uuid.
+ */
+export function normalizeFeedItemId(id: string): string {
+  const trimmed = id.trim();
+  if (trimmed.startsWith(FEED_ITEM_ID_PREFIX)) return trimmed;
+  return `${FEED_ITEM_ID_PREFIX}${trimmed}`;
+}
+
+/** Strip the `notif:` prefix to recover the original signal/event id. */
+export function feedItemIdToSignalId(feedItemId: string): string {
+  return feedItemId.startsWith(FEED_ITEM_ID_PREFIX)
+    ? feedItemId.slice(FEED_ITEM_ID_PREFIX.length)
+    : feedItemId;
+}
+
+/**
+ * Apply an edit to a previously-sent notification.
+ *
+ * Returns the updated feed item plus per-channel update outcomes.
+ * Resolves to `null` when the feed item id isn't on disk so callers
+ * can surface a clear "not found" to the user.
+ */
+export async function editNotification(
+  params: EditNotificationParams,
+): Promise<EditNotificationResult | null> {
+  const feedItemId = normalizeFeedItemId(params.id);
+
+  const feedItem = await patchFeedItemContent(feedItemId, {
+    title: params.title,
+    summary: params.body,
+    urgency: params.urgency,
+    status: params.status,
+  });
+  if (!feedItem) {
+    log.warn({ feedItemId }, "Edit requested for unknown feed item");
+    return null;
+  }
+
+  // Only edit channel messages when the user-visible text changed.
+  // Urgency/status are feed-only — pushing a channel update for those
+  // alone would re-deliver the same body and confuse the recipient.
+  const shouldUpdateChannels =
+    params.title !== undefined || params.body !== undefined;
+  if (!shouldUpdateChannels) {
+    return { feedItem, channels: [] };
+  }
+
+  const signalId = feedItemIdToSignalId(feedItemId);
+  const decision = findLatestDecisionByEventId(signalId);
+  if (!decision) {
+    log.info(
+      { feedItemId, signalId },
+      "Feed item has no persisted decision — skipping channel updates",
+    );
+    return { feedItem, channels: [] };
+  }
+
+  const deliveries = findDeliveriesByDecisionId(decision.id);
+  const channels = await updateChannelDeliveries(deliveries, {
+    title: params.title,
+    body: params.body,
+  });
+
+  return { feedItem, channels };
+}
+
+async function updateChannelDeliveries(
+  deliveries: NotificationDeliveryRow[],
+  patch: { title?: string; body?: string },
+): Promise<ChannelEditResult[]> {
+  const broadcaster = getBroadcaster();
+  const results: ChannelEditResult[] = [];
+
+  for (const delivery of deliveries) {
+    const channel = delivery.channel as NotificationChannel;
+    if (delivery.status !== "sent") {
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "skipped",
+        reason: `delivery status is ${delivery.status}`,
+      });
+      continue;
+    }
+
+    const adapter = broadcaster.getAdapter(channel);
+    if (!adapter?.update) {
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "unsupported",
+        reason: `${channel} adapter does not support in-place edits`,
+      });
+      continue;
+    }
+
+    try {
+      const result = await adapter.update(
+        {
+          deliveryId: delivery.id,
+          destination: delivery.destination,
+          messageId: delivery.messageId,
+        },
+        patch,
+      );
+      if (!result.success) {
+        results.push({
+          channel,
+          deliveryId: delivery.id,
+          outcome: "failed",
+          reason: result.error ?? "unknown error",
+        });
+        continue;
+      }
+      updateDeliveryRenderedCopy(delivery.id, {
+        renderedTitle: patch.title,
+        renderedBody: patch.body,
+      });
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "updated",
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, channel, deliveryId: delivery.id },
+        "Channel adapter update threw",
+      );
+      results.push({
+        channel,
+        deliveryId: delivery.id,
+        outcome: "failed",
+        reason: message,
+      });
+    }
+  }
+
+  return results;
+}