@vellumai/assistant 0.3.15 → 0.3.16

package/src/notifications/conversation-pairing.ts

@@ -34,11 +34,11 @@ export interface PairingResult {
  * Errors are caught and logged — this function never throws so the
  * notification pipeline is not disrupted by pairing failures.
  */
-export function pairDeliveryWithConversation(
+export async function pairDeliveryWithConversation(
   signal: NotificationSignal,
   channel: NotificationChannel,
   copy: RenderedChannelCopy,
-): PairingResult {
+): Promise<PairingResult> {
   try {
     const strategy = getConversationStrategy(channel as ChannelId);
 
@@ -78,7 +78,7 @@ export function pairDeliveryWithConversation(
       : composeThreadSeed(signal, channel, copy);
     // Skip memory indexing — notification audit messages are not conversational
     // memory and should not pollute recall or incur embedding/extraction overhead.
-    const message = addMessage(conversation.id, 'assistant', messageContent, undefined, { skipIndexing: true });
+    const message = await addMessage(conversation.id, 'assistant', messageContent, undefined, { skipIndexing: true });
 
     log.info(
       {

package/src/notifications/decision-engine.ts

@@ -19,18 +19,20 @@ import { getLogger } from '../util/logger.js';
 import { createDecision } from './decisions-store.js';
 import { getPreferenceSummary } from './preference-summary.js';
 import type { NotificationSignal, RoutingIntent } from './signal.js';
-import type { NotificationChannel, NotificationDecision, RenderedChannelCopy } from './types.js';
+import { type ThreadCandidateSet, buildThreadCandidates, serializeCandidatesForPrompt } from './thread-candidates.js';
+import type { NotificationChannel, NotificationDecision, RenderedChannelCopy, ThreadAction } from './types.js';
 
 const log = getLogger('notification-decision-engine');
 
 const DECISION_TIMEOUT_MS = 15_000;
-const PROMPT_VERSION = 'v3';
+const PROMPT_VERSION = 'v4';
 
 // ── System prompt ──────────────────────────────────────────────────────
 
 function buildSystemPrompt(
   availableChannels: NotificationChannel[],
   preferenceContext?: string,
+  candidateContext?: string,
 ): string {
   const sections: string[] = [
     `You are a notification routing engine. Given a signal describing an event, decide whether the user should be notified, on which channel(s), and compose the notification copy.`,
@@ -73,6 +75,26 @@ function buildSystemPrompt(
     `- \`threadSeedMessage\` is the opening message in the internal notification thread — it can be richer and more contextual.`,
     `  - For vellum (desktop): 2-4 short sentences with useful context and clear next step if action is required.`,
     `  - Never dump raw JSON. Include only human-readable context.`,
+    ``,
+    `Thread reuse guidelines:`,
+    `- For each selected channel, decide whether to start a new conversation thread or reuse an existing one.`,
+    `- Set \`threadActions\` keyed by channel name with \`action\` = "start_new" or "reuse_existing" (with \`conversationId\` from the candidates).`,
+    `- Prefer \`reuse_existing\` when the signal is clearly a continuation or update of an existing notification thread (same event type, related context).`,
+    `- Prefer \`start_new\` when the signal is a distinct event that deserves its own thread.`,
+    `- You may ONLY reuse a conversationId that appears in the provided candidate list. Any other ID will be rejected and downgraded to start_new.`,
+    `- When no candidates are available for a channel, always use start_new.`,
+  );
+
+  if (candidateContext) {
+    sections.push(
+      ``,
+      `<thread-candidates>`,
+      candidateContext,
+      `</thread-candidates>`,
+    );
+  }
+
+  sections.push(
     ``,
     `You MUST respond using the \`record_notification_decision\` tool. Do not respond with text.`,
   );
@@ -158,6 +180,30 @@ function buildDecisionTool(availableChannels: NotificationChannel[]) {
             ]),
           ),
         },
+        threadActions: {
+          type: 'object',
+          description: 'Per-channel thread action: start a new thread or reuse an existing candidate. Keyed by channel name.',
+          properties: Object.fromEntries(
+            availableChannels.map((ch) => [
+              ch,
+              {
+                type: 'object',
+                properties: {
+                  action: {
+                    type: 'string',
+                    enum: ['start_new', 'reuse_existing'],
+                    description: 'Whether to start a new thread or reuse an existing one.',
+                  },
+                  conversationId: {
+                    type: 'string',
+                    description: 'Required when action is reuse_existing. Must be a conversationId from the provided thread candidates.',
+                  },
+                },
+                required: ['action'],
+              },
+            ]),
+          ),
+        },
         deepLinkTarget: {
           type: 'object',
           description: 'Optional deep link metadata for navigating to the source context',
@@ -237,6 +283,7 @@ const VALID_CHANNELS = new Set<string>(getDeliverableChannels());
 function validateDecisionOutput(
   input: Record<string, unknown>,
   availableChannels: NotificationChannel[],
+  candidateSet?: ThreadCandidateSet,
 ): NotificationDecision | null {
   if (typeof input.shouldNotify !== 'boolean') return null;
   if (typeof input.reasoningSummary !== 'string') return null;
@@ -277,6 +324,9 @@ function validateDecisionOutput(
     }
   }
 
+  // Validate threadActions — strictly against the provided candidate set
+  const threadActions = validateThreadActions(input.threadActions, validChannels, candidateSet);
+
   const deepLinkTarget = input.deepLinkTarget && typeof input.deepLinkTarget === 'object'
     ? input.deepLinkTarget as Record<string, unknown>
     : undefined;
@@ -286,6 +336,7 @@ function validateDecisionOutput(
     selectedChannels: validChannels,
     reasoningSummary: input.reasoningSummary,
     renderedCopy,
+    threadActions: Object.keys(threadActions).length > 0 ? threadActions : undefined,
     deepLinkTarget,
     dedupeKey: input.dedupeKey,
     confidence,
@@ -293,6 +344,74 @@ function validateDecisionOutput(
   };
 }
 
+// ── Thread action validation ───────────────────────────────────────────
+
+/**
+ * Validate and sanitize thread actions from LLM output.
+ *
+ * - reuse_existing targets are checked against the candidate set; invalid
+ *   targets are downgraded to start_new with a warning.
+ * - Channels not in the selected set are ignored.
+ * - Missing actions for selected channels default to start_new (handled
+ *   downstream, not materialized here to keep the output compact).
+ */
+export function validateThreadActions(
+  raw: unknown,
+  validChannels: NotificationChannel[],
+  candidateSet?: ThreadCandidateSet,
+): Partial<Record<NotificationChannel, ThreadAction>> {
+  const result: Partial<Record<NotificationChannel, ThreadAction>> = {};
+
+  if (!raw || typeof raw !== 'object') return result;
+
+  const actionsObj = raw as Record<string, unknown>;
+  const channelSet = new Set(validChannels);
+
+  // Build a lookup of valid candidate conversationIds per channel
+  const validCandidateIds = new Map<NotificationChannel, Set<string>>();
+  if (candidateSet) {
+    for (const [ch, candidates] of Object.entries(candidateSet) as [NotificationChannel, { conversationId: string }[]][]) {
+      validCandidateIds.set(ch, new Set(candidates.map((c) => c.conversationId)));
+    }
+  }
+
+  for (const [ch, actionRaw] of Object.entries(actionsObj)) {
+    if (!channelSet.has(ch as NotificationChannel)) continue;
+    if (!actionRaw || typeof actionRaw !== 'object') continue;
+
+    const channel = ch as NotificationChannel;
+    const action = actionRaw as Record<string, unknown>;
+
+    if (action.action === 'start_new') {
+      result[channel] = { action: 'start_new' };
+    } else if (action.action === 'reuse_existing') {
+      const conversationId = action.conversationId;
+      if (typeof conversationId !== 'string' || !conversationId.trim()) {
+        log.warn({ channel }, 'LLM returned reuse_existing without conversationId — downgrading to start_new');
+        result[channel] = { action: 'start_new' };
+        continue;
+      }
+
+      // Strict validation: the conversationId must exist in the candidate set
+      const candidateIds = validCandidateIds.get(channel);
+      if (!candidateIds || !candidateIds.has(conversationId)) {
+        log.warn(
+          { channel, conversationId },
+          'LLM returned reuse_existing with conversationId not in candidate set — downgrading to start_new',
+        );
+        result[channel] = { action: 'start_new' };
+        continue;
+      }
+
+      result[channel] = { action: 'reuse_existing', conversationId };
+    }
+    // Unknown action values are silently ignored — the channel will default
+    // to start_new downstream.
+  }
+
+  return result;
+}
+
 // ── Core evaluation function ───────────────────────────────────────────
 
 export async function evaluateSignal(
@@ -317,6 +436,16 @@ export async function evaluateSignal(
     }
   }
 
+  // Build thread candidate set for reuse decisions. Wrapped in try/catch
+  // so candidate lookup failures do not block the decision path.
+  let candidateSet: ThreadCandidateSet | undefined;
+  try {
+    candidateSet = buildThreadCandidates(availableChannels, signal.assistantId);
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log.warn({ err: errMsg }, 'Failed to build thread candidates, proceeding without candidates');
+  }
+
   const provider = getConfiguredProvider();
   if (!provider) {
     log.warn('Configured provider unavailable for notification decision, using fallback');
@@ -327,7 +456,7 @@ export async function evaluateSignal(
 
   let decision: NotificationDecision;
   try {
-    decision = await classifyWithLLM(signal, availableChannels, resolvedPreferenceContext, decisionModelIntent);
+    decision = await classifyWithLLM(signal, availableChannels, resolvedPreferenceContext, decisionModelIntent, candidateSet);
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err);
     log.warn({ err: errMsg }, 'Notification decision LLM call failed, using fallback');
@@ -346,11 +475,13 @@ async function classifyWithLLM(
   availableChannels: NotificationChannel[],
   preferenceContext: string | undefined,
   modelIntent: ModelIntent,
+  candidateSet?: ThreadCandidateSet,
 ): Promise<NotificationDecision> {
   const provider = getConfiguredProvider()!;
   const { signal: abortSignal, cleanup } = createTimeout(DECISION_TIMEOUT_MS);
 
-  const systemPrompt = buildSystemPrompt(availableChannels, preferenceContext);
+  const candidateContext = candidateSet ? serializeCandidatesForPrompt(candidateSet) ?? undefined : undefined;
+  const systemPrompt = buildSystemPrompt(availableChannels, preferenceContext, candidateContext);
   const prompt = buildUserPrompt(signal);
   const tool = buildDecisionTool(availableChannels);
 
@@ -379,6 +510,7 @@ async function classifyWithLLM(
     const validated = validateDecisionOutput(
       toolBlock.input as Record<string, unknown>,
       availableChannels,
+      candidateSet,
     );
     if (!validated) {
       log.warn('Invalid notification decision output from LLM, using fallback');
@@ -432,12 +564,31 @@ export function enforceRoutingIntent(
   if (routingIntent === 'multi_channel') {
     // Ensure at least 2 channels when 2+ are connected
     if (connectedChannels.length >= 2 && decision.selectedChannels.length < 2) {
+      const connectedSet = new Set<NotificationChannel>(connectedChannels);
+      const selectedConnected = decision.selectedChannels.filter((ch) => connectedSet.has(ch));
+      const expanded: NotificationChannel[] = [];
+      const seen = new Set<NotificationChannel>();
+
+      // Preserve the decision's selected channels first, then add connected
+      // channels until we reach two channels total.
+      for (const ch of selectedConnected) {
+        if (seen.has(ch)) continue;
+        expanded.push(ch);
+        seen.add(ch);
+      }
+      for (const ch of connectedChannels) {
+        if (seen.has(ch)) continue;
+        expanded.push(ch);
+        seen.add(ch);
+        if (expanded.length >= 2) break;
+      }
+
       const enforced = { ...decision };
-      enforced.selectedChannels = [...connectedChannels];
-      enforced.reasoningSummary = `${decision.reasoningSummary} [routing_intent=multi_channel enforced: expanded to ${connectedChannels.join(', ')}]`;
+      enforced.selectedChannels = expanded;
+      enforced.reasoningSummary = `${decision.reasoningSummary} [routing_intent=multi_channel enforced: expanded to ${expanded.join(', ')}]`;
       log.info(
-        { routingIntent, connectedChannels, originalChannels: decision.selectedChannels },
-        'Routing intent enforcement: multi_channel → expanded to all connected channels',
+        { routingIntent, connectedChannels, originalChannels: decision.selectedChannels, enforcedChannels: expanded },
+        'Routing intent enforcement: multi_channel → expanded to at least two channels',
       );
       return enforced;
     }
@@ -451,6 +602,19 @@ export function enforceRoutingIntent(
 function persistDecision(signal: NotificationSignal, decision: NotificationDecision): string | undefined {
   try {
     const decisionId = uuid();
+
+    // Summarize thread actions for the audit trail
+    const threadActionSummary: Record<string, string> = {};
+    if (decision.threadActions) {
+      for (const [ch, ta] of Object.entries(decision.threadActions)) {
+        if (ta.action === 'reuse_existing') {
+          threadActionSummary[ch] = `reuse:${ta.conversationId}`;
+        } else {
+          threadActionSummary[ch] = 'start_new';
+        }
+      }
+    }
+
     createDecision({
       id: decisionId,
       notificationEventId: signal.signalId,
@@ -464,6 +628,7 @@ function persistDecision(signal: NotificationSignal, decision: NotificationDecis
         dedupeKey: decision.dedupeKey,
         channelCount: decision.selectedChannels.length,
         hasCopy: Object.keys(decision.renderedCopy).length > 0,
+        ...(Object.keys(threadActionSummary).length > 0 ? { threadActions: threadActionSummary } : {}),
       },
     });
     return decisionId;

package/src/notifications/deliveries-store.ts

@@ -6,9 +6,9 @@
  * (decision, channel, destination) are tracked via the `attempt` counter.
  */
 
-import { eq } from 'drizzle-orm';
+import { and, eq } from 'drizzle-orm';
 
-import { getDb } from '../memory/db.js';
+import { getDb, rawChanges } from '../memory/db.js';
 import { notificationDeliveries } from '../memory/schema.js';
 import type { NotificationChannel, NotificationDeliveryStatus } from './types.js';
 
@@ -131,13 +131,13 @@ export function updateDeliveryStatus(
     updates.errorMessage = error.message;
   }
 
-  const result = db
+  db
     .update(notificationDeliveries)
     .set(updates)
     .where(eq(notificationDeliveries.id, id))
-    .run() as unknown as { changes?: number };
+    .run();
 
-  return (result.changes ?? 0) > 0;
+  return rawChanges() > 0;
 }
 
 /**
@@ -171,13 +171,13 @@ export function updateDeliveryClientOutcome(
     updates.clientDeliveryError = error.code;
   }
 
-  const result = db
+  db
     .update(notificationDeliveries)
     .set(updates)
     .where(eq(notificationDeliveries.id, deliveryId))
-    .run() as unknown as { changes?: number };
+    .run();
 
-  return (result.changes ?? 0) > 0;
+  return rawChanges() > 0;
 }
 
 /** List all delivery records for a given notification decision. */
@@ -190,3 +190,22 @@ export function listDeliveries(decisionId: string): NotificationDeliveryRow[] {
     .all();
   return rows.map(rowToDelivery);
 }
+
+/** Check whether a delivery already exists for a given decision+channel pair. */
+export function findDeliveryByDecisionAndChannel(
+  decisionId: string,
+  channel: NotificationChannel,
+): NotificationDeliveryRow | undefined {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(notificationDeliveries)
+    .where(
+      and(
+        eq(notificationDeliveries.notificationDecisionId, decisionId),
+        eq(notificationDeliveries.channel, channel),
+      ),
+    )
+    .get();
+  return row ? rowToDelivery(row) : undefined;
+}

package/src/notifications/preferences-store.ts

@@ -10,7 +10,7 @@
 import { desc, eq } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 
-import { getDb } from '../memory/db.js';
+import { getDb, rawChanges } from '../memory/db.js';
 import { notificationPreferences } from '../memory/schema.js';
 
 // ── Row type ────────────────────────────────────────────────────────────
@@ -107,13 +107,13 @@ export function updatePreference(id: string, params: UpdatePreferenceParams): bo
   if (params.appliesWhen !== undefined) updates.appliesWhenJson = JSON.stringify(params.appliesWhen);
   if (params.priority !== undefined) updates.priority = params.priority;
 
-  const result = db
+  db
     .update(notificationPreferences)
     .set(updates)
     .where(eq(notificationPreferences.id, id))
-    .run() as unknown as { changes?: number };
+    .run();
 
-  return (result.changes ?? 0) > 0;
+  return rawChanges() > 0;
 }
 
 // ── Delete ──────────────────────────────────────────────────────────────
@@ -121,12 +121,12 @@ export function updatePreference(id: string, params: UpdatePreferenceParams): bo
 export function deletePreference(id: string): boolean {
   const db = getDb();
 
-  const result = db
+  db
     .delete(notificationPreferences)
     .where(eq(notificationPreferences.id, id))
-    .run() as unknown as { changes?: number };
+    .run();
 
-  return (result.changes ?? 0) > 0;
+  return rawChanges() > 0;
 }
 
 // ── Get by ID ───────────────────────────────────────────────────────────

package/src/notifications/thread-candidates.ts

@@ -0,0 +1,234 @@
+/**
+ * Thread candidate builder for notification thread reuse.
+ *
+ * Builds a lightweight candidate set of recent notification conversations
+ * per channel that the decision engine can choose to reuse instead of
+ * starting a new thread. Includes guardian-specific context (pending
+ * unresolved request count) when available.
+ *
+ * The candidate set is intentionally compact — only the fields the LLM
+ * needs for a routing decision, not full conversation contents.
+ */
+
+import { and, desc, eq, isNotNull } from 'drizzle-orm';
+
+import { getDb } from '../memory/db.js';
+import { countPendingByConversation } from '../memory/guardian-approvals.js';
+import { conversations, notificationDeliveries, notificationDecisions, notificationEvents } from '../memory/schema.js';
+import { getLogger } from '../util/logger.js';
+import type { NotificationChannel } from './types.js';
+
+const log = getLogger('thread-candidates');
+
+/** Maximum number of candidate threads to surface per channel. */
+const MAX_CANDIDATES_PER_CHANNEL = 5;
+
+/** Only consider conversations updated within this window (ms). */
+const CANDIDATE_RECENCY_WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+// -- Public types -------------------------------------------------------------
+
+/** Guardian-specific context attached to a thread candidate when available. */
+export interface GuardianCandidateContext {
+  /** Number of unresolved (pending) guardian approval requests in this conversation. */
+  pendingUnresolvedRequestCount: number;
+}
+
+/** A single candidate conversation that the decision engine can select for reuse. */
+export interface ThreadCandidate {
+  conversationId: string;
+  title: string | null;
+  updatedAt: number;
+  /** The source event name from the most recent notification delivered to this conversation. */
+  latestSourceEventName: string | null;
+  channel: NotificationChannel;
+  /** Guardian-specific context, present only when there are relevant guardian records. */
+  guardianContext?: GuardianCandidateContext;
+}
+
+/** Candidate set for the decision engine, keyed by channel. */
+export type ThreadCandidateSet = Partial<Record<NotificationChannel, ThreadCandidate[]>>;
+
+// -- Core builder -------------------------------------------------------------
+
+/**
+ * Build the thread candidate set for all selected channels.
+ *
+ * Queries recent notification-sourced conversations that were delivered
+ * to each channel and enriches them with guardian-specific metadata
+ * when available.
+ *
+ * Errors are caught per-channel so a failure in one channel does not
+ * block candidates for others.
+ */
+export function buildThreadCandidates(
+  channels: NotificationChannel[],
+  assistantId: string,
+): ThreadCandidateSet {
+  const result: ThreadCandidateSet = {};
+  const cutoff = Date.now() - CANDIDATE_RECENCY_WINDOW_MS;
+
+  for (const channel of channels) {
+    try {
+      const candidates = buildCandidatesForChannel(channel, assistantId, cutoff);
+      if (candidates.length > 0) {
+        result[channel] = candidates;
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log.warn({ err: errMsg, channel }, 'Failed to build thread candidates for channel');
+    }
+  }
+
+  return result;
+}
+
+// -- Per-channel query --------------------------------------------------------
+
+/**
+ * Query recent notification conversations for a given channel.
+ *
+ * Joins notification_deliveries -> notification_decisions -> notification_events
+ * to find conversations that were created by the notification pipeline for
+ * this channel, then enriches with guardian context.
+ */
+function buildCandidatesForChannel(
+  channel: NotificationChannel,
+  assistantId: string,
+  cutoffMs: number,
+): ThreadCandidate[] {
+  const db = getDb();
+
+  // Find recent notification deliveries for this channel that have a
+  // conversationId and were successfully sent.
+  const rows = db
+    .select({
+      conversationId: notificationDeliveries.conversationId,
+      channel: notificationDeliveries.channel,
+      deliverySentAt: notificationDeliveries.sentAt,
+      sourceEventName: notificationEvents.sourceEventName,
+      convTitle: conversations.title,
+      convUpdatedAt: conversations.updatedAt,
+    })
+    .from(notificationDeliveries)
+    .innerJoin(
+      notificationDecisions,
+      eq(notificationDeliveries.notificationDecisionId, notificationDecisions.id),
+    )
+    .innerJoin(
+      notificationEvents,
+      eq(notificationDecisions.notificationEventId, notificationEvents.id),
+    )
+    .innerJoin(
+      conversations,
+      eq(notificationDeliveries.conversationId, conversations.id),
+    )
+    .where(
+      and(
+        eq(notificationDeliveries.channel, channel),
+        eq(notificationDeliveries.assistantId, assistantId),
+        eq(notificationDeliveries.status, 'sent'),
+        isNotNull(notificationDeliveries.conversationId),
+      ),
+    )
+    .orderBy(desc(notificationDeliveries.sentAt))
+    .limit(MAX_CANDIDATES_PER_CHANNEL * 3) // over-fetch to allow deduplication
+    .all();
+
+  // Deduplicate by conversationId (keep the most recent delivery per conversation)
+  const seen = new Set<string>();
+  const candidates: ThreadCandidate[] = [];
+
+  for (const row of rows) {
+    if (!row.conversationId) continue;
+    if (seen.has(row.conversationId)) continue;
+
+    // Apply recency filter on the conversation's updatedAt
+    if (row.convUpdatedAt < cutoffMs) continue;
+
+    seen.add(row.conversationId);
+
+    const candidate: ThreadCandidate = {
+      conversationId: row.conversationId,
+      title: row.convTitle,
+      updatedAt: row.convUpdatedAt,
+      latestSourceEventName: row.sourceEventName ?? null,
+      channel: channel,
+    };
+
+    // Enrich with guardian context
+    const guardianContext = buildGuardianContext(row.conversationId, assistantId);
+    if (guardianContext) {
+      candidate.guardianContext = guardianContext;
+    }
+
+    candidates.push(candidate);
+
+    if (candidates.length >= MAX_CANDIDATES_PER_CHANNEL) break;
+  }
+
+  return candidates;
+}
+
+// -- Guardian context enrichment ----------------------------------------------
+
+/**
+ * Build guardian-specific context for a candidate conversation.
+ * Returns null when there is no guardian-relevant data.
+ */
+function buildGuardianContext(
+  conversationId: string,
+  assistantId: string,
+): GuardianCandidateContext | null {
+  try {
+    const pendingCount = countPendingByConversation(conversationId, assistantId);
+    if (pendingCount > 0) {
+      return { pendingUnresolvedRequestCount: pendingCount };
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    log.warn({ err: errMsg, conversationId }, 'Failed to query guardian context for candidate');
+  }
+
+  return null;
+}
+
+// -- Prompt serialization -----------------------------------------------------
+
+/**
+ * Serialize a thread candidate set into a compact text block suitable for
+ * injection into the decision engine's user prompt.
+ *
+ * Designed to be token-efficient while giving the LLM enough context
+ * to make a reuse decision.
+ */
+export function serializeCandidatesForPrompt(candidateSet: ThreadCandidateSet): string | null {
+  const channelEntries = Object.entries(candidateSet) as [NotificationChannel, ThreadCandidate[]][];
+  if (channelEntries.length === 0) return null;
+
+  const sections: string[] = [];
+
+  for (const [channel, candidates] of channelEntries) {
+    if (candidates.length === 0) continue;
+
+    const lines: string[] = [`Channel: ${channel}`];
+    for (const c of candidates) {
+      const parts: string[] = [
+        `  - id=${c.conversationId}`,
+        `title="${c.title ?? '(untitled)'}"`,
+        `updated=${new Date(c.updatedAt).toISOString()}`,
+      ];
+      if (c.latestSourceEventName) {
+        parts.push(`lastEvent="${c.latestSourceEventName}"`);
+      }
+      if (c.guardianContext) {
+        parts.push(`pendingRequests=${c.guardianContext.pendingUnresolvedRequestCount}`);
+      }
+      lines.push(parts.join(' '));
+    }
+    sections.push(lines.join('\n'));
+  }
+
+  if (sections.length === 0) return null;
+  return sections.join('\n\n');
+}

package/src/notifications/types.ts

@@ -79,12 +79,30 @@ export interface RenderedChannelCopy {
   threadSeedMessage?: string;
 }
 
+// -- Thread action types ------------------------------------------------------
+
+/** Start a new conversation thread for the notification delivery. */
+export interface ThreadActionStartNew {
+  action: 'start_new';
+}
+
+/** Reuse an existing conversation thread identified by conversationId. */
+export interface ThreadActionReuseExisting {
+  action: 'reuse_existing';
+  conversationId: string;
+}
+
+/** Per-channel thread action — either start a new thread or reuse an existing one. */
+export type ThreadAction = ThreadActionStartNew | ThreadActionReuseExisting;
+
 /** Output produced by the notification decision engine for a given signal. */
 export interface NotificationDecision {
   shouldNotify: boolean;
   selectedChannels: NotificationChannel[];
   reasoningSummary: string;
   renderedCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>>;
+  /** Per-channel thread action. When absent for a channel, defaults to start_new. */
+  threadActions?: Partial<Record<NotificationChannel, ThreadAction>>;
   deepLinkTarget?: Record<string, unknown>;
   dedupeKey: string;
   confidence: number;