@vellumai/assistant 0.8.1 → 0.8.3

package/src/notifications/copy-composer.ts

@@ -32,51 +32,6 @@ export function nonEmpty(value: string | undefined): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
-export function looksLikeIntermediaryInstruction(text: string): boolean {
-  const normalized = text.replace(/\s+/g, " ").trim();
-  const intermediaryAction =
-    "(?:tell|telling|ask|asking|remind|reminding|nudge|nudging|prompt|prompting|notify|notifying|encourage|encouraging|prime|priming|brief|briefing|coach|coaching)";
-  const target = "(?:the\\s+)?(?:guardian|recipient|user)";
-  return (
-    /\b(?:assistant|agent|system|model|watcher)\s+(?:should|needs?\s+to|must|can|could)\b/i.test(
-      normalized,
-    ) ||
-    new RegExp(
-      `\\b(?:consider|try|please)\\s+${intermediaryAction}\\s+${target}\\b`,
-      "i",
-    ).test(normalized) ||
-    new RegExp(
-      `\\b${intermediaryAction}\\s+${target}\\s+(?:to|that|about|with)\\b`,
-      "i",
-    ).test(normalized) ||
-    new RegExp(
-      `\\b${target}\\s+(?:should|needs?\\s+to|must|might\\s+want\\s+to)\\b`,
-      "i",
-    ).test(normalized) ||
-    new RegExp(`\\b(?:for|to)\\s+${target}\\s+to\\b`, "i").test(normalized)
-  );
-}
-
-function buildHeartbeatAlertCopy(
-  payload: Record<string, unknown>,
-): RenderedChannelCopy {
-  const summary = str(
-    payload.summary,
-    str(payload.body, "Your assistant found something worth your attention."),
-  ).trim();
-  const safePopupBody = looksLikeIntermediaryInstruction(summary)
-    ? "I found something worth your attention in a heartbeat check. Open the conversation for details."
-    : summary;
-
-  return {
-    title: str(payload.title, "Heartbeat Alert"),
-    body: safePopupBody,
-    deliveryText: safePopupBody,
-    conversationTitle: str(payload.conversationTitle, "Heartbeat"),
-    conversationSeedMessage: summary,
-  };
-}
-
 // ── Access-request copy contract ─────────────────────────────────────────────
 //
 // Deterministic helpers for building guardian-facing access-request copy.
@@ -550,8 +505,6 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
     body: str(payload.body, "A watcher event requires your attention"),
   }),
 
-  "heartbeat.alert": buildHeartbeatAlertCopy,
-
   "tool_confirmation.required_action": (payload) => ({
     title: "Tool Confirmation",
     body: str(payload.toolName, "A tool") + " requires your confirmation",
@@ -605,11 +558,11 @@ export function composeFallbackCopy(
 
   const baseCopy: RenderedChannelCopy = template
     ? template(signal.contextPayload)
-    : buildGenericCopy(signal);
+    : buildGenericCopy();
 
   const result: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {};
   for (const ch of channels) {
-    result[ch] = applyChannelDefaults(ch, baseCopy, signal);
+    result[ch] = applyChannelDefaults(ch, baseCopy);
   }
   return result;
 }
@@ -617,12 +570,11 @@ export function composeFallbackCopy(
 function applyChannelDefaults(
   channel: NotificationChannel,
   baseCopy: RenderedChannelCopy,
-  signal: NotificationSignal,
 ): RenderedChannelCopy {
   const copy: RenderedChannelCopy = { ...baseCopy };
 
   if (channel === "telegram") {
-    copy.deliveryText = buildChatSurfaceFallbackDeliveryText(baseCopy, signal);
+    copy.deliveryText = buildChatSurfaceFallbackDeliveryText(baseCopy);
   }
 
   return copy;
@@ -630,7 +582,6 @@ function applyChannelDefaults(
 
 function buildChatSurfaceFallbackDeliveryText(
   baseCopy: RenderedChannelCopy,
-  signal: NotificationSignal,
 ): string {
   const explicit = nonEmpty(baseCopy.deliveryText);
   if (explicit) return explicit;
@@ -641,23 +592,25 @@ function buildChatSurfaceFallbackDeliveryText(
   const title = nonEmpty(baseCopy.title);
   if (title) return title;
 
-  return signal.sourceEventName.replace(/[._]/g, " ");
+  // No usable text: return empty string. The broadcaster's empty-body skip in
+  // `broadcaster.ts` suppresses fallback-derived empty bodies; the
+  // deterministic `checkRenderedCopyQuality` (see deterministic-checks.ts)
+  // covers the same case when the empty body originates in
+  // `decision.renderedCopy`.
+  return "";
 }
 
 /**
- * Build generic copy when no template matches. Uses the signal's
- * sourceEventName and attention hints to produce something reasonable.
+ * Build generic copy when no template matches. Returns an empty body so the
+ * notification is suppressed rather than rendering an event-name placeholder.
+ * The broadcaster's empty-body skip in `broadcaster.ts` catches fallback-derived
+ * empty bodies; the deterministic `checkRenderedCopyQuality` (see
+ * deterministic-checks.ts) covers the same case when the empty body originates
+ * in `decision.renderedCopy`.
  */
-function buildGenericCopy(signal: NotificationSignal): RenderedChannelCopy {
-  const humanName = signal.sourceEventName.replace(/[._]/g, " ");
-  const urgencyPrefix =
-    signal.attentionHints.urgency === "high" ? "Urgent: " : "";
-  const actionSuffix = signal.attentionHints.requiresAction
-    ? " — action required"
-    : "";
-
+function buildGenericCopy(): RenderedChannelCopy {
   return {
     title: "Notification",
-    body: `${urgencyPrefix}${humanName}${actionSuffix}`,
+    body: "",
   };
 }

package/src/notifications/decision-engine.ts

@@ -35,7 +35,6 @@ import {
   composeFallbackCopy,
   hasAccessRequestInstructions,
   hasInviteFlowDirective,
-  looksLikeIntermediaryInstruction,
 } from "./copy-composer.js";
 import { createDecision } from "./decisions-store.js";
 import {
@@ -58,6 +57,21 @@ const log = getLogger("notification-decision-engine");
 const DECISION_TIMEOUT_MS = 15_000;
 const PROMPT_VERSION = "v4";
 
+/**
+ * Derive a short notification title from a message body. Used when an
+ * assistant_tool-sourced signal supplies `requestedMessage` without an
+ * explicit `requestedTitle`: trims to the first sentence terminator when
+ * present, then caps the result at 60 characters with an ellipsis.
+ */
+function deriveTitle(body: string): string {
+  const firstSentenceEnd = body.search(/[.!?](\s|$)/);
+  const candidate =
+    firstSentenceEnd > 0 ? body.slice(0, firstSentenceEnd + 1) : body;
+  return candidate.length > 60
+    ? candidate.slice(0, 60).trim() + "…"
+    : candidate.trim();
+}
+
 /**
  * Maximum character budget for identity context injected into the notification
  * decision prompt. We truncate to prevent oversized prompts when SOUL.md /
@@ -326,8 +340,9 @@ function buildFallbackDecision(
   signal: NotificationSignal,
   availableChannels: NotificationChannel[],
 ): NotificationDecision {
+  const urgency = signal.attentionHints.urgency;
   const isHighUrgencyAction =
-    signal.attentionHints.urgency === "high" &&
+    (urgency === "high" || urgency === "critical") &&
     signal.attentionHints.requiresAction;
 
   // Always include the vellum channel in the fallback — it's a local
@@ -667,47 +682,6 @@ function enforceAccessRequestInstructions(
   };
 }
 
-function enforceHeartbeatAlertCopy(
-  decision: NotificationDecision,
-  signal: NotificationSignal,
-): NotificationDecision {
-  if (signal.sourceEventName !== "heartbeat.alert") return decision;
-  if (!decision.shouldNotify || decision.selectedChannels.length === 0)
-    return decision;
-
-  const fallbackCopy = composeFallbackCopy(signal, decision.selectedChannels);
-  const nextCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {
-    ...decision.renderedCopy,
-  };
-
-  for (const channel of decision.selectedChannels) {
-    const currentCopy = nextCopy[channel];
-    if (
-      currentCopy &&
-      !heartbeatCopyLooksLikeIntermediaryInstruction(currentCopy)
-    ) {
-      continue;
-    }
-    const safeCopy = fallbackCopy[channel];
-    if (!safeCopy) continue;
-    nextCopy[channel] = safeCopy;
-  }
-
-  return {
-    ...decision,
-    renderedCopy: nextCopy,
-  };
-}
-
-function heartbeatCopyLooksLikeIntermediaryInstruction(
-  copy: RenderedChannelCopy,
-): boolean {
-  return [copy.title, copy.body, copy.deliveryText].some(
-    (value) =>
-      typeof value === "string" && looksLikeIntermediaryInstruction(value),
-  );
-}
-
 function ensureAccessRequestInstructionsInCopy(
   copy: RenderedChannelCopy,
   requestCode: string,
@@ -790,6 +764,102 @@ export async function evaluateSignal(
     );
   }
 
+  // Assistant-tool pass-through: when a producer hands us a verbatim
+  // message body via contextPayload.requestedMessage, skip the LLM
+  // classifier entirely. The producer has already done the routing and
+  // copy decisions — we just enforce the standard post-decision guards
+  // and persist the result.
+  if (
+    signal.sourceChannel === "assistant_tool" &&
+    typeof signal.contextPayload === "object" &&
+    signal.contextPayload != null &&
+    typeof (signal.contextPayload as Record<string, unknown>)
+      .requestedMessage === "string" &&
+    (
+      (signal.contextPayload as Record<string, unknown>)
+        .requestedMessage as string
+    ).trim().length > 0
+  ) {
+    const payload = signal.contextPayload as Record<string, unknown>;
+    const body = (payload.requestedMessage as string).trim();
+    const title =
+      typeof payload.requestedTitle === "string" &&
+      payload.requestedTitle.trim().length > 0
+        ? (payload.requestedTitle as string).trim()
+        : deriveTitle(body);
+    const isUrgent =
+      signal.attentionHints.urgency === "critical" ||
+      signal.attentionHints.urgency === "high";
+    const defaultChannels: NotificationChannel[] = isUrgent
+      ? [...availableChannels]
+      : availableChannels.includes("vellum")
+        ? ["vellum" as NotificationChannel]
+        : [];
+    // Honor `--preferred-channels` as ADDITIVE push targets on top of
+    // the default channel set. The notification center (vellum) is the
+    // always-on canonical inbox; preferred channels add push surfaces
+    // on top, they never replace vellum. Disconnected channels are
+    // filtered out so we never try to deliver on something unavailable.
+    const preferredChannelsRaw = Array.isArray(payload.preferredChannels)
+      ? (payload.preferredChannels as unknown[]).filter(
+          (c): c is string => typeof c === "string",
+        )
+      : undefined;
+    let selectedChannels = defaultChannels;
+    if (preferredChannelsRaw && preferredChannelsRaw.length > 0) {
+      const availableSet = new Set<string>(availableChannels);
+      const preferredAvailable = preferredChannelsRaw.filter((c) =>
+        availableSet.has(c),
+      ) as NotificationChannel[];
+      if (preferredAvailable.length > 0) {
+        selectedChannels = Array.from(
+          new Set<NotificationChannel>([
+            ...selectedChannels,
+            ...preferredAvailable,
+          ]),
+        );
+      }
+    }
+    // Thread `--deep-link-metadata` through when supplied as a plain object.
+    const deepLinkTarget =
+      payload.deepLinkMetadata != null &&
+      typeof payload.deepLinkMetadata === "object" &&
+      !Array.isArray(payload.deepLinkMetadata)
+        ? (payload.deepLinkMetadata as Record<string, unknown>)
+        : undefined;
+    // Populate renderedCopy and conversationActions for every available
+    // channel — not just `selectedChannels`. Downstream guards
+    // (routing-intent expansion in `enforceRoutingIntent`, urgency-forced
+    // vellum prepending in `emit-signal`) may widen `selectedChannels`
+    // beyond what we picked here. Pre-seeding copy for all channels ensures
+    // the verbatim message survives those expansions rather than falling
+    // back to an empty `composeFallbackCopy` body.
+    let decision: NotificationDecision = {
+      shouldNotify: selectedChannels.length > 0,
+      selectedChannels,
+      reasoningSummary: "assistant_tool pass-through",
+      renderedCopy: Object.fromEntries(
+        availableChannels.map((ch) => [ch, { title, body }]),
+      ) as NotificationDecision["renderedCopy"],
+      conversationActions: Object.fromEntries(
+        availableChannels.map((ch) => [ch, { action: "start_new" as const }]),
+      ) as NotificationDecision["conversationActions"],
+      dedupeKey: signal.signalId,
+      confidence: 1.0,
+      fallbackUsed: false,
+      ...(deepLinkTarget ? { deepLinkTarget } : {}),
+    };
+    decision = enforceGuardianRequestCode(decision, signal);
+    decision = enforceAccessRequestInstructions(decision, signal);
+    decision = enforceGuardianCallConversationAffinity(decision, signal);
+    decision = enforceConversationAffinity(
+      decision,
+      signal.conversationAffinityHint,
+    );
+    decision.persistedDecisionId = persistDecision(signal, decision);
+    return decision;
+  }
+
   const provider = await getConfiguredProvider("notificationDecision");
   if (!provider) {
     log.warn(
@@ -798,7 +868,6 @@ export async function evaluateSignal(
     let decision = buildFallbackDecision(signal, availableChannels);
     decision = enforceGuardianRequestCode(decision, signal);
     decision = enforceAccessRequestInstructions(decision, signal);
-    decision = enforceHeartbeatAlertCopy(decision, signal);
     decision = enforceGuardianCallConversationAffinity(decision, signal);
     decision = enforceConversationAffinity(
       decision,
@@ -828,7 +897,6 @@ export async function evaluateSignal(
 
   decision = enforceGuardianRequestCode(decision, signal);
   decision = enforceAccessRequestInstructions(decision, signal);
-  decision = enforceHeartbeatAlertCopy(decision, signal);
   decision = enforceGuardianCallConversationAffinity(decision, signal);
   decision = enforceConversationAffinity(
     decision,

package/src/notifications/deterministic-checks.ts

@@ -12,6 +12,7 @@ import { and, eq } from "drizzle-orm";
 import { getDb } from "../memory/db-connection.js";
 import { notificationEvents } from "../memory/schema.js";
 import { getLogger } from "../util/logger.js";
+import { composeFallbackCopy } from "./copy-composer.js";
 import type { NotificationSignal } from "./signal.js";
 import type { NotificationChannel, NotificationDecision } from "./types.js";
 
@@ -88,6 +89,16 @@ export async function runDeterministicChecks(
     return dedupeCheck;
   }
 
+  // Check 5: Rendered copy quality (fail-closed)
+  const copyCheck = checkRenderedCopyQuality(signal, decision);
+  if (!copyCheck.passed) {
+    log.info(
+      { signalId: signal.signalId, reason: copyCheck.reason },
+      "Deterministic check failed: rendered copy quality",
+    );
+    return copyCheck;
+  }
+
   return { passed: true };
 }
 
@@ -232,3 +243,88 @@ function checkDedupe(
 
   return { passed: true };
 }
+
+/**
+ * Fail-closed check that the rendered copy is real text and not an
+ * accidental fallback leak (empty body, or body that is just the raw
+ * source event name like "user.send_notification").
+ *
+ * Only validates channels that the decision engine actually emitted
+ * copy for. Channels appended after the decision (urgency-forced
+ * `vellum` prepend, `enforceRoutingIntent` expansion) have no entry
+ * in `renderedCopy` and are left for the broadcaster's
+ * `composeFallbackCopy` rescue at delivery time.
+ *
+ * If `renderedCopy` is empty for every selected channel, the
+ * broadcaster's fallback must produce a usable body — otherwise the
+ * signal would be silently dropped at delivery (broadcaster skips
+ * empty-body channels, `dispatchDecision` reports 0/N sent). In that
+ * case, require `composeFallbackCopy` to yield a non-empty body for
+ * at least one selected channel; otherwise fail-closed.
+ *
+ * The event-name-match branch is skipped for `assistant_tool`
+ * pass-through decisions because the producer supplied the body
+ * verbatim — a coincidental match with the event name is the user's
+ * intent, not a fallback leak.
+ */
+function checkRenderedCopyQuality(
+  signal: NotificationSignal,
+  decision: NotificationDecision,
+): CheckResult {
+  if (!decision.shouldNotify) {
+    return { passed: true };
+  }
+
+  const isAssistantToolPassthrough =
+    decision.reasoningSummary === "assistant_tool pass-through";
+  const normalizedEventName = signal.sourceEventName
+    .replace(/[._]/g, " ")
+    .toLowerCase()
+    .trim();
+  const rawEventName = signal.sourceEventName.toLowerCase();
+
+  let anyChannelHasCopy = false;
+  for (const channel of decision.selectedChannels) {
+    const copy = decision.renderedCopy[channel];
+    if (!copy) {
+      continue;
+    }
+    anyChannelHasCopy = true;
+    const trimmedBody = copy.body.trim();
+    if (trimmedBody.length === 0) {
+      return {
+        passed: false,
+        reason: "rendered copy body is empty",
+      };
+    }
+    if (isAssistantToolPassthrough) {
+      continue;
+    }
+    const normalizedBody = trimmedBody.toLowerCase();
+    if (
+      normalizedBody === normalizedEventName ||
+      normalizedBody === rawEventName
+    ) {
+      return {
+        passed: false,
+        reason: "rendered copy body is the source event name (fallback leak)",
+      };
+    }
+  }
+
+  if (!anyChannelHasCopy && decision.selectedChannels.length > 0) {
+    const fallback = composeFallbackCopy(signal, decision.selectedChannels);
+    const fallbackUsable = decision.selectedChannels.some(
+      (ch) => (fallback[ch]?.body ?? "").trim().length > 0,
+    );
+    if (!fallbackUsable) {
+      return {
+        passed: false,
+        reason:
+          "rendered copy missing for all selected channels and fallback body is empty (would silently drop)",
+      };
+    }
+  }
+
+  return { passed: true };
+}

package/src/notifications/emit-signal.ts

@@ -13,6 +13,7 @@ import { v4 as uuid } from "uuid";
 
 import { getDeliverableChannels } from "../channels/config.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
+import type { ConversationCreateType } from "../memory/conversation-crud.js";
 import { getLogger } from "../util/logger.js";
 import { type BroadcastFn, VellumAdapter } from "./adapters/macos.js";
 import { PlatformPushAdapter } from "./adapters/platform.js";
@@ -87,6 +88,7 @@ function getBroadcaster(): NotificationBroadcaster {
           targetGuardianPrincipalId: info.targetGuardianPrincipalId,
           groupId: info.groupId,
           source: info.source,
+          silent: info.silent,
         });
         log.info(
           {
@@ -204,6 +206,7 @@ export interface EmitSignalParams<TEventName extends string = string> {
     groupId?: string;
     scheduleJobId?: string;
     source?: string;
+    conversationType?: ConversationCreateType;
   };
 }
 
@@ -280,7 +283,24 @@ export async function emitNotificationSignal<TEventName extends string>(
 
     let decision = await evaluateSignal(signal, connectedChannels);
 
-    // Step 2.5: Enforce routing intent policy (fire-time guard)
+    // Step 2.5a: High/critical urgency signals always get a system
+    // notification via the vellum channel, regardless of what the
+    // decision engine selected. This ensures macOS surfaces a banner
+    // even when the app is focused.
+    const urgency = signal.attentionHints.urgency;
+    if (
+      (urgency === "high" || urgency === "critical") &&
+      decision.shouldNotify &&
+      !decision.selectedChannels.includes("vellum")
+    ) {
+      decision = {
+        ...decision,
+        selectedChannels: ["vellum", ...decision.selectedChannels],
+        reasoningSummary: `${decision.reasoningSummary} (vellum forced: ${urgency} urgency)`,
+      };
+    }
+
+    // Step 2.5b: Enforce routing intent policy (fire-time guard)
     const preEnforcementDecision = decision;
     decision = enforceRoutingIntent(
       decision,