@vellumai/assistant 0.4.55 → 0.4.57

package/src/notifications/decision-engine.ts

@@ -13,14 +13,20 @@ import { v4 as uuid } from "uuid";
 
 import { getDeliverableChannels } from "../channels/config.js";
 import { getConfig } from "../config/loader.js";
+import { buildCoreIdentityContext } from "../prompts/system-prompt.js";
 import {
   createTimeout,
   extractToolUse,
   getConfiguredProvider,
   userMessage,
 } from "../providers/provider-send-message.js";
-import type { ModelIntent } from "../providers/types.js";
+import type { ModelIntent, Provider } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
+import {
+  buildConversationCandidates,
+  type ConversationCandidateSet,
+  serializeCandidatesForPrompt,
+} from "./conversation-candidates.js";
 import {
   buildAccessRequestContractText,
   buildAccessRequestInviteDirective,
@@ -37,16 +43,11 @@ import {
 } from "./guardian-question-mode.js";
 import { getPreferenceSummary } from "./preference-summary.js";
 import type { NotificationSignal, RoutingIntent } from "./signal.js";
-import {
-  buildThreadCandidates,
-  serializeCandidatesForPrompt,
-  type ThreadCandidateSet,
-} from "./thread-candidates.js";
 import type {
+  ConversationAction,
   NotificationChannel,
   NotificationDecision,
   RenderedChannelCopy,
-  ThreadAction,
 } from "./types.js";
 
 const log = getLogger("notification-decision-engine");
@@ -60,6 +61,7 @@ function buildSystemPrompt(
   availableChannels: NotificationChannel[],
   preferenceContext?: string,
   candidateContext?: string,
+  identityContext?: 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.`,
@@ -76,6 +78,16 @@ function buildSystemPrompt(
     );
   }
 
+  if (identityContext) {
+    sections.push(
+      ``,
+      `<assistant-identity>`,
+      `The following describes the assistant's identity, personality, and the user's profile. Use this context to match the assistant's tone and style when composing notification copy. Do not include information from this context that is not relevant to the notification.`,
+      identityContext,
+      `</assistant-identity>`,
+    );
+  }
+
   sections.push(
     ``,
     `Guidelines:`,
@@ -94,20 +106,20 @@ function buildSystemPrompt(
     `Copy guidelines (three distinct outputs):`,
     `- \`title\` and \`body\` are for native notification popups (e.g. vellum desktop/mobile) — keep them short and glanceable (title ≤ 8 words, body ≤ 2 sentences).`,
     `- \`deliveryText\` is the channel-native message for chat channels (e.g. telegram). It must read naturally as a standalone message.`,
-    `  - Do not prepend mechanical labels like "Thread:".`,
+    `  - Do not prepend mechanical labels like "Conversation:".`,
     `  - Do not mention channel or transport names (e.g. Telegram, Slack, email) unless the event context explicitly requires it.`,
     `  - Do not repeat title/body verbatim unless that repetition is truly necessary.`,
     `  - Avoid meta-send phrasing (e.g. "I'd like to send a notification", "May I go ahead with that?"). Write the recipient-facing message directly.`,
     `  - For telegram: 1-2 concise sentences.`,
-    `- \`threadSeedMessage\` is the opening message in the internal notification thread — it can be richer and more contextual.`,
+    `- \`conversationSeedMessage\` is the opening message in the internal notification conversation — 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.`,
+    `Conversation reuse guidelines:`,
+    `- For each selected channel, decide whether to start a new conversation or reuse an existing one.`,
+    `- Set \`conversationActions\` 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 conversation (same event type, related context).`,
+    `- Prefer \`start_new\` when the signal is a distinct event that deserves its own conversation.`,
     `- 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.`,
   );
@@ -115,9 +127,9 @@ function buildSystemPrompt(
   if (candidateContext) {
     sections.push(
       ``,
-      `<thread-candidates>`,
+      `<conversation-candidates>`,
       candidateContext,
-      `</thread-candidates>`,
+      `</conversation-candidates>`,
     );
   }
 
@@ -213,15 +225,15 @@ function buildDecisionTool(availableChannels: NotificationChannel[]) {
                     description:
                       "Channel-native chat message text (for example Telegram). Must stand alone naturally.",
                   },
-                  threadTitle: {
+                  conversationTitle: {
                     type: "string",
                     description:
-                      "Optional thread title for grouped notifications",
+                      "Optional conversation title for grouped notifications",
                   },
-                  threadSeedMessage: {
+                  conversationSeedMessage: {
                     type: "string",
                     description:
-                      "Richer opening message for the notification thread. More contextual than title/body. For vellum: 2-4 sentences. For telegram: 1-2 sentences. Never raw JSON.",
+                      "Richer opening message for the notification conversation. More contextual than title/body. For vellum: 2-4 sentences. For telegram: 1-2 sentences. Never raw JSON.",
                   },
                 },
                 required: ["title", "body"],
@@ -229,10 +241,10 @@ function buildDecisionTool(availableChannels: NotificationChannel[]) {
             ]),
           ),
         },
-        threadActions: {
+        conversationActions: {
           type: "object",
           description:
-            "Per-channel thread action: start a new thread or reuse an existing candidate. Keyed by channel name.",
+            "Per-channel conversation action: start a new conversation or reuse an existing candidate. Keyed by channel name.",
           properties: Object.fromEntries(
             availableChannels.map((ch) => [
               ch,
@@ -243,12 +255,12 @@ function buildDecisionTool(availableChannels: NotificationChannel[]) {
                     type: "string",
                     enum: ["start_new", "reuse_existing"],
                     description:
-                      "Whether to start a new thread or reuse an existing one.",
+                      "Whether to start a new conversation 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 when action is reuse_existing. Must be a conversationId from the provided conversation candidates.",
                   },
                 },
                 required: ["action"],
@@ -307,7 +319,7 @@ function buildFallbackDecision(
       selectedChannels: [],
       reasoningSummary: "Fallback: suppressed (vellum channel not available)",
       renderedCopy: {},
-      dedupeKey: `fallback:${signal.sourceEventName}:${signal.sourceSessionId}:${signal.createdAt}`,
+      dedupeKey: `fallback:${signal.sourceEventName}:${signal.sourceContextId}:${signal.createdAt}`,
       confidence: 0.3,
       fallbackUsed: true,
     };
@@ -322,7 +334,7 @@ function buildFallbackDecision(
       ? "Fallback: high urgency + requires action — all channels"
       : "Fallback: vellum-only (local, always delivered)",
     renderedCopy: copy,
-    dedupeKey: `fallback:${signal.sourceEventName}:${signal.sourceSessionId}:${signal.createdAt}`,
+    dedupeKey: `fallback:${signal.sourceEventName}:${signal.sourceContextId}:${signal.createdAt}`,
     confidence: 0.3,
     fallbackUsed: true,
   };
@@ -335,7 +347,7 @@ const VALID_CHANNELS = new Set<string>(getDeliverableChannels());
 function validateDecisionOutput(
   input: Record<string, unknown>,
   availableChannels: NotificationChannel[],
-  candidateSet?: ThreadCandidateSet,
+  candidateSet?: ConversationCandidateSet,
 ): NotificationDecision | null {
   if (typeof input.shouldNotify !== "boolean") return null;
   if (typeof input.reasoningSummary !== "string") return null;
@@ -377,11 +389,13 @@ function validateDecisionOutput(
             body: c.body,
             deliveryText:
               typeof c.deliveryText === "string" ? c.deliveryText : undefined,
-            threadTitle:
-              typeof c.threadTitle === "string" ? c.threadTitle : undefined,
-            threadSeedMessage:
-              typeof c.threadSeedMessage === "string"
-                ? c.threadSeedMessage
+            conversationTitle:
+              typeof c.conversationTitle === "string"
+                ? c.conversationTitle
+                : undefined,
+            conversationSeedMessage:
+              typeof c.conversationSeedMessage === "string"
+                ? c.conversationSeedMessage
                 : undefined,
           };
         }
@@ -389,9 +403,9 @@ function validateDecisionOutput(
     }
   }
 
-  // Validate threadActions — strictly against the provided candidate set
-  const threadActions = validateThreadActions(
-    input.threadActions,
+  // Validate conversationActions — strictly against the provided candidate set
+  const conversationActions = validateConversationActions(
+    input.conversationActions,
     validChannels,
     candidateSet,
   );
@@ -406,8 +420,10 @@ function validateDecisionOutput(
     selectedChannels: validChannels,
     reasoningSummary: input.reasoningSummary,
     renderedCopy,
-    threadActions:
-      Object.keys(threadActions).length > 0 ? threadActions : undefined,
+    conversationActions:
+      Object.keys(conversationActions).length > 0
+        ? conversationActions
+        : undefined,
     deepLinkTarget,
     dedupeKey: input.dedupeKey,
     confidence,
@@ -415,10 +431,10 @@ function validateDecisionOutput(
   };
 }
 
-// ── Thread action validation ───────────────────────────────────────────
+// ── Conversation action validation ────────────────────────────────────
 
 /**
- * Validate and sanitize thread actions from LLM output.
+ * Validate and sanitize conversation actions from LLM output.
  *
  * - reuse_existing targets are checked against the candidate set; invalid
  *   targets are downgraded to start_new with a warning.
@@ -426,12 +442,12 @@ function validateDecisionOutput(
  * - Missing actions for selected channels default to start_new (handled
  *   downstream, not materialized here to keep the output compact).
  */
-export function validateThreadActions(
+export function validateConversationActions(
   raw: unknown,
   validChannels: NotificationChannel[],
-  candidateSet?: ThreadCandidateSet,
-): Partial<Record<NotificationChannel, ThreadAction>> {
-  const result: Partial<Record<NotificationChannel, ThreadAction>> = {};
+  candidateSet?: ConversationCandidateSet,
+): Partial<Record<NotificationChannel, ConversationAction>> {
+  const result: Partial<Record<NotificationChannel, ConversationAction>> = {};
 
   if (!raw || typeof raw !== "object") return result;
 
@@ -522,9 +538,9 @@ function ensureGuardianRequestCodeInCopy(
     deliveryText: copy.deliveryText
       ? ensureText(copy.deliveryText)
       : copy.deliveryText,
-    threadSeedMessage: copy.threadSeedMessage
-      ? ensureText(copy.threadSeedMessage)
-      : copy.threadSeedMessage,
+    conversationSeedMessage: copy.conversationSeedMessage
+      ? ensureText(copy.conversationSeedMessage)
+      : copy.conversationSeedMessage,
   };
 }
 
@@ -643,9 +659,9 @@ function ensureAccessRequestInstructionsInCopy(
     deliveryText: copy.deliveryText
       ? ensureText(copy.deliveryText)
       : copy.deliveryText,
-    threadSeedMessage: copy.threadSeedMessage
-      ? ensureText(copy.threadSeedMessage)
-      : copy.threadSeedMessage,
+    conversationSeedMessage: copy.conversationSeedMessage
+      ? ensureText(copy.conversationSeedMessage)
+      : copy.conversationSeedMessage,
   };
 }
 
@@ -665,9 +681,9 @@ function ensureInviteFlowDirectiveInCopy(
     deliveryText: copy.deliveryText
       ? ensureText(copy.deliveryText)
       : copy.deliveryText,
-    threadSeedMessage: copy.threadSeedMessage
-      ? ensureText(copy.threadSeedMessage)
-      : copy.threadSeedMessage,
+    conversationSeedMessage: copy.conversationSeedMessage
+      ? ensureText(copy.conversationSeedMessage)
+      : copy.conversationSeedMessage,
   };
 }
 
@@ -698,16 +714,16 @@ export async function evaluateSignal(
     }
   }
 
-  // Build thread candidate set for reuse decisions. Wrapped in try/catch
+  // Build conversation candidate set for reuse decisions. Wrapped in try/catch
   // so candidate lookup failures do not block the decision path.
-  let candidateSet: ThreadCandidateSet | undefined;
+  let candidateSet: ConversationCandidateSet | undefined;
   try {
-    candidateSet = buildThreadCandidates(availableChannels);
+    candidateSet = buildConversationCandidates(availableChannels);
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err);
     log.warn(
       { err: errMsg },
-      "Failed to build thread candidates, proceeding without candidates",
+      "Failed to build conversation candidates, proceeding without candidates",
     );
   }
 
@@ -719,7 +735,7 @@ export async function evaluateSignal(
     let decision = buildFallbackDecision(signal, availableChannels);
     decision = enforceGuardianRequestCode(decision, signal);
     decision = enforceAccessRequestInstructions(decision, signal);
-    decision = enforceGuardianCallThreadAffinity(decision, signal);
+    decision = enforceGuardianCallConversationAffinity(decision, signal);
     decision = enforceConversationAffinity(
       decision,
       signal.conversationAffinityHint,
@@ -731,6 +747,7 @@ export async function evaluateSignal(
   let decision: NotificationDecision;
   try {
     decision = await classifyWithLLM(
+      provider,
       signal,
       availableChannels,
       resolvedPreferenceContext,
@@ -748,7 +765,7 @@ export async function evaluateSignal(
 
   decision = enforceGuardianRequestCode(decision, signal);
   decision = enforceAccessRequestInstructions(decision, signal);
-  decision = enforceGuardianCallThreadAffinity(decision, signal);
+  decision = enforceGuardianCallConversationAffinity(decision, signal);
   decision = enforceConversationAffinity(
     decision,
     signal.conversationAffinityHint,
@@ -761,22 +778,24 @@ export async function evaluateSignal(
 // ── LLM classification ────────────────────────────────────────────────
 
 async function classifyWithLLM(
+  provider: Provider,
   signal: NotificationSignal,
   availableChannels: NotificationChannel[],
   preferenceContext: string | undefined,
   modelIntent: ModelIntent,
-  candidateSet?: ThreadCandidateSet,
+  candidateSet?: ConversationCandidateSet,
 ): Promise<NotificationDecision> {
-  const provider = (await getConfiguredProvider())!;
   const { signal: abortSignal, cleanup } = createTimeout(DECISION_TIMEOUT_MS);
 
   const candidateContext = candidateSet
     ? (serializeCandidatesForPrompt(candidateSet) ?? undefined)
     : undefined;
+  const identityContext = buildCoreIdentityContext() ?? undefined;
   const systemPrompt = buildSystemPrompt(
     availableChannels,
     preferenceContext,
     candidateContext,
+    identityContext,
   );
   const prompt = buildUserPrompt(signal);
   const tool = buildDecisionTool(availableChannels);
@@ -909,19 +928,19 @@ export function enforceRoutingIntent(
   return decision;
 }
 
-// ── Guardian call thread affinity ────────────────────────────────────────
+// ── Guardian call conversation affinity ──────────────────────────────────
 
 /**
- * Force a new vellum thread for the first guardian question in a phone call.
+ * Force a new vellum conversation for the first guardian question in a phone call.
  *
  * When a guardian.question signal carries a callSessionId but has no
  * conversationAffinityHint, this is the first dispatch in a new call and
- * should get its own thread. Without this guard the LLM might reuse a
- * thread from a previous call. For subsequent dispatches within the same
+ * should get its own conversation. Without this guard the LLM might reuse a
+ * conversation from a previous call. For subsequent dispatches within the same
  * call, the affinity hint already exists and enforceConversationAffinity
  * handles routing — so this guard is a no-op.
  */
-export function enforceGuardianCallThreadAffinity(
+export function enforceGuardianCallConversationAffinity(
   decision: NotificationDecision,
   signal: NotificationSignal,
 ): NotificationDecision {
@@ -936,15 +955,17 @@ export function enforceGuardianCallThreadAffinity(
   if (signal.conversationAffinityHint?.vellum) return decision;
 
   const enforced = { ...decision };
-  const threadActions: Partial<Record<NotificationChannel, ThreadAction>> = {
-    ...(decision.threadActions ?? {}),
+  const conversationActions: Partial<
+    Record<NotificationChannel, ConversationAction>
+  > = {
+    ...(decision.conversationActions ?? {}),
   };
-  threadActions.vellum = { action: "start_new" };
-  enforced.threadActions = threadActions;
+  conversationActions.vellum = { action: "start_new" };
+  enforced.conversationActions = conversationActions;
 
   log.info(
     { callSessionId },
-    "Guardian call thread affinity: first question in call — forcing start_new for vellum",
+    "Guardian call conversation affinity: first question in call — forcing start_new for vellum",
   );
 
   return enforced;
@@ -956,7 +977,7 @@ export function enforceGuardianCallThreadAffinity(
  * Enforce conversation affinity on a decision.
  *
  * When the signal carries a conversationAffinityHint (per-channel map of
- * conversationId), override the decision's threadActions for those channels
+ * conversationId), override the decision's conversationActions for those channels
  * to `reuse_existing` with the hinted conversationId. This is a
  * deterministic post-decision guard that prevents the LLM from routing
  * guardian questions for the same call session to different conversations.
@@ -974,22 +995,24 @@ export function enforceConversationAffinity(
   if (entries.length === 0) return decision;
 
   const enforced = { ...decision };
-  const threadActions: Partial<Record<NotificationChannel, ThreadAction>> = {
-    ...(decision.threadActions ?? {}),
+  const conversationActions: Partial<
+    Record<NotificationChannel, ConversationAction>
+  > = {
+    ...(decision.conversationActions ?? {}),
   };
 
   for (const [channel, conversationId] of entries) {
-    threadActions[channel as NotificationChannel] = {
+    conversationActions[channel as NotificationChannel] = {
       action: "reuse_existing",
       conversationId: conversationId!,
     };
   }
 
-  enforced.threadActions = threadActions;
+  enforced.conversationActions = conversationActions;
 
   log.info(
     { affinityHint },
-    "Conversation affinity enforcement: overrode threadActions for hinted channels",
+    "Conversation affinity enforcement: overrode conversationActions for hinted channels",
   );
 
   return enforced;
@@ -1004,14 +1027,14 @@ function persistDecision(
   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)) {
+    // Summarize conversation actions for the audit trail
+    const conversationActionSummary: Record<string, string> = {};
+    if (decision.conversationActions) {
+      for (const [ch, ta] of Object.entries(decision.conversationActions)) {
         if (ta.action === "reuse_existing") {
-          threadActionSummary[ch] = `reuse:${ta.conversationId}`;
+          conversationActionSummary[ch] = `reuse:${ta.conversationId}`;
         } else {
-          threadActionSummary[ch] = "start_new";
+          conversationActionSummary[ch] = "start_new";
         }
       }
     }
@@ -1029,8 +1052,8 @@ function persistDecision(
         dedupeKey: decision.dedupeKey,
         channelCount: decision.selectedChannels.length,
         hasCopy: Object.keys(decision.renderedCopy).length > 0,
-        ...(Object.keys(threadActionSummary).length > 0
-          ? { threadActions: threadActionSummary }
+        ...(Object.keys(conversationActionSummary).length > 0
+          ? { conversationActions: conversationActionSummary }
           : {}),
       },
     });

package/src/notifications/deliveries-store.ts

@@ -30,9 +30,9 @@ export interface NotificationDeliveryRow {
   conversationId: string | null;
   messageId: string | null;
   conversationStrategy: string | null;
-  threadAction: string | null;
-  threadTargetConversationId: string | null;
-  threadDecisionFallbackUsed: number | null;
+  conversationAction: string | null;
+  conversationTargetId: string | null;
+  conversationFallbackUsed: number | null;
   clientDeliveryStatus: string | null;
   clientDeliveryError: string | null;
   clientDeliveryAt: number | null;
@@ -58,9 +58,9 @@ function rowToDelivery(
     conversationId: row.conversationId,
     messageId: row.messageId,
     conversationStrategy: row.conversationStrategy,
-    threadAction: row.threadAction,
-    threadTargetConversationId: row.threadTargetConversationId,
-    threadDecisionFallbackUsed: row.threadDecisionFallbackUsed,
+    conversationAction: row.conversationAction,
+    conversationTargetId: row.conversationTargetId,
+    conversationFallbackUsed: row.conversationFallbackUsed,
     clientDeliveryStatus: row.clientDeliveryStatus,
     clientDeliveryError: row.clientDeliveryError,
     clientDeliveryAt: row.clientDeliveryAt,
@@ -84,9 +84,9 @@ export interface CreateDeliveryParams {
   conversationId?: string;
   messageId?: string;
   conversationStrategy?: string;
-  threadAction?: string;
-  threadTargetConversationId?: string;
-  threadDecisionFallbackUsed?: boolean;
+  conversationAction?: string;
+  conversationTargetId?: string;
+  conversationFallbackUsed?: boolean;
 }
 
 /** Create a new delivery audit record. */
@@ -111,11 +111,11 @@ export function createDelivery(
     conversationId: params.conversationId ?? null,
     messageId: params.messageId ?? null,
     conversationStrategy: params.conversationStrategy ?? null,
-    threadAction: params.threadAction ?? null,
-    threadTargetConversationId: params.threadTargetConversationId ?? null,
-    threadDecisionFallbackUsed:
-      params.threadDecisionFallbackUsed != null
-        ? params.threadDecisionFallbackUsed
+    conversationAction: params.conversationAction ?? null,
+    conversationTargetId: params.conversationTargetId ?? null,
+    conversationFallbackUsed:
+      params.conversationFallbackUsed != null
+        ? params.conversationFallbackUsed
           ? 1
           : 0
         : null,

package/src/notifications/emit-signal.ts

@@ -18,8 +18,8 @@ import { type BroadcastFn, VellumAdapter } from "./adapters/macos.js";
 import { SlackAdapter } from "./adapters/slack.js";
 import { TelegramAdapter } from "./adapters/telegram.js";
 import {
+  type ConversationCreatedInfo,
   NotificationBroadcaster,
-  type ThreadCreatedInfo,
 } from "./broadcaster.js";
 import { enforceRoutingIntent, evaluateSignal } from "./decision-engine.js";
 import { updateDecision } from "./decisions-store.js";
@@ -67,14 +67,14 @@ function getBroadcaster(): NotificationBroadcaster {
     }
     broadcasterInstance = new NotificationBroadcaster(adapters);
 
-    // Wire the thread-created callback so the macOS client is notified
-    // immediately when a vellum notification thread is paired — before
+    // Wire the conversation-created callback so the macOS client is notified
+    // immediately when a vellum notification conversation is paired — before
     // slower channel deliveries (e.g. Telegram) delay the push.
     if (registeredBroadcastFn) {
       const broadcastFn = registeredBroadcastFn;
-      broadcasterInstance.setOnThreadCreated((info) => {
+      broadcasterInstance.setOnConversationCreated((info) => {
         broadcastFn({
-          type: "notification_thread_created",
+          type: "notification_conversation_created",
           conversationId: info.conversationId,
           title: info.title,
           sourceEventName: info.sourceEventName,
@@ -85,7 +85,7 @@ function getBroadcaster(): NotificationBroadcaster {
             conversationId: info.conversationId,
             guardianScoped: info.targetGuardianPrincipalId != null,
           },
-          "Emitted notification_thread_created push event",
+          "Emitted notification_conversation_created push event",
         );
       });
     }
@@ -148,8 +148,8 @@ export interface EmitSignalParams<TEventName extends string = string> {
   sourceEventName: TEventName;
   /** Source channel that produced the event — must be a registered channel. */
   sourceChannel: NotificationSourceChannel;
-  /** Session or conversation ID from the source context. */
-  sourceSessionId: string;
+  /** Opaque identifier for the source context (conversation ID, schedule ID, call session ID, etc.). */
+  sourceContextId: string;
   /** Attention hints for the decision engine. */
   attentionHints: AttentionHints;
   /** Arbitrary context payload passed to the decision engine. */
@@ -161,16 +161,16 @@ export interface EmitSignalParams<TEventName extends string = string> {
   /**
    * Per-channel conversation affinity hint. Forces the decision engine to
    * reuse the specified conversation for the given channel(s), bypassing
-   * LLM thread-routing judgment. Keyed by channel name, value is conversationId.
+   * LLM conversation-routing judgment. Keyed by channel name, value is conversationId.
    */
   conversationAffinityHint?: Partial<Record<string, string>>;
   /** Optional deduplication key. */
   dedupeKey?: string;
   /**
    * Optional callback invoked immediately when the broadcaster pairs a vellum
-   * thread and emits `notification_thread_created`.
+   * conversation and emits `notification_conversation_created`.
    */
-  onThreadCreated?: (info: ThreadCreatedInfo) => void;
+  onConversationCreated?: (info: ConversationCreatedInfo) => void;
   /**
    * When true, rethrow pipeline errors to the caller instead of only logging.
    * Useful for direct user-invoked actions that must fail closed.
@@ -202,7 +202,7 @@ export async function emitNotificationSignal<TEventName extends string>(
     signalId,
     createdAt: Date.now(),
     sourceChannel: params.sourceChannel,
-    sourceSessionId: params.sourceSessionId,
+    sourceContextId: params.sourceContextId,
     sourceEventName: params.sourceEventName,
     contextPayload: (params.contextPayload ??
       {}) as NotificationContextPayload<TEventName>,
@@ -218,7 +218,7 @@ export async function emitNotificationSignal<TEventName extends string>(
       id: signalId,
       sourceEventName: params.sourceEventName,
       sourceChannel: params.sourceChannel,
-      sourceSessionId: params.sourceSessionId,
+      sourceContextId: params.sourceContextId,
       attentionHints: params.attentionHints,
       payload: params.contextPayload ?? {},
       dedupeKey: params.dedupeKey,
@@ -320,7 +320,7 @@ export async function emitNotificationSignal<TEventName extends string>(
     }
 
     // Step 4: Dispatch through the broadcaster
-    // Note: notification_thread_created events are emitted eagerly inside
+    // Note: notification_conversation_created events are emitted eagerly inside
     // the broadcaster as soon as vellum conversation pairing succeeds, rather
     // than after all channel deliveries complete. This avoids a race where
     // slow Telegram delivery delays the push past the macOS deep-link retry.
@@ -329,8 +329,8 @@ export async function emitNotificationSignal<TEventName extends string>(
       signal,
       decision,
       broadcaster,
-      params.onThreadCreated
-        ? { onThreadCreated: params.onThreadCreated }
+      params.onConversationCreated
+        ? { onConversationCreated: params.onConversationCreated }
         : undefined,
     );