@vellumai/assistant 0.4.55 → 0.4.57

package/src/notifications/broadcaster.ts

@@ -25,31 +25,31 @@ import type { NotificationSignal } from "./signal.js";
 import type {
   ChannelAdapter,
   ChannelDeliveryPayload,
+  ConversationAction,
   NotificationChannel,
   NotificationDecision,
   NotificationDeliveryResult,
   RenderedChannelCopy,
-  ThreadAction,
 } from "./types.js";
 
 const log = getLogger("notif-broadcaster");
 
-/** Callback invoked immediately when a vellum notification thread is created. */
-export interface ThreadCreatedInfo {
+/** Callback invoked immediately when a vellum notification conversation is created. */
+export interface ConversationCreatedInfo {
   conversationId: string;
   title: string;
   sourceEventName: string;
-  /** Present when the thread is for a guardian-sensitive notification. */
+  /** Present when the conversation is for a guardian-sensitive notification. */
   targetGuardianPrincipalId?: string;
 }
-export type OnThreadCreatedFn = (info: ThreadCreatedInfo) => void;
+export type OnConversationCreatedFn = (info: ConversationCreatedInfo) => void;
 export interface BroadcastDecisionOptions {
-  onThreadCreated?: OnThreadCreatedFn;
+  onConversationCreated?: OnConversationCreatedFn;
 }
 
 export class NotificationBroadcaster {
   private adapters: Map<NotificationChannel, ChannelAdapter>;
-  private onThreadCreated: OnThreadCreatedFn | null = null;
+  private onConversationCreated: OnConversationCreatedFn | null = null;
 
   constructor(adapters: ChannelAdapter[]) {
     this.adapters = new Map();
@@ -59,8 +59,8 @@ export class NotificationBroadcaster {
   }
 
   /** Register a callback that fires immediately when a vellum conversation is paired. */
-  setOnThreadCreated(fn: OnThreadCreatedFn): void {
-    this.onThreadCreated = fn;
+  setOnConversationCreated(fn: OnConversationCreatedFn): void {
+    this.onConversationCreated = fn;
   }
 
   /**
@@ -79,7 +79,7 @@ export class NotificationBroadcaster {
   ): Promise<NotificationDeliveryResult[]> {
     const destinations = resolveDestinations(decision.selectedChannels);
 
-    // Ensure vellum is processed first so the notification_thread_created
+    // Ensure vellum is processed first so the notification_conversation_created
     // event fires immediately, before slower channel sends (e.g. Telegram 30s
     // timeout) can delay it past the macOS deep-link retry window.
     const orderedChannels = [...decision.selectedChannels].sort((a, b) => {
@@ -147,12 +147,12 @@ export class NotificationBroadcaster {
         };
       }
 
-      // Resolve the per-channel thread action from the decision (default: start_new)
-      const threadAction: ThreadAction | undefined =
-        decision.threadActions?.[channel];
+      // Resolve the per-channel conversation action from the decision (default: start_new)
+      const conversationAction: ConversationAction | undefined =
+        decision.conversationActions?.[channel];
 
       // Check for duplicate delivery BEFORE pairing to avoid side effects
-      // (e.g. appending seed messages to existing threads) on retry paths
+      // (e.g. appending seed messages to existing conversations) on retry paths
       // where a delivery row already exists.
       const persistedDecisionId = decision.persistedDecisionId;
       const hasPersistedDecision = typeof persistedDecisionId === "string";
@@ -184,17 +184,17 @@ export class NotificationBroadcaster {
         }
       }
 
-      // Pair the delivery with a conversation before sending, passing the thread action
+      // Pair the delivery with a conversation before sending, passing the conversation action
       // and destination binding context for channel-scoped continuation
       const pairing = await pairDeliveryWithConversation(
         signal,
         channel,
         copy,
-        { threadAction, bindingContext: destination.bindingContext },
+        { conversationAction, bindingContext: destination.bindingContext },
       );
 
       // For the vellum channel, merge the conversationId into deep-link metadata
-      // so the macOS/iOS client can navigate directly to the notification thread.
+      // so the macOS/iOS client can navigate directly to the notification conversation.
       let deepLinkTarget = decision.deepLinkTarget;
       if (channel === "vellum" && pairing.conversationId) {
         deepLinkTarget = {
@@ -205,8 +205,8 @@ export class NotificationBroadcaster {
           deepLinkTarget = { ...deepLinkTarget, messageId: pairing.messageId };
         }
 
-        // Resolve guardian scoping for thread-created events so clients
-        // can filter guardian-sensitive threads the same way they filter
+        // Resolve guardian scoping for conversation-created events so clients
+        // can filter guardian-sensitive conversations the same way they filter
         // guardian-sensitive notification intents.
         const guardianPrincipalId =
           typeof destination.metadata?.guardianPrincipalId === "string"
@@ -218,45 +218,45 @@ export class NotificationBroadcaster {
             ? guardianPrincipalId
             : undefined;
 
-        const threadTitle =
-          copy.threadTitle ?? copy.title ?? signal.sourceEventName;
-        const info: ThreadCreatedInfo = {
+        const conversationTitle =
+          copy.conversationTitle ?? copy.title ?? signal.sourceEventName;
+        const info: ConversationCreatedInfo = {
           conversationId: pairing.conversationId,
-          title: threadTitle,
+          title: conversationTitle,
           sourceEventName: signal.sourceEventName,
           targetGuardianPrincipalId,
         };
 
-        // The per-dispatch onThreadCreated callback fires whenever a vellum
+        // The per-dispatch onConversationCreated callback fires whenever a vellum
         // conversation is paired (new or reused) because callers like
         // dispatchGuardianQuestion rely on it to create delivery bookkeeping
         // rows before emitNotificationSignal() returns.
-        if (options?.onThreadCreated) {
+        if (options?.onConversationCreated) {
           try {
-            options.onThreadCreated(info);
+            options.onConversationCreated(info);
           } catch (err) {
             log.error(
               { err, signalId: signal.signalId },
-              "per-dispatch onThreadCreated callback failed — continuing broadcast",
+              "per-dispatch onConversationCreated callback failed — continuing broadcast",
             );
           }
         }
 
-        // Emit notification_thread_created event only when a NEW
-        // conversation was actually created. Reusing an existing thread
+        // Emit notification_conversation_created event only when a NEW
+        // conversation was actually created. Reusing an existing conversation
         // should not fire the event — the client already knows about the
         // conversation.
         if (
           pairing.createdNewConversation &&
           pairing.strategy === "start_new_conversation"
         ) {
-          if (this.onThreadCreated) {
+          if (this.onConversationCreated) {
             try {
-              this.onThreadCreated(info);
+              this.onConversationCreated(info);
             } catch (err) {
               log.error(
                 { err, signalId: signal.signalId },
-                "onThreadCreated callback failed — continuing broadcast",
+                "onConversationCreated callback failed — continuing broadcast",
               );
             }
           }
@@ -273,14 +273,14 @@ export class NotificationBroadcaster {
         deepLinkTarget,
       };
 
-      // Compute thread decision audit fields for the delivery record
-      const threadAudit = {
-        threadAction: threadAction?.action ?? "start_new",
-        threadTargetConversationId:
-          threadAction?.action === "reuse_existing"
-            ? threadAction.conversationId
+      // Compute conversation decision audit fields for the delivery record
+      const conversationAudit = {
+        conversationAction: conversationAction?.action ?? "start_new",
+        conversationTargetId:
+          conversationAction?.action === "reuse_existing"
+            ? conversationAction.conversationId
             : undefined,
-        threadDecisionFallbackUsed: pairing.threadDecisionFallbackUsed,
+        conversationFallbackUsed: pairing.conversationFallbackUsed,
       };
 
       try {
@@ -297,7 +297,7 @@ export class NotificationBroadcaster {
             conversationId: pairing.conversationId ?? undefined,
             messageId: pairing.messageId ?? undefined,
             conversationStrategy: pairing.strategy,
-            ...threadAudit,
+            ...conversationAudit,
           });
         } else {
           log.warn(

package/src/notifications/{thread-candidates.ts → conversation-candidates.ts}

@@ -1,9 +1,9 @@
 /**
- * Thread candidate builder for notification thread reuse.
+ * Conversation candidate builder for notification conversation 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
+ * starting a new conversation. Includes guardian-specific context (pending
  * unresolved request count) when available.
  *
  * The candidate set is intentionally compact — only the fields the LLM
@@ -23,9 +23,9 @@ import {
 import { getLogger } from "../util/logger.js";
 import type { NotificationChannel } from "./types.js";
 
-const log = getLogger("thread-candidates");
+const log = getLogger("conversation-candidates");
 
-/** Maximum number of candidate threads to surface per channel. */
+/** Maximum number of candidate conversations to surface per channel. */
 const MAX_CANDIDATES_PER_CHANNEL = 5;
 
 /** Only consider conversations updated within this window (ms). */
@@ -33,14 +33,14 @@ const CANDIDATE_RECENCY_WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours
 
 // -- Public types -------------------------------------------------------------
 
-/** Guardian-specific context attached to a thread candidate when available. */
+/** Guardian-specific context attached to a conversation 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 {
+export interface ConversationCandidate {
   conversationId: string;
   title: string | null;
   updatedAt: number;
@@ -52,14 +52,14 @@ export interface ThreadCandidate {
 }
 
 /** Candidate set for the decision engine, keyed by channel. */
-export type ThreadCandidateSet = Partial<
-  Record<NotificationChannel, ThreadCandidate[]>
+export type ConversationCandidateSet = Partial<
+  Record<NotificationChannel, ConversationCandidate[]>
 >;
 
 // -- Core builder -------------------------------------------------------------
 
 /**
- * Build the thread candidate set for all selected channels.
+ * Build the conversation candidate set for all selected channels.
  *
  * Queries recent notification-sourced conversations that were delivered
  * to each channel and enriches them with guardian-specific metadata
@@ -68,10 +68,10 @@ export type ThreadCandidateSet = Partial<
  * Errors are caught per-channel so a failure in one channel does not
  * block candidates for others.
  */
-export function buildThreadCandidates(
+export function buildConversationCandidates(
   channels: NotificationChannel[],
-): ThreadCandidateSet {
-  const result: ThreadCandidateSet = {};
+): ConversationCandidateSet {
+  const result: ConversationCandidateSet = {};
   const cutoff = Date.now() - CANDIDATE_RECENCY_WINDOW_MS;
 
   for (const channel of channels) {
@@ -84,7 +84,7 @@ export function buildThreadCandidates(
       const errMsg = err instanceof Error ? err.message : String(err);
       log.warn(
         { err: errMsg, channel },
-        "Failed to build thread candidates for channel",
+        "Failed to build conversation candidates for channel",
       );
     }
   }
@@ -104,7 +104,7 @@ export function buildThreadCandidates(
 function buildCandidatesForChannel(
   channel: NotificationChannel,
   cutoffMs: number,
-): ThreadCandidate[] {
+): ConversationCandidate[] {
   const db = getDb();
 
   // Find recent notification deliveries for this channel that have a
@@ -147,7 +147,7 @@ function buildCandidatesForChannel(
 
   // Deduplicate by conversationId (keep the most recent delivery per conversation)
   const seen = new Set<string>();
-  const candidates: ThreadCandidate[] = [];
+  const candidates: ConversationCandidate[] = [];
 
   for (const row of rows) {
     if (!row.conversationId) continue;
@@ -240,18 +240,18 @@ function batchCountPendingByConversation(
 // -- Prompt serialization -----------------------------------------------------
 
 /**
- * Serialize a thread candidate set into a compact text block suitable for
+ * Serialize a conversation 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,
+  candidateSet: ConversationCandidateSet,
 ): string | null {
   const channelEntries = Object.entries(candidateSet) as [
     NotificationChannel,
-    ThreadCandidate[],
+    ConversationCandidate[],
   ][];
   if (channelEntries.length === 0) return null;
 

package/src/notifications/conversation-pairing.ts

@@ -4,10 +4,10 @@
  * Materializes a conversation + message for each notification delivery
  * before the adapter sends it. This ensures every delivery has an
  * auditable conversation trail and enables the macOS/iOS client to
- * deep-link directly into the notification thread.
+ * deep-link directly into the notification conversation.
  *
  * Resolution order:
- * 1. Explicit `reuse_existing` thread action — highest precedence.
+ * 1. Explicit `reuse_existing` conversation action — highest precedence.
  * 2. Binding-key reuse — for `continue_existing_conversation` channels,
  *    looks up a previously bound conversation by (sourceChannel, externalChatId).
  * 3. Default — creates a fresh conversation and, when binding context is
@@ -27,12 +27,15 @@ import {
   upsertOutboundBinding,
 } from "../memory/external-conversation-store.js";
 import { getLogger } from "../util/logger.js";
+import {
+  composeConversationSeed,
+  isConversationSeedSane,
+} from "./conversation-seed-composer.js";
 import type { NotificationSignal } from "./signal.js";
-import { composeThreadSeed, isThreadSeedSane } from "./thread-seed-composer.js";
 import type {
+  ConversationAction,
   DestinationBindingContext,
   NotificationChannel,
-  ThreadAction,
 } from "./types.js";
 import type { RenderedChannelCopy } from "./types.js";
 
@@ -57,12 +60,12 @@ export interface PairingResult {
   /** True when a brand-new conversation was created; false when an existing one was reused. */
   createdNewConversation: boolean;
   /** When the model requested reuse_existing but the target was invalid, this is true. */
-  threadDecisionFallbackUsed: boolean;
+  conversationFallbackUsed: boolean;
 }
 
 export interface PairingOptions {
-  /** Per-channel thread action from the decision engine. */
-  threadAction?: ThreadAction;
+  /** Per-channel conversation action from the decision engine. */
+  conversationAction?: ConversationAction;
   /** Destination binding data for channel-scoped conversation continuation. */
   bindingContext?: DestinationBindingContext;
 }
@@ -74,7 +77,7 @@ export interface PairingOptions {
  * and materializes a conversation + assistant message accordingly.
  *
  * Resolution precedence:
- * 1. `options.threadAction === "reuse_existing"` — reuse the explicit target.
+ * 1. `options.conversationAction === "reuse_existing"` — reuse the explicit target.
  * 2. `continue_existing_conversation` strategy with binding context —
  *    look up a previously bound conversation by (sourceChannel, externalChatId).
  * 3. Create a new conversation (and upsert the binding when context is present).
@@ -99,35 +102,36 @@ export async function pairDeliveryWithConversation(
         messageId: null,
         strategy: "not_deliverable",
         createdNewConversation: false,
-        threadDecisionFallbackUsed: false,
+        conversationFallbackUsed: false,
       };
     }
 
-    const title = copy.threadTitle ?? copy.title ?? signal.sourceEventName;
+    const title =
+      copy.conversationTitle ?? copy.title ?? signal.sourceEventName;
 
-    // Only start_new_conversation threads should be user-visible in the sidebar.
-    // Channels with continue_existing_conversation reuse bound external threads
+    // Only start_new_conversation conversations should be user-visible in the sidebar.
+    // Channels with continue_existing_conversation reuse bound external conversations
     // and mark them as background so they don't clutter the sidebar UI.
-    const threadType =
+    const conversationType =
       strategy === "start_new_conversation" ? "standard" : "background";
 
-    // Prefer model-provided threadSeedMessage when present and sane;
+    // Prefer model-provided conversationSeedMessage when present and sane;
     // fall back to the runtime composer which adapts verbosity to the
     // delivery surface (vellum/macos = richer, telegram = compact).
-    const messageContent = isThreadSeedSane(copy.threadSeedMessage)
-      ? copy.threadSeedMessage
-      : composeThreadSeed(signal, channel, copy);
+    const messageContent = isConversationSeedSane(copy.conversationSeedMessage)
+      ? copy.conversationSeedMessage
+      : composeConversationSeed(signal, channel, copy);
 
-    const threadAction = options?.threadAction;
+    const conversationAction = options?.conversationAction;
     const bindingContext = options?.bindingContext;
 
     // Attempt to reuse an existing conversation when the model requests it
-    if (threadAction?.action === "reuse_existing") {
-      const targetId = threadAction.conversationId;
+    if (conversationAction?.action === "reuse_existing") {
+      const targetId = conversationAction.conversationId;
       const existing = getConversation(targetId);
 
       if (existing && existing.source === "notification") {
-        // Append the seed message to the existing conversation thread
+        // Append the seed message to the existing conversation
         const message = await addMessage(
           existing.id,
           "assistant",
@@ -153,7 +157,7 @@ export async function pairDeliveryWithConversation(
             strategy,
             conversationId: existing.id,
             messageId: message.id,
-            threadAction: "reuse_existing",
+            conversationAction: "reuse_existing",
           },
           "Reused existing notification conversation for delivery",
         );
@@ -163,7 +167,7 @@ export async function pairDeliveryWithConversation(
           messageId: message.id,
           strategy,
           createdNewConversation: false,
-          threadDecisionFallbackUsed: false,
+          conversationFallbackUsed: false,
         };
       }
 
@@ -176,12 +180,12 @@ export async function pairDeliveryWithConversation(
           targetExists: !!existing,
           targetSource: existing?.source,
         },
-        "Thread reuse target invalid — falling back to new conversation",
+        "Conversation reuse target invalid — falling back to new conversation",
       );
 
       const conversation = createConversation({
         title,
-        threadType,
+        conversationType,
         source: "notification",
       });
 
@@ -208,7 +212,7 @@ export async function pairDeliveryWithConversation(
         messageId: message.id,
         strategy,
         createdNewConversation: true,
-        threadDecisionFallbackUsed: true,
+        conversationFallbackUsed: true,
       };
     }
 
@@ -270,7 +274,7 @@ export async function pairDeliveryWithConversation(
             messageId: message.id,
             strategy,
             createdNewConversation: false,
-            threadDecisionFallbackUsed: false,
+            conversationFallbackUsed: false,
           };
         }
 
@@ -294,7 +298,7 @@ export async function pairDeliveryWithConversation(
     // notification copy from polluting conversational recall.
     const conversation = createConversation({
       title,
-      threadType,
+      conversationType,
       source: "notification",
     });
 
@@ -325,7 +329,7 @@ export async function pairDeliveryWithConversation(
         strategy,
         conversationId: conversation.id,
         messageId: message.id,
-        threadAction: threadAction?.action ?? "start_new",
+        conversationAction: conversationAction?.action ?? "start_new",
       },
       "Paired notification delivery with conversation",
     );
@@ -335,7 +339,7 @@ export async function pairDeliveryWithConversation(
       messageId: message.id,
       strategy,
       createdNewConversation: true,
-      threadDecisionFallbackUsed: false,
+      conversationFallbackUsed: false,
     };
   } catch (err) {
     log.error(
@@ -354,7 +358,7 @@ export async function pairDeliveryWithConversation(
       messageId: null,
       strategy: fallbackStrategy,
       createdNewConversation: false,
-      threadDecisionFallbackUsed: false,
+      conversationFallbackUsed: false,
     };
   }
 }

package/src/notifications/{thread-seed-composer.ts → conversation-seed-composer.ts}

@@ -1,7 +1,7 @@
 /**
- * Surface-aware thread seed message composer.
+ * Surface-aware conversation seed message composer.
  *
- * Generates richer seed content for notification threads than the concise
+ * Generates richer seed content for notification conversations than the concise
  * title/body used in native notification popups. Verbosity adapts to the
  * delivery surface: vellum/macos gets flowing prose, telegram gets compact.
  *
@@ -9,7 +9,7 @@
  * so LLM-localized copy is preserved for non-English users.
  *
  * This runs in the daemon runtime (not via skills), ensuring every
- * notification thread has a readable seed message regardless of whether
+ * notification conversation has a readable seed message regardless of whether
  * the decision engine's LLM produced one.
  */
 
@@ -55,12 +55,12 @@ export function resolveVerbosity(
 }
 
 /**
- * Check whether a model-provided threadSeedMessage is usable.
+ * Check whether a model-provided conversationSeedMessage is usable.
  *
  * Rejects empty strings, raw JSON dumps, and excessively long content.
  * Min-length is 3 (not higher) to support concise CJK text.
  */
-export function isThreadSeedSane(value: unknown): value is string {
+export function isConversationSeedSane(value: unknown): value is string {
   if (typeof value !== "string") return false;
   const trimmed = value.trim();
   if (trimmed.length < 3) return false;
@@ -86,7 +86,7 @@ function humanizeEventName(eventName: string): string {
  *
  * Extracts the most useful fields from `contextPayload` (common keys like
  * message, summary, body, preview, senderIdentifier, title, label, questionText) and combines
- * them with a humanized event name. This ensures notification threads retain
+ * them with a humanized event name. This ensures notification conversations retain
  * usable audit context even when the decision engine produces empty copy.
  */
 function buildContextFallback(signal: NotificationSignal): string {
@@ -127,16 +127,16 @@ function hasCopyContent(copy: RenderedChannelCopy): boolean {
 }
 
 /**
- * Compose a thread seed message from signal context.
+ * Compose a conversation seed message from signal context.
  *
  * Builds from `copy.title` and `copy.body` so that LLM-localized content
  * is preserved. Surface-aware formatting makes the seed richer on
  * desktop (flowing prose) and compact on mobile (title + body separated).
  *
  * When rendered copy is blank, falls back to signal metadata (event name
- * and context payload) so notification threads always have usable content.
+ * and context payload) so notification conversations always have usable content.
  */
-export function composeThreadSeed(
+export function composeConversationSeed(
   signal: NotificationSignal,
   channel: NotificationChannel,
   copy: RenderedChannelCopy,