@vellumai/assistant 0.3.16 → 0.3.19

package/src/__tests__/notification-broadcaster.test.ts

@@ -6,6 +6,8 @@
  * - Handles missing adapters gracefully
  * - Falls back to copy-composer when decision copy is missing
  * - Reports delivery results per channel
+ * - Emits notification_thread_created only when a new conversation is created
+ * - Does NOT emit notification_thread_created when reusing an existing thread
  */
 
 import { describe, expect, mock, test } from 'bun:test';
@@ -36,6 +38,32 @@ mock.module('../notifications/deliveries-store.js', () => ({
   updateDeliveryStatus: () => {},
 }));
 
+// Configurable mock for conversation-pairing.
+// By default returns a "new conversation" result with a stable UUID.
+// Set `nextPairingResult` to override the return value for a single call.
+let nextPairingResult: import('../notifications/conversation-pairing.js').PairingResult | null = null;
+let pairingCallCount = 0;
+
+mock.module('../notifications/conversation-pairing.js', () => ({
+  pairDeliveryWithConversation: async () => {
+    if (nextPairingResult) {
+      const result = nextPairingResult;
+      nextPairingResult = null;
+      return result;
+    }
+    // Default: simulate creating a new conversation with a unique ID
+    const id = `mock-conv-${++pairingCallCount}`;
+    return {
+      conversationId: id,
+      messageId: `mock-msg-${pairingCallCount}`,
+      strategy: 'start_new_conversation' as const,
+      createdNewConversation: true,
+      threadDecisionFallbackUsed: false,
+    };
+  },
+}));
+
+import type { ThreadCreatedInfo } from '../notifications/broadcaster.js';
 import { NotificationBroadcaster } from '../notifications/broadcaster.js';
 import type { NotificationSignal } from '../notifications/signal.js';
 import type {
@@ -167,10 +195,17 @@ describe('notification broadcaster', () => {
     await broadcaster.broadcastDecision(signal, decision);
 
     expect(vellumAdapter.sent).toHaveLength(1);
-    expect(vellumAdapter.sent[0].deepLinkTarget).toEqual({
-      conversationId: 'conv-123',
-      screen: 'thread',
-    });
+    // The broadcaster overwrites deepLinkTarget.conversationId with the
+    // paired conversation ID, so the original 'conv-123' is replaced.
+    // Verify the structure is correct and that conversationId comes from
+    // the pairing result, not the pre-pairing placeholder.
+    const deepLink = vellumAdapter.sent[0].deepLinkTarget;
+    expect(deepLink).toBeDefined();
+    expect(deepLink!.screen).toBe('thread');
+    expect(deepLink!.conversationId).toBeDefined();
+    expect(deepLink!.conversationId).not.toBe('conv-123');
+    // Should be the paired conversation ID from conversation-pairing
+    expect(deepLink!.conversationId).toMatch(/^mock-conv-\d+$/);
   });
 
   test('multiple channels receive independent copy from the decision', async () => {
@@ -253,4 +288,80 @@ describe('notification broadcaster', () => {
     expect(results).toHaveLength(0);
     expect(vellumAdapter.sent).toHaveLength(0);
   });
+
+  // ── Thread-created IPC emission ─────────────────────────────────────
+
+  test('fires onThreadCreated when a new vellum conversation is created (start_new)', async () => {
+    const vellumAdapter = new MockAdapter('vellum');
+    const broadcaster = new NotificationBroadcaster([vellumAdapter]);
+    const threadCreatedCalls: ThreadCreatedInfo[] = [];
+    broadcaster.setOnThreadCreated((info) => threadCreatedCalls.push(info));
+
+    const signal = makeSignal();
+    // No threadActions means default start_new behavior
+    const decision = makeDecision();
+
+    await broadcaster.broadcastDecision(signal, decision);
+
+    // Pairing creates a new conversation by default, so onThreadCreated should fire
+    expect(threadCreatedCalls).toHaveLength(1);
+    expect(threadCreatedCalls[0].sourceEventName).toBe('test.event');
+  });
+
+  test('fires per-dispatch onThreadCreated callback on new conversation', async () => {
+    const vellumAdapter = new MockAdapter('vellum');
+    const broadcaster = new NotificationBroadcaster([vellumAdapter]);
+    const dispatchCalls: ThreadCreatedInfo[] = [];
+
+    const signal = makeSignal();
+    const decision = makeDecision();
+
+    await broadcaster.broadcastDecision(signal, decision, {
+      onThreadCreated: (info) => dispatchCalls.push(info),
+    });
+
+    expect(dispatchCalls).toHaveLength(1);
+  });
+
+  test('does NOT fire class-level onThreadCreated when reusing an existing thread', async () => {
+    const vellumAdapter = new MockAdapter('vellum');
+    const broadcaster = new NotificationBroadcaster([vellumAdapter]);
+    const ipcCalls: ThreadCreatedInfo[] = [];
+    const dispatchCalls: ThreadCreatedInfo[] = [];
+    broadcaster.setOnThreadCreated((info) => ipcCalls.push(info));
+
+    // Simulate a successful reuse by injecting a pairing result with
+    // createdNewConversation=false. This bypasses the real conversation
+    // store (which would fall back to creating a new conversation since
+    // the target does not exist in the test DB).
+    nextPairingResult = {
+      conversationId: 'conv-reused-456',
+      messageId: 'msg-reused-789',
+      strategy: 'start_new_conversation',
+      createdNewConversation: false,
+      threadDecisionFallbackUsed: false,
+    };
+
+    const signal = makeSignal();
+    const decision = makeDecision({
+      threadActions: {
+        vellum: { action: 'reuse_existing', conversationId: 'conv-existing-123' },
+      },
+    });
+
+    await broadcaster.broadcastDecision(signal, decision, {
+      onThreadCreated: (info) => dispatchCalls.push(info),
+    });
+
+    // The class-level IPC callback should NOT fire because
+    // createdNewConversation is false — the client already knows about
+    // the reused conversation.
+    expect(ipcCalls).toHaveLength(0);
+
+    // The per-dispatch callback SHOULD fire for both new and reused
+    // pairings (used by callers like dispatchGuardianQuestion for
+    // delivery bookkeeping).
+    expect(dispatchCalls).toHaveLength(1);
+    expect(dispatchCalls[0].conversationId).toBe('conv-reused-456');
+  });
 });

package/src/__tests__/notification-decision-strategy.test.ts

@@ -3,7 +3,8 @@
  *
  * Validates that the deterministic fallback correctly classifies signals based
  * on urgency + requiresAction, that channel selection respects connected channels,
- * and that the copy-composer generates correct fallback copy for known event names.
+ * the copy-composer generates correct fallback copy for known event names, and
+ * thread action types are structurally correct.
  */
 
 import { describe, expect, test } from 'bun:test';

package/src/__tests__/notification-deep-link.test.ts

@@ -3,7 +3,8 @@
  *
  * Validates that the VellumAdapter broadcasts notification_intent with
  * deepLinkMetadata, and that the broadcaster correctly passes deepLinkTarget
- * from the decision through to the adapter payload.
+ * from the decision through to the adapter payload — regardless of whether
+ * the conversation was newly created or reused.
  */
 
 import { describe, expect, mock, test } from 'bun:test';
@@ -154,5 +155,47 @@ describe('notification deep-link metadata', () => {
       expect(metadata.conversationId).toBe('conv-task-run-42');
       expect(metadata.workItemId).toBe('work-item-7');
     });
+
+    // ── Deep-link conversationId present regardless of reuse/new ──────
+
+    test('deep-link payload includes conversationId for a newly created conversation', async () => {
+      const messages: ServerMessage[] = [];
+      const adapter = new VellumAdapter((msg) => messages.push(msg));
+
+      // Simulates the broadcaster merging pairing.conversationId into deep-link
+      // for a newly created notification thread (start_new path)
+      await adapter.send(
+        {
+          sourceEventName: 'reminder.fired',
+          copy: { title: 'Reminder', body: 'Take out the trash' },
+          deepLinkTarget: { conversationId: 'conv-new-thread-001' },
+        },
+        { channel: 'vellum' },
+      );
+
+      const msg = messages[0] as unknown as Record<string, unknown>;
+      const metadata = msg.deepLinkMetadata as Record<string, unknown>;
+      expect(metadata.conversationId).toBe('conv-new-thread-001');
+    });
+
+    test('deep-link payload includes conversationId for a reused conversation', async () => {
+      const messages: ServerMessage[] = [];
+      const adapter = new VellumAdapter((msg) => messages.push(msg));
+
+      // Simulates the broadcaster merging pairing.conversationId into deep-link
+      // for a reused notification thread (reuse_existing path)
+      await adapter.send(
+        {
+          sourceEventName: 'reminder.fired',
+          copy: { title: 'Follow-up', body: 'Still need to take out the trash' },
+          deepLinkTarget: { conversationId: 'conv-reused-thread-042' },
+        },
+        { channel: 'vellum' },
+      );
+
+      const msg = messages[0] as unknown as Record<string, unknown>;
+      const metadata = msg.deepLinkMetadata as Record<string, unknown>;
+      expect(metadata.conversationId).toBe('conv-reused-thread-042');
+    });
   });
 });

package/src/__tests__/notification-guardian-path.test.ts

@@ -333,4 +333,161 @@ describe('ASK_GUARDIAN canonical notification path', () => {
     expect(vellumDelivery!.status).toBe('failed');
     expect(vellumDelivery!.last_error).toContain('No vellum delivery result');
   });
+
+  test('context payload includes callSessionId and activeGuardianRequestCount for candidate-affinity', async () => {
+    const convId = 'conv-guardian-notif-affinity';
+    ensureConversation(convId);
+
+    const session = createCallSession({
+      conversationId: convId,
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15550002222',
+    });
+    const pq = createPendingQuestion(session.id, 'Affinity test question');
+
+    await dispatchGuardianQuestion({
+      callSessionId: session.id,
+      conversationId: convId,
+      assistantId: 'self',
+      pendingQuestion: pq,
+    });
+
+    expect(emitCalls.length).toBe(1);
+    const signalParams = emitCalls[0] as Record<string, unknown>;
+    const payload = signalParams.contextPayload as Record<string, unknown>;
+
+    // callSessionId is present for the decision engine to match candidates to the current call
+    expect(payload.callSessionId).toBe(session.id);
+    // activeGuardianRequestCount provides a hint about whether to reuse an existing thread
+    expect(typeof payload.activeGuardianRequestCount).toBe('number');
+    expect(payload.activeGuardianRequestCount).toBeGreaterThanOrEqual(1);
+  });
+
+  test('repeated guardian questions retain per-request delivery records when sharing a conversation', async () => {
+    const convId = 'conv-guardian-notif-reuse';
+    ensureConversation(convId);
+
+    const sharedConvId = 'conv-guardian-shared-thread';
+
+    const session = createCallSession({
+      conversationId: convId,
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15550002222',
+    });
+
+    // First guardian question
+    const pq1 = createPendingQuestion(session.id, 'Can they enter through the side gate?');
+    mockEmitResult = {
+      signalId: 'sig-reuse-a',
+      deduplicated: false,
+      dispatched: true,
+      reason: 'ok',
+      deliveryResults: [
+        {
+          channel: 'vellum',
+          destination: 'vellum',
+          status: 'sent',
+          conversationId: sharedConvId,
+        },
+      ],
+    };
+
+    await dispatchGuardianQuestion({
+      callSessionId: session.id,
+      conversationId: convId,
+      assistantId: 'self',
+      pendingQuestion: pq1,
+    });
+
+    // Second guardian question (same call, pipeline reuses the same conversation)
+    emitCalls.length = 0;
+    const pq2 = createPendingQuestion(session.id, 'What about the back door?');
+    mockEmitResult = {
+      signalId: 'sig-reuse-b',
+      deduplicated: false,
+      dispatched: true,
+      reason: 'ok',
+      deliveryResults: [
+        {
+          channel: 'vellum',
+          destination: 'vellum',
+          status: 'sent',
+          conversationId: sharedConvId,
+        },
+      ],
+    };
+
+    await dispatchGuardianQuestion({
+      callSessionId: session.id,
+      conversationId: convId,
+      assistantId: 'self',
+      pendingQuestion: pq2,
+    });
+
+    // Verify: two distinct guardian_action_requests exist
+    const db = getDb();
+    const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+    const requests = raw.query(
+      'SELECT id, question_text FROM guardian_action_requests WHERE call_session_id = ? ORDER BY created_at ASC',
+    ).all(session.id) as Array<{ id: string; question_text: string }>;
+    expect(requests).toHaveLength(2);
+    expect(requests[0].question_text).toBe('Can they enter through the side gate?');
+    expect(requests[1].question_text).toBe('What about the back door?');
+
+    // Verify: each request has its own delivery row pointing to the shared conversation
+    const deliveries = raw.query(
+      'SELECT request_id, destination_conversation_id, status FROM guardian_action_deliveries WHERE destination_conversation_id = ? ORDER BY created_at ASC',
+    ).all(sharedConvId) as Array<{ request_id: string; destination_conversation_id: string; status: string }>;
+    expect(deliveries).toHaveLength(2);
+    expect(deliveries[0].request_id).toBe(requests[0].id);
+    expect(deliveries[1].request_id).toBe(requests[1].id);
+    expect(deliveries[0].status).toBe('sent');
+    expect(deliveries[1].status).toBe('sent');
+  });
+
+  test('follow-up/timeout flow is unchanged — expired request still gets fallback delivery on no pipeline result', async () => {
+    const convId = 'conv-guardian-notif-timeout';
+    ensureConversation(convId);
+
+    // Simulate a scenario where the pipeline returns no delivery results (e.g. blocked)
+    mockEmitResult = {
+      signalId: 'sig-timeout',
+      deduplicated: false,
+      dispatched: false,
+      reason: 'blocked by deterministic checks',
+      deliveryResults: [],
+    };
+
+    const session = createCallSession({
+      conversationId: convId,
+      provider: 'twilio',
+      fromNumber: '+15550001111',
+      toNumber: '+15550002222',
+    });
+    const pq = createPendingQuestion(session.id, 'Timeout scenario');
+
+    await dispatchGuardianQuestion({
+      callSessionId: session.id,
+      conversationId: convId,
+      assistantId: 'self',
+      pendingQuestion: pq,
+    });
+
+    // The dispatch should still create a failed fallback delivery row
+    const db = getDb();
+    const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
+    const request = raw.query('SELECT id FROM guardian_action_requests WHERE call_session_id = ?').get(session.id) as
+      | { id: string }
+      | undefined;
+    expect(request).toBeDefined();
+
+    const delivery = raw.query(
+      'SELECT status, last_error FROM guardian_action_deliveries WHERE request_id = ? AND destination_channel = ?',
+    ).get(request!.id, 'vellum') as { status: string; last_error: string | null } | undefined;
+    expect(delivery).toBeDefined();
+    expect(delivery!.status).toBe('failed');
+    expect(delivery!.last_error).toContain('No vellum delivery result');
+  });
 });

package/src/__tests__/notification-thread-candidate-validation.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Focused tests for thread candidate validation in the notification decision
+ * engine. Validates that:
+ * - Valid reuse targets pass validation
+ * - Invalid reuse targets are rejected and downgraded to start_new
+ * - Candidate context is structurally correct and auditable
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { validateThreadActions } from '../notifications/decision-engine.js';
+import type {
+  ThreadCandidate,
+  ThreadCandidateSet,
+} from '../notifications/thread-candidates.js';
+import type {
+  NotificationChannel,
+  ThreadAction,
+} from '../notifications/types.js';
+
+// -- Helpers -----------------------------------------------------------------
+
+function makeCandidate(overrides?: Partial<ThreadCandidate>): ThreadCandidate {
+  return {
+    conversationId: 'conv-default',
+    title: 'Test Thread',
+    updatedAt: Date.now(),
+    latestSourceEventName: 'test.event',
+    channel: 'vellum' as NotificationChannel,
+    ...overrides,
+  };
+}
+
+/**
+ * Simple candidate ID check equivalent to the removed isValidCandidateId.
+ * Used in tests to verify candidate matching semantics.
+ */
+function isCandidateIdPresent(id: string, candidates: ThreadCandidate[]): boolean {
+  return candidates.some((c) => c.conversationId === id);
+}
+
+// -- Tests -------------------------------------------------------------------
+
+describe('thread candidate validation', () => {
+  describe('candidate ID matching', () => {
+    test('returns true when conversationId matches a candidate', () => {
+      const candidates = [
+        makeCandidate({ conversationId: 'conv-001' }),
+        makeCandidate({ conversationId: 'conv-002' }),
+      ];
+
+      expect(isCandidateIdPresent('conv-001', candidates)).toBe(true);
+      expect(isCandidateIdPresent('conv-002', candidates)).toBe(true);
+    });
+
+    test('returns false when conversationId does not match any candidate', () => {
+      const candidates = [
+        makeCandidate({ conversationId: 'conv-001' }),
+      ];
+
+      expect(isCandidateIdPresent('conv-999', candidates)).toBe(false);
+    });
+
+    test('returns false for empty candidate list', () => {
+      expect(isCandidateIdPresent('conv-001', [])).toBe(false);
+    });
+
+    test('returns false for empty string conversationId', () => {
+      const candidates = [
+        makeCandidate({ conversationId: 'conv-001' }),
+      ];
+
+      expect(isCandidateIdPresent('', candidates)).toBe(false);
+    });
+
+    test('matching is exact (no substring or prefix matching)', () => {
+      const candidates = [
+        makeCandidate({ conversationId: 'conv-001' }),
+      ];
+
+      expect(isCandidateIdPresent('conv-00', candidates)).toBe(false);
+      expect(isCandidateIdPresent('conv-0011', candidates)).toBe(false);
+      expect(isCandidateIdPresent('CONV-001', candidates)).toBe(false);
+    });
+  });
+
+  describe('candidate metadata structure', () => {
+    test('candidate without guardian context has no optional fields', () => {
+      const candidate = makeCandidate();
+
+      expect(candidate.guardianContext).toBeUndefined();
+    });
+
+    test('candidate with guardian context includes pending counts', () => {
+      const candidate = makeCandidate({
+        guardianContext: { pendingUnresolvedRequestCount: 3 },
+      });
+
+      expect(candidate.guardianContext?.pendingUnresolvedRequestCount).toBe(3);
+    });
+
+    test('candidate with null title is valid', () => {
+      const candidate = makeCandidate({ title: null });
+      expect(candidate.title).toBeNull();
+    });
+
+    test('candidate with null latestSourceEventName is valid', () => {
+      const candidate = makeCandidate({ latestSourceEventName: null });
+      expect(candidate.latestSourceEventName).toBeNull();
+    });
+  });
+
+  describe('thread action downgrade semantics', () => {
+    test('start_new action does not require a conversationId', () => {
+      const action: ThreadAction = { action: 'start_new' };
+      expect(action.action).toBe('start_new');
+      expect('conversationId' in action).toBe(false);
+    });
+
+    test('reuse_existing with valid candidate is accepted via validateThreadActions', () => {
+      const candidateSet: ThreadCandidateSet = {
+        vellum: [makeCandidate({ conversationId: 'conv-valid' })],
+      };
+
+      const result = validateThreadActions(
+        { vellum: { action: 'reuse_existing', conversationId: 'conv-valid' } },
+        ['vellum'] as NotificationChannel[],
+        candidateSet,
+      );
+
+      expect(result.vellum?.action).toBe('reuse_existing');
+      if (result.vellum?.action === 'reuse_existing') {
+        expect(result.vellum.conversationId).toBe('conv-valid');
+      }
+    });
+
+    test('reuse_existing with invalid candidate is downgraded to start_new', () => {
+      const candidateSet: ThreadCandidateSet = {
+        vellum: [makeCandidate({ conversationId: 'conv-valid' })],
+      };
+
+      const result = validateThreadActions(
+        { vellum: { action: 'reuse_existing', conversationId: 'conv-hacked' } },
+        ['vellum'] as NotificationChannel[],
+        candidateSet,
+      );
+
+      expect(result.vellum?.action).toBe('start_new');
+    });
+
+    test('reuse_existing with empty candidate set is downgraded to start_new', () => {
+      const result = validateThreadActions(
+        { vellum: { action: 'reuse_existing', conversationId: 'conv-any' } },
+        ['vellum'] as NotificationChannel[],
+        undefined,
+      );
+
+      expect(result.vellum?.action).toBe('start_new');
+    });
+  });
+
+  describe('candidate set per channel', () => {
+    test('channels without candidates result in empty map entries', () => {
+      const candidateMap: ThreadCandidateSet = {};
+
+      // When no candidates exist for vellum, the map has no entry
+      expect(candidateMap.vellum).toBeUndefined();
+    });
+
+    test('candidate set preserves channel association via validateThreadActions', () => {
+      const vellumCandidates = [
+        makeCandidate({ conversationId: 'conv-v1', channel: 'vellum' as NotificationChannel }),
+      ];
+      const telegramCandidates = [
+        makeCandidate({ conversationId: 'conv-t1', channel: 'telegram' as NotificationChannel }),
+      ];
+
+      const candidateSet: ThreadCandidateSet = {
+        vellum: vellumCandidates,
+        telegram: telegramCandidates,
+      };
+
+      // Vellum candidate should not be valid for telegram and vice versa
+      const validChannels: NotificationChannel[] = ['vellum', 'telegram'];
+
+      const result1 = validateThreadActions(
+        { vellum: { action: 'reuse_existing', conversationId: 'conv-v1' } },
+        validChannels,
+        candidateSet,
+      );
+      expect(result1.vellum?.action).toBe('reuse_existing');
+
+      const result2 = validateThreadActions(
+        { vellum: { action: 'reuse_existing', conversationId: 'conv-t1' } },
+        validChannels,
+        candidateSet,
+      );
+      expect(result2.vellum?.action).toBe('start_new');
+
+      const result3 = validateThreadActions(
+        { telegram: { action: 'reuse_existing', conversationId: 'conv-t1' } },
+        validChannels,
+        candidateSet,
+      );
+      expect(result3.telegram?.action).toBe('reuse_existing');
+
+      const result4 = validateThreadActions(
+        { telegram: { action: 'reuse_existing', conversationId: 'conv-v1' } },
+        validChannels,
+        candidateSet,
+      );
+      expect(result4.telegram?.action).toBe('start_new');
+    });
+  });
+});