@vellumai/assistant 0.8.2 → 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 /
@@ -668,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,
@@ -791,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(
@@ -799,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,
@@ -829,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

@@ -88,6 +88,7 @@ function getBroadcaster(): NotificationBroadcaster {
           targetGuardianPrincipalId: info.targetGuardianPrincipalId,
           groupId: info.groupId,
           source: info.source,
+          silent: info.silent,
         });
         log.info(
           {

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

@@ -25,6 +25,7 @@ import type { NotificationSignal } from "./signal.js";
 import type {
   NotificationDecision,
   NotificationDeliveryResult,
+  RenderedChannelCopy,
 } from "./types.js";
 
 const log = getLogger("home-feed-side-effect");
@@ -51,9 +52,30 @@ export async function writeHomeFeedItemForSignal(
 ): Promise<FeedItem | null> {
   if (!shouldMirrorToHomeFeed(signal)) return null;
 
-  const renderedCopy = decision.renderedCopy.vellum;
-  const payloadTitle = readPayloadString(signal.contextPayload, "title");
-  const payloadBody = readPayloadString(signal.contextPayload, "body");
+  const renderedCopy =
+    decision.renderedCopy.vellum ??
+    firstSelectedRenderedCopy(decision.renderedCopy, decision.selectedChannels);
+  const payloadTitle =
+    readPayloadString(signal.contextPayload, "title") ??
+    readPayloadString(signal.contextPayload, "requestedTitle");
+  const payloadBody =
+    readPayloadString(signal.contextPayload, "body") ??
+    readPayloadString(signal.contextPayload, "requestedMessage");
+
+  // Source the title from the payload only. The LLM's `renderedCopy.title`
+  // often echoes the body when no explicit title was passed, which stutters
+  // against `summary` in the row. Leave undefined when absent; renderers
+  // fall back to `summary`.
+  const resolvedTitle = payloadTitle?.trim() || undefined;
+  const resolvedSummary =
+    renderedCopy?.body?.trim() || payloadBody?.trim() || "";
+  if (!resolvedSummary) {
+    log.warn(
+      { signalId: signal.signalId, sourceEventName: signal.sourceEventName },
+      "Home-feed write skipped: no summary available (would have fallen back to event name)",
+    );
+    return null;
+  }
 
   const conversationId = deliveryResults.find(
     (r) => r.channel === "vellum",
@@ -76,12 +98,14 @@ export async function writeHomeFeedItemForSignal(
     id: `notif:${signal.signalId}`,
     type: "notification",
     priority: 50,
-    title: renderedCopy?.title ?? payloadTitle ?? signal.sourceEventName,
-    summary: renderedCopy?.body ?? payloadBody ?? signal.sourceEventName,
+    ...(resolvedTitle ? { title: resolvedTitle } : {}),
+    summary: resolvedSummary,
     timestamp: now,
     createdAt: now,
     status: "new",
     category,
+    noteworthy: deriveNoteworthy(signal),
+    fromAssistant: signal.sourceChannel === "assistant_tool",
     ...(urgency ? { urgency } : {}),
     ...(conversationId ? { conversationId } : {}),
     ...(panelKind ? { detailPanel: { kind: panelKind } } : {}),
@@ -108,7 +132,6 @@ const EVENT_CATEGORY_MAP: Record<string, FeedItemCategory> = {
   "credential.health_alert": "security",
   "activity.failed": "background",
   "activity.complete": "background",
-  "heartbeat.alert": "system",
   "watcher.notification": "system",
   "schedule.notify": "scheduling",
   "guardian.question": "security",
@@ -146,8 +169,17 @@ function deriveDetailPanelKind(
  * `sourceContextId` is best-effort — it may not be a conversation id
  * (e.g. scheduler job id, watcher event id), so a lookup failure
  * falls through to "not a background conversation" rather than throwing.
+ *
+ * `assistant_tool` is the source channel used by the `notifications send`
+ * skill (and by background-job failure emits). These signals represent
+ * the assistant actively choosing to share, so we mirror them into the
+ * home feed without requiring a background-typed conversation or the
+ * `isAsyncBackground` hint — the documented (SKILL.md) CLI surface
+ * intentionally does not expose either; internal call sites that still set
+ * the hint keep working unchanged.
  */
 function shouldMirrorToHomeFeed(signal: NotificationSignal): boolean {
+  if (signal.sourceChannel === "assistant_tool") return true;
   if (signal.attentionHints.isAsyncBackground) return true;
   if (!signal.sourceContextId) return false;
   try {
@@ -163,3 +195,50 @@ function readPayloadString(payload: unknown, key: string): string | undefined {
   const value = (payload as Record<string, unknown>)[key];
   return typeof value === "string" ? value : undefined;
 }
+
+/**
+ * Routing-intent enforcement can prune `selectedChannels` without also
+ * pruning `renderedCopy`, so iterating `renderedCopy` directly risks
+ * surfacing copy for a channel that was never delivered. Walk
+ * `selectedChannels` in order instead so the channel that actually shipped
+ * wins.
+ */
+function firstSelectedRenderedCopy(
+  renderedCopy: NotificationDecision["renderedCopy"],
+  selectedChannels: NotificationDecision["selectedChannels"],
+): RenderedChannelCopy | undefined {
+  for (const channel of selectedChannels) {
+    const copy = renderedCopy[channel];
+    if (copy && (copy.title?.trim() || copy.body?.trim())) return copy;
+  }
+  return undefined;
+}
+
+// ── Noteworthy derivation ─────────────────────────────────────────────
+//
+// Clients split the feed into inbox-style (noteworthy) and activity-style
+// (routine) surfaces. Assistant-initiated shares and a small allow-list of
+// high-importance system events land in the inbox; routine background
+// signals stay in activity.
+
+const NOTEWORTHY_EVENT_NAMES: ReadonlySet<string> = new Set([
+  "guardian.question",
+  "guardian.channel_activation",
+  "ingress.access_request",
+  "ingress.escalation",
+  "credential.health_alert",
+]);
+
+function deriveNoteworthy(signal: NotificationSignal): boolean {
+  // Background-job failures emit with `sourceChannel: "assistant_tool"`
+  // (see `runtime/background-job-runner.ts`), so the activity.failed rule
+  // must run BEFORE the assistant_tool short-circuit — otherwise every
+  // routine watcher/heartbeat failure would land in the Inbox instead of
+  // staying in the activity feed.
+  if (signal.sourceEventName === "activity.failed") {
+    return signal.attentionHints.urgency === "critical";
+  }
+  if (signal.sourceChannel === "assistant_tool") return true;
+  if (NOTEWORTHY_EVENT_NAMES.has(signal.sourceEventName)) return true;
+  return false;
+}

package/src/notifications/signal.ts

@@ -107,10 +107,6 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     description:
       "OAuth credential health issue detected (expired, revoked, missing scopes)",
   },
-  {
-    id: "heartbeat.alert",
-    description: "Heartbeat found something worth surfacing to the guardian",
-  },
 ] as const;
 
 export type NotificationSourceEventName =

package/src/notifications/types.ts

@@ -7,6 +7,7 @@
 
 import type { ChannelPolicies } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
+import type { AttentionHints } from "./signal.js";
 
 /**
  * Derived from the channel policy registry: only channels whose
@@ -81,6 +82,13 @@ export interface ChannelDeliveryPayload {
   deepLinkTarget?: Record<string, unknown>;
   /** Original signal context payload — available for channel-specific structured rendering. */
   contextPayload?: Record<string, unknown>;
+  /**
+   * Forwarded from the originating signal so adapters can make
+   * urgency-aware decisions (e.g. the vellum adapter suppresses the OS
+   * banner for non-urgent intents while still emitting the conversation
+   * pairing side effects).
+   */
+  urgency: AttentionHints["urgency"];
 }
 
 /** Interface that each channel adapter must implement. */

package/src/oauth/platform-connection.test.ts

@@ -261,17 +261,57 @@ describe("PlatformOAuthConnection", () => {
     ).rejects.toThrow(CredentialRequiredError);
   });
 
-  test("502 response throws ProviderUnreachableError", async () => {
+  test("502 response retries then throws ProviderUnreachableError", async () => {
+    let callCount = 0;
+    const client = makeMockClient(
+      mock(async () => {
+        callCount++;
+        return new Response("", { status: 502 });
+      }) as unknown as typeof globalThis.fetch,
+    );
+
+    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    await expect(
+      conn.request({ method: "GET", path: "/test" }),
+    ).rejects.toThrow(ProviderUnreachableError);
+    // 1 initial + 3 retries = 4 total attempts
+    expect(callCount).toBe(4);
+  });
+
+  test("502 response includes detail from response body", async () => {
     const client = makeMockClient(
       mock(
-        async () => new Response("", { status: 502 }),
+        async () => new Response("upstream timeout after 30s", { status: 502 }),
       ) as unknown as typeof globalThis.fetch,
     );
 
     const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
     await expect(
       conn.request({ method: "GET", path: "/test" }),
-    ).rejects.toThrow(ProviderUnreachableError);
+    ).rejects.toThrow(/upstream timeout after 30s/);
+  });
+
+  test("502 recovers on retry", async () => {
+    let callCount = 0;
+    const client = makeMockClient(
+      mock(async () => {
+        callCount++;
+        if (callCount <= 2) {
+          return new Response("", { status: 502 });
+        }
+        return new Response(
+          JSON.stringify({ status: 200, headers: {}, body: { ok: true } }),
+          { status: 200 },
+        );
+      }) as unknown as typeof globalThis.fetch,
+    );
+
+    const conn = new PlatformOAuthConnection({ ...DEFAULT_OPTIONS, client });
+    const result = await conn.request({ method: "GET", path: "/test" });
+
+    expect(result.status).toBe(200);
+    expect(result.body).toEqual({ ok: true });
+    expect(callCount).toBe(3);
   });
 
   test("withToken throws clear error", async () => {