@vellumai/assistant 0.4.2 → 0.4.4

package/src/__tests__/call-pointer-message-composer.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, test } from 'bun:test';
+import { mock } from 'bun:test';
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import {
+  buildPointerGenerationPrompt,
+  type CallPointerMessageContext,
+  composeCallPointerMessageGenerative,
+  getPointerFallbackMessage,
+  includesRequiredFacts,
+} from '../calls/call-pointer-message-composer.js';
+
+// ---------------------------------------------------------------------------
+// Deterministic fallback templates
+// ---------------------------------------------------------------------------
+
+describe('getPointerFallbackMessage', () => {
+  test('started without verification code', () => {
+    const msg = getPointerFallbackMessage({ scenario: 'started', phoneNumber: '+15551234567' });
+    expect(msg).toContain('Call to +15551234567 started');
+    expect(msg).not.toContain('Verification code');
+  });
+
+  test('started with verification code', () => {
+    const msg = getPointerFallbackMessage({
+      scenario: 'started',
+      phoneNumber: '+15551234567',
+      verificationCode: '1234',
+    });
+    expect(msg).toContain('Verification code: 1234');
+    expect(msg).toContain('+15551234567');
+  });
+
+  test('completed without duration', () => {
+    const msg = getPointerFallbackMessage({ scenario: 'completed', phoneNumber: '+15559876543' });
+    expect(msg).toContain('completed');
+    expect(msg).toContain('+15559876543');
+  });
+
+  test('completed with duration', () => {
+    const msg = getPointerFallbackMessage({
+      scenario: 'completed',
+      phoneNumber: '+15559876543',
+      duration: '5m 30s',
+    });
+    expect(msg).toContain('completed (5m 30s)');
+  });
+
+  test('failed without reason', () => {
+    const msg = getPointerFallbackMessage({ scenario: 'failed', phoneNumber: '+15559876543' });
+    expect(msg).toContain('failed');
+    expect(msg).toContain('+15559876543');
+  });
+
+  test('failed with reason', () => {
+    const msg = getPointerFallbackMessage({
+      scenario: 'failed',
+      phoneNumber: '+15559876543',
+      reason: 'no answer',
+    });
+    expect(msg).toContain('failed: no answer');
+  });
+
+  test('guardian_verification_succeeded defaults to voice channel', () => {
+    const msg = getPointerFallbackMessage({
+      scenario: 'guardian_verification_succeeded',
+      phoneNumber: '+15559876543',
+    });
+    expect(msg).toContain('Guardian verification (voice)');
+    expect(msg).toContain('succeeded');
+  });
+
+  test('guardian_verification_succeeded with custom channel', () => {
+    const msg = getPointerFallbackMessage({
+      scenario: 'guardian_verification_succeeded',
+      phoneNumber: '+15559876543',
+      channel: 'sms',
+    });
+    expect(msg).toContain('Guardian verification (sms)');
+  });
+
+  test('guardian_verification_failed without reason', () => {
+    const msg = getPointerFallbackMessage({
+      scenario: 'guardian_verification_failed',
+      phoneNumber: '+15559876543',
+    });
+    expect(msg).toContain('Guardian verification');
+    expect(msg).toContain('failed');
+  });
+
+  test('guardian_verification_failed with reason', () => {
+    const msg = getPointerFallbackMessage({
+      scenario: 'guardian_verification_failed',
+      phoneNumber: '+15559876543',
+      reason: 'Max attempts exceeded',
+    });
+    expect(msg).toContain('failed: Max attempts exceeded');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Required facts validation
+// ---------------------------------------------------------------------------
+
+describe('includesRequiredFacts', () => {
+  test('returns true when no required facts', () => {
+    expect(includesRequiredFacts('any text', undefined)).toBe(true);
+    expect(includesRequiredFacts('any text', [])).toBe(true);
+  });
+
+  test('returns true when all facts present', () => {
+    expect(includesRequiredFacts('Call to +15551234567 completed (2m).', ['+15551234567', '2m'])).toBe(true);
+  });
+
+  test('returns false when a fact is missing', () => {
+    expect(includesRequiredFacts('Call completed.', ['+15551234567'])).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+describe('buildPointerGenerationPrompt', () => {
+  test('includes context JSON and fallback message', () => {
+    const ctx: CallPointerMessageContext = { scenario: 'started', phoneNumber: '+15551234567' };
+    const prompt = buildPointerGenerationPrompt(ctx, 'Fallback text', undefined);
+    expect(prompt).toContain(JSON.stringify(ctx));
+    expect(prompt).toContain('Fallback text');
+  });
+
+  test('includes required facts clause when provided', () => {
+    const ctx: CallPointerMessageContext = { scenario: 'completed', phoneNumber: '+15559876543', duration: '3m' };
+    const prompt = buildPointerGenerationPrompt(ctx, 'Fallback', ['+15559876543', '3m']);
+    expect(prompt).toContain('Required facts to include');
+    expect(prompt).toContain('+15559876543');
+    expect(prompt).toContain('3m');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Generative composition (test env falls back to deterministic)
+// ---------------------------------------------------------------------------
+
+describe('composeCallPointerMessageGenerative', () => {
+  test('returns fallback in test environment regardless of generator', async () => {
+    const generator = async () => 'LLM-generated copy';
+    const ctx: CallPointerMessageContext = { scenario: 'started', phoneNumber: '+15551234567' };
+    const result = await composeCallPointerMessageGenerative(ctx, {}, generator);
+    // NODE_ENV is 'test' during bun test
+    expect(result).toContain('Call to +15551234567 started');
+  });
+
+  test('returns fallback when no generator provided', async () => {
+    const ctx: CallPointerMessageContext = { scenario: 'failed', phoneNumber: '+15559876543', reason: 'busy' };
+    const result = await composeCallPointerMessageGenerative(ctx);
+    expect(result).toContain('failed: busy');
+  });
+
+  test('uses custom fallbackText when provided', async () => {
+    const ctx: CallPointerMessageContext = { scenario: 'completed', phoneNumber: '+15559876543' };
+    const result = await composeCallPointerMessageGenerative(ctx, { fallbackText: 'Custom fallback' });
+    expect(result).toBe('Custom fallback');
+  });
+});

package/src/__tests__/call-pointer-messages.test.ts

@@ -2,7 +2,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { afterAll, beforeEach, describe, expect, mock,test } from 'bun:test';
+import { afterAll, afterEach, beforeEach, describe, expect, mock,test } from 'bun:test';
 
 const testDir = mkdtempSync(join(tmpdir(), 'call-pointer-messages-test-'));
 
@@ -25,14 +25,14 @@ mock.module('../util/logger.js', () => ({
     }),
 }));
 
-import { addPointerMessage, formatDuration } from '../calls/call-pointer-messages.js';
+import { addPointerMessage, formatDuration, resetPointerCopyGenerator, setPointerCopyGenerator } from '../calls/call-pointer-messages.js';
 import { getMessages } from '../memory/conversation-store.js';
 import { getDb, initializeDb, resetDb } from '../memory/db.js';
 import { conversations } from '../memory/schema.js';
 
 initializeDb();
 
-function ensureConversation(id: string): void {
+function ensureConversation(id: string, options?: { threadType?: string; originChannel?: string }): void {
   const db = getDb();
   const now = Date.now();
   db.insert(conversations).values({
@@ -40,6 +40,8 @@ function ensureConversation(id: string): void {
     title: `Conversation ${id}`,
     createdAt: now,
     updatedAt: now,
+    ...(options?.threadType ? { threadType: options.threadType } : {}),
+    ...(options?.originChannel ? { originChannel: options.originChannel } : {}),
   }).run();
 }
 
@@ -92,6 +94,10 @@ describe('addPointerMessage', () => {
     resetTables();
   });
 
+  afterEach(() => {
+    resetPointerCopyGenerator();
+  });
+
   afterAll(() => {
     resetDb();
     try { rmSync(testDir, { recursive: true }); } catch { /* best effort */ }
@@ -185,4 +191,88 @@ describe('addPointerMessage', () => {
     const text = getLatestAssistantText(convId);
     expect(text).toContain('failed: Max attempts exceeded');
   });
+
+  // Trust-aware tests: in test env, generator is not called (NODE_ENV=test
+  // short-circuits to fallback), so these validate the trust gating path
+  // while still receiving deterministic text.
+
+  test('untrusted audience uses deterministic fallback even with generator set', () => {
+    const convId = 'conv-ptr-untrusted';
+    // standard threadType + no origin channel = untrusted
+    ensureConversation(convId, { threadType: 'standard' });
+
+    const generatorCalled = { value: false };
+    setPointerCopyGenerator(async () => {
+      generatorCalled.value = true;
+      return 'generated text';
+    });
+
+    addPointerMessage(convId, 'started', '+15551234567');
+    const text = getLatestAssistantText(convId);
+    // In test env, deterministic fallback is always used regardless of trust
+    expect(text).toContain('Call to +15551234567 started');
+  });
+
+  test('explicit untrusted audience mode skips generator', () => {
+    const convId = 'conv-ptr-explicit-untrusted';
+    ensureConversation(convId, { threadType: 'private' });
+
+    const generatorCalled = { value: false };
+    setPointerCopyGenerator(async () => {
+      generatorCalled.value = true;
+      return 'generated text';
+    });
+
+    addPointerMessage(convId, 'started', '+15551234567', undefined, 'untrusted');
+    const text = getLatestAssistantText(convId);
+    expect(text).toContain('Call to +15551234567 started');
+    // generator is not called because audience is explicitly untrusted
+    expect(generatorCalled.value).toBe(false);
+  });
+
+  test('private threadType is detected as trusted audience', async () => {
+    const convId = 'conv-ptr-private';
+    ensureConversation(convId, { threadType: 'private' });
+
+    setPointerCopyGenerator(async () => 'generated text');
+
+    await addPointerMessage(convId, 'completed', '+15559876543', { duration: '1m' });
+    const text = getLatestAssistantText(convId);
+    // In test env, falls back to deterministic even on trusted path
+    expect(text).toContain('Call to +15559876543 completed (1m)');
+  });
+
+  test('vellum origin channel is detected as trusted audience', async () => {
+    const convId = 'conv-ptr-vellum';
+    ensureConversation(convId, { originChannel: 'vellum' });
+
+    setPointerCopyGenerator(async () => 'generated text');
+
+    await addPointerMessage(convId, 'failed', '+15559876543', { reason: 'busy' });
+    const text = getLatestAssistantText(convId);
+    expect(text).toContain('failed: busy');
+  });
+
+  test('missing conversation defaults to untrusted', () => {
+    const _convId = 'conv-ptr-missing';
+    // Don't create the conversation — trust resolution should default to untrusted
+
+    const generatorCalled = { value: false };
+    setPointerCopyGenerator(async () => {
+      generatorCalled.value = true;
+      return 'generated text';
+    });
+
+    // This will fail at addMessage because conversation doesn't exist,
+    // but the trust check itself should not throw. Test just the trust
+    // gating by using a conversation that exists but has no trust signals.
+    const convId2 = 'conv-ptr-no-signals';
+    ensureConversation(convId2);
+
+    addPointerMessage(convId2, 'started', '+15551234567');
+    const text = getLatestAssistantText(convId2);
+    expect(text).toContain('Call to +15551234567 started');
+    // generator not called because standard threadType + no origin = untrusted
+    expect(generatorCalled.value).toBe(false);
+  });
 });

package/src/__tests__/call-pointer-no-hardcoded-copy.guard.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Guard test: prevent reintroduction of hard-coded pointer copy in
+ * relay-server.ts, call-controller.ts, and call-domain.ts.
+ *
+ * Deterministic fallback literals should only exist in the pointer
+ * composer file (call-pointer-message-composer.ts). The call-site
+ * files should route through addPointerMessage() exclusively.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+const srcDir = join(import.meta.dir, '..');
+
+// These files must NOT contain inline pointer copy strings.
+const guardedFiles = [
+  'calls/relay-server.ts',
+  'calls/call-controller.ts',
+  'calls/call-domain.ts',
+];
+
+// Patterns that indicate inline pointer copy rather than routing through
+// addPointerMessage. We check for the distinctive emoji + "Call to" prefix
+// that the old hard-coded templates used.
+const forbiddenPatterns = [
+  /["\u{1F4DE}].*Call to.*(?:started|completed|failed)/u,
+  /["\u{2705}].*Guardian verification.*succeeded/u,
+  /["\u{274C}].*Guardian verification.*failed/u,
+];
+
+describe('no hardcoded pointer copy in call-site files', () => {
+  for (const file of guardedFiles) {
+    test(`${file} does not contain inline pointer copy`, () => {
+      const content = readFileSync(join(srcDir, file), 'utf-8');
+      for (const pattern of forbiddenPatterns) {
+        const match = pattern.exec(content);
+        expect(match).toBeNull();
+      }
+    });
+  }
+});

package/src/__tests__/call-routes-http.test.ts

@@ -177,10 +177,6 @@ describe('runtime call routes — HTTP layer', () => {
     return `http://127.0.0.1:${port}/v1/calls${path}`;
   }
 
-  function assistantCallsUrl(assistantId: string, path = ''): string {
-    return `http://127.0.0.1:${port}/v1/assistants/${assistantId}/calls${path}`;
-  }
-
   // ── POST /v1/calls/start ────────────────────────────────────────────
 
   test('POST /v1/calls/start returns 201 with call session', async () => {
@@ -235,27 +231,6 @@ describe('runtime call routes — HTTP layer', () => {
     await stopServer();
   });
 
-  test('POST /v1/assistants/:assistantId/calls/start uses assistant-scoped caller number', async () => {
-    await startServer();
-    ensureConversation('conv-start-scoped-1');
-
-    const res = await fetch(assistantCallsUrl('asst-alpha', '/start'), {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', ...AUTH_HEADERS },
-      body: JSON.stringify({
-        phoneNumber: '+15559997777',
-        task: 'Check order status',
-        conversationId: 'conv-start-scoped-1',
-      }),
-    });
-
-    expect(res.status).toBe(201);
-    const body = await res.json() as { fromNumber: string };
-    expect(body.fromNumber).toBe('+15550009999');
-
-    await stopServer();
-  });
-
   test('POST /v1/calls/start returns 400 for invalid phone number', async () => {
     await startServer();
     ensureConversation('conv-start-2');

package/src/__tests__/callback-handoff-copy.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Tests for the callback handoff notification fallback copy template.
+ *
+ * Verifies that the `ingress.access_request.callback_handoff` template in
+ * copy-composer.ts renders caller identity, request code, and trusted-contact
+ * member reference correctly — including graceful fallback when fields are missing.
+ */
+import { describe, expect, test } from 'bun:test';
+
+import { composeFallbackCopy } from '../notifications/copy-composer.js';
+import type { NotificationSignal } from '../notifications/signal.js';
+
+function buildSignal(payloadOverrides: Record<string, unknown> = {}): NotificationSignal {
+  return {
+    signalId: 'test-signal-1',
+    assistantId: 'self',
+    createdAt: Date.now(),
+    sourceChannel: 'voice',
+    sourceSessionId: 'test-session-1',
+    sourceEventName: 'ingress.access_request.callback_handoff',
+    contextPayload: {
+      requestId: 'req-123',
+      requestCode: null,
+      callSessionId: 'call-456',
+      sourceChannel: 'voice',
+      reason: 'timeout',
+      callbackOptIn: true,
+      callerPhoneNumber: '+15551234567',
+      callerName: null,
+      requesterExternalUserId: '+15551234567',
+      requesterChatId: '+15551234567',
+      requesterMemberId: null,
+      requesterMemberSourceChannel: null,
+      ...payloadOverrides,
+    },
+    attentionHints: {
+      requiresAction: false,
+      urgency: 'medium',
+      isAsyncBackground: true,
+      visibleInSourceNow: false,
+    },
+  };
+}
+
+describe('callback handoff copy template', () => {
+  test('renders caller name and phone when both are present', () => {
+    const signal = buildSignal({
+      callerName: 'Alice',
+      callerPhoneNumber: '+15551234567',
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.title).toBe('Callback Requested');
+    expect(copy.body).toContain('Alice (+15551234567)');
+    expect(copy.body).toContain('callback');
+    expect(copy.body).toContain('unreachable');
+  });
+
+  test('renders phone number only when caller name is missing', () => {
+    const signal = buildSignal({
+      callerName: null,
+      callerPhoneNumber: '+15559876543',
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.body).toContain('+15559876543');
+    expect(copy.body).not.toContain('null');
+  });
+
+  test('renders caller name only when phone is missing', () => {
+    const signal = buildSignal({
+      callerName: 'Bob',
+      callerPhoneNumber: null,
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.body).toContain('Bob');
+  });
+
+  test('falls back to "An unknown caller" when both name and phone are missing', () => {
+    const signal = buildSignal({
+      callerName: null,
+      callerPhoneNumber: null,
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.body).toContain('An unknown caller');
+  });
+
+  test('includes request code when present', () => {
+    const signal = buildSignal({
+      callerName: 'Charlie',
+      callerPhoneNumber: '+15551111111',
+      requestCode: 'a1b2c3',
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.body).toContain('A1B2C3');
+  });
+
+  test('omits request code line when not present', () => {
+    const signal = buildSignal({
+      callerName: 'Charlie',
+      callerPhoneNumber: '+15551111111',
+      requestCode: null,
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.body).not.toContain('Request code');
+  });
+
+  test('includes trusted-contact member reference when requesterMemberId is present', () => {
+    const signal = buildSignal({
+      callerName: 'Diana',
+      callerPhoneNumber: '+15552222222',
+      requesterMemberId: 'member-789',
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.body).toContain('trusted contact');
+    expect(copy.body).toContain('member-789');
+  });
+
+  test('omits member reference line when requesterMemberId is null', () => {
+    const signal = buildSignal({
+      callerName: 'Eve',
+      callerPhoneNumber: '+15553333333',
+      requesterMemberId: null,
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.body).not.toContain('trusted contact');
+    expect(copy.body).not.toContain('member');
+  });
+
+  test('telegram channel gets deliveryText fallback', () => {
+    const signal = buildSignal({
+      callerName: 'Frank',
+      callerPhoneNumber: '+15554444444',
+    });
+    const result = composeFallbackCopy(signal, ['telegram']);
+    const copy = result.telegram!;
+
+    expect(copy.deliveryText).toBeDefined();
+    expect(copy.deliveryText!.length).toBeGreaterThan(0);
+    expect(copy.deliveryText).toContain('Frank');
+  });
+
+  test('sms channel gets deliveryText fallback', () => {
+    const signal = buildSignal({
+      callerName: 'Grace',
+      callerPhoneNumber: '+15555555555',
+    });
+    const result = composeFallbackCopy(signal, ['sms']);
+    const copy = result.sms!;
+
+    expect(copy.deliveryText).toBeDefined();
+    expect(copy.deliveryText!.length).toBeGreaterThan(0);
+  });
+
+  test('full payload renders all fields correctly', () => {
+    const signal = buildSignal({
+      callerName: 'Hank',
+      callerPhoneNumber: '+15556666666',
+      requestCode: 'ff00aa',
+      requesterMemberId: 'member-full-test',
+    });
+    const result = composeFallbackCopy(signal, ['vellum']);
+    const copy = result.vellum!;
+
+    expect(copy.title).toBe('Callback Requested');
+    expect(copy.body).toContain('Hank (+15556666666)');
+    expect(copy.body).toContain('FF00AA');
+    expect(copy.body).toContain('member-full-test');
+    expect(copy.body).toContain('callback');
+    expect(copy.body).toContain('unreachable');
+  });
+});