@vellumai/assistant 0.4.2 → 0.4.4

package/src/__tests__/guardian-question-mode.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  buildGuardianCodeOnlyClarification,
+  buildGuardianDisambiguationExample,
+  buildGuardianDisambiguationLabel,
+  buildGuardianInvalidActionReply,
+  buildGuardianReplyDirective,
+  buildGuardianRequestCodeInstruction,
+  hasGuardianRequestCodeInstruction,
+  parseGuardianQuestionPayload,
+  resolveGuardianInstructionModeForRequest,
+  resolveGuardianInstructionModeFromFields,
+  resolveGuardianQuestionInstructionMode,
+  stripConflictingGuardianRequestInstructions,
+} from '../notifications/guardian-question-mode.js';
+
+describe('guardian-question-mode', () => {
+  test('parses pending_question payload as discriminated union', () => {
+    const parsed = parseGuardianQuestionPayload({
+      requestKind: 'pending_question',
+      requestId: 'req-1',
+      requestCode: 'A1B2C3',
+      questionText: 'What time works?',
+      callSessionId: 'call-1',
+      activeGuardianRequestCount: 2,
+    });
+
+    expect(parsed).not.toBeNull();
+    expect(parsed?.requestKind).toBe('pending_question');
+    if (!parsed || parsed.requestKind !== 'pending_question') return;
+    expect(parsed.callSessionId).toBe('call-1');
+    expect(parsed.activeGuardianRequestCount).toBe(2);
+  });
+
+  test('parses tool_grant_request payload and requires toolName', () => {
+    const parsed = parseGuardianQuestionPayload({
+      requestKind: 'tool_grant_request',
+      requestId: 'req-2',
+      requestCode: 'D4E5F6',
+      questionText: 'Allow host bash?',
+      toolName: 'host_bash',
+    });
+
+    expect(parsed).not.toBeNull();
+    expect(parsed?.requestKind).toBe('tool_grant_request');
+    if (!parsed || parsed.requestKind !== 'tool_grant_request') return;
+    expect(parsed.toolName).toBe('host_bash');
+  });
+
+  test('parses pending_question payload with optional toolName metadata', () => {
+    const parsed = parseGuardianQuestionPayload({
+      requestKind: 'pending_question',
+      requestId: 'req-voice-tool-1',
+      requestCode: 'AA11BB',
+      questionText: 'Allow send_email?',
+      callSessionId: 'call-voice-1',
+      activeGuardianRequestCount: 1,
+      toolName: 'send_email',
+    });
+
+    expect(parsed).not.toBeNull();
+    expect(parsed?.requestKind).toBe('pending_question');
+    if (!parsed || parsed.requestKind !== 'pending_question') return;
+    expect(parsed.toolName).toBe('send_email');
+  });
+
+  test('rejects invalid pending_question payload missing required fields', () => {
+    const parsed = parseGuardianQuestionPayload({
+      requestKind: 'pending_question',
+      requestId: 'req-3',
+      requestCode: 'AAA111',
+      questionText: 'Missing call session and count',
+    });
+    expect(parsed).toBeNull();
+  });
+
+  test('resolve mode uses discriminant for valid typed payloads', () => {
+    const resolved = resolveGuardianQuestionInstructionMode({
+      requestKind: 'pending_question',
+      requestId: 'req-1',
+      requestCode: 'A1B2C3',
+      questionText: 'What time works?',
+      callSessionId: 'call-1',
+      activeGuardianRequestCount: 2,
+    });
+
+    expect(resolved.mode).toBe('answer');
+    expect(resolved.requestKind).toBe('pending_question');
+    expect(resolved.legacyFallbackUsed).toBe(false);
+  });
+
+  test('resolve mode uses legacy fallback when requestKind is missing', () => {
+    const resolved = resolveGuardianQuestionInstructionMode({
+      requestCode: 'A1B2C3',
+      questionText: 'Allow host bash?',
+      toolName: 'host_bash',
+    });
+
+    expect(resolved.mode).toBe('approval');
+    expect(resolved.requestKind).toBeNull();
+    expect(resolved.legacyFallbackUsed).toBe(true);
+  });
+
+  test('resolve mode treats pending_question with toolName as approval-mode', () => {
+    const resolved = resolveGuardianQuestionInstructionMode({
+      requestKind: 'pending_question',
+      requestId: 'req-voice-tool-2',
+      requestCode: 'CC22DD',
+      questionText: 'Allow send_email?',
+      callSessionId: 'call-voice-2',
+      activeGuardianRequestCount: 1,
+      toolName: 'send_email',
+    });
+
+    expect(resolved.mode).toBe('approval');
+    expect(resolved.requestKind).toBe('pending_question');
+    expect(resolved.legacyFallbackUsed).toBe(false);
+  });
+
+  test('resolveGuardianInstructionModeFromFields returns null for unknown request kind', () => {
+    const resolved = resolveGuardianInstructionModeFromFields('unknown_kind', 'send_email');
+    expect(resolved).toBeNull();
+  });
+
+  test('answer-mode instruction detection rejects approval phrasing', () => {
+    const code = 'A1B2C3';
+    const wrongInstruction = buildGuardianRequestCodeInstruction(code, 'approval');
+    const correctInstruction = buildGuardianRequestCodeInstruction(code, 'answer');
+
+    expect(hasGuardianRequestCodeInstruction(wrongInstruction, code, 'answer')).toBe(false);
+    expect(hasGuardianRequestCodeInstruction(correctInstruction, code, 'answer')).toBe(true);
+  });
+
+  test('buildGuardianReplyDirective uses mode-specific wording', () => {
+    expect(buildGuardianReplyDirective('A1B2C3', 'approval')).toBe('Reply "A1B2C3 approve" or "A1B2C3 reject".');
+    expect(buildGuardianReplyDirective('A1B2C3', 'answer')).toBe('Reply "A1B2C3 <your answer>".');
+  });
+
+  test('resolveGuardianInstructionModeForRequest handles tool-backed pending_question as approval', () => {
+    expect(
+      resolveGuardianInstructionModeForRequest({
+        kind: 'pending_question',
+        toolName: 'send_email',
+      }),
+    ).toBe('approval');
+    expect(
+      resolveGuardianInstructionModeForRequest({
+        kind: 'pending_question',
+        toolName: null,
+      }),
+    ).toBe('answer');
+  });
+
+  test('centralized guardian response copy builders produce mode-specific copy', () => {
+    expect(buildGuardianInvalidActionReply('approval', 'A1B2C3')).toContain('approve');
+    expect(buildGuardianInvalidActionReply('answer', 'A1B2C3')).toContain('<your answer>');
+
+    expect(
+      buildGuardianCodeOnlyClarification('approval', {
+        requestCode: 'A1B2C3',
+        questionText: 'Allow send_email to bob@example.com?',
+        toolName: 'send_email',
+      }),
+    ).toContain('I found request A1B2C3 for send_email.');
+    expect(
+      buildGuardianCodeOnlyClarification('answer', {
+        requestCode: 'A1B2C3',
+        questionText: 'What time works best?',
+      }),
+    ).toContain('I found question A1B2C3.');
+
+    expect(
+      buildGuardianDisambiguationLabel('approval', {
+        questionText: 'Allow send_email to bob@example.com?',
+        toolName: 'send_email',
+      }),
+    ).toBe('send_email');
+    expect(
+      buildGuardianDisambiguationLabel('answer', {
+        questionText: 'What time works best?',
+      }),
+    ).toBe('What time works best?');
+
+    expect(buildGuardianDisambiguationExample('approval', 'A1B2C3')).toBe(
+      'For approvals: reply "A1B2C3 approve" or "A1B2C3 reject".',
+    );
+    expect(buildGuardianDisambiguationExample('answer', 'A1B2C3')).toBe(
+      'For questions: reply "A1B2C3 <your answer>".',
+    );
+  });
+
+  test('stripConflictingGuardianRequestInstructions removes opposite-mode instructions', () => {
+    const approvalText = 'Reference code: A1B2C3. Reply "A1B2C3 approve" or "A1B2C3 reject".';
+    const answerText = 'Reference code: A1B2C3. Reply "A1B2C3 <your answer>".';
+
+    expect(stripConflictingGuardianRequestInstructions(approvalText, 'A1B2C3', 'answer')).toBe('');
+    expect(stripConflictingGuardianRequestInstructions(answerText, 'A1B2C3', 'approval')).toBe('');
+  });
+});

package/src/__tests__/guardian-routing-invariants.test.ts

@@ -475,6 +475,69 @@ describe('routing invariant: code-only messages return clarification', () => {
     expect(unchanged!.status).toBe('pending');
   });
 
+  test('code-only pending_question asks for free-text answer (not approve/reject)', async () => {
+    const req = createCanonicalGuardianRequest({
+      kind: 'pending_question',
+      sourceType: 'voice',
+      sourceChannel: 'voice',
+      conversationId: 'conv-1',
+      guardianExternalUserId: 'guardian-1',
+      callSessionId: 'call-1',
+      pendingQuestionId: 'pq-1',
+      requestCode: 'A2B3C4',
+      questionText: 'What time works best?',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const result = await routeGuardianReply(replyCtx({
+      messageText: 'A2B3C4',
+      conversationId: 'conv-1',
+    }));
+
+    expect(result.consumed).toBe(true);
+    expect(result.type).toBe('code_only_clarification');
+    expect(result.decisionApplied).toBe(false);
+    expect(result.replyText).toContain('A2B3C4');
+    expect(result.replyText).toContain('<your answer>');
+    expect(result.replyText).not.toContain('approve');
+    expect(result.replyText).not.toContain('reject');
+
+    const unchanged = getCanonicalGuardianRequest(req.id);
+    expect(unchanged!.status).toBe('pending');
+  });
+
+  test('code-only tool-backed pending_question asks for approve/reject decision', async () => {
+    const req = createCanonicalGuardianRequest({
+      kind: 'pending_question',
+      sourceType: 'voice',
+      sourceChannel: 'voice',
+      conversationId: 'conv-1',
+      guardianExternalUserId: 'guardian-1',
+      callSessionId: 'call-2',
+      pendingQuestionId: 'pq-2',
+      requestCode: 'B2C3D4',
+      questionText: 'Allow send_email to bob@example.com?',
+      toolName: 'send_email',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const result = await routeGuardianReply(replyCtx({
+      messageText: 'B2C3D4',
+      conversationId: 'conv-1',
+    }));
+
+    expect(result.consumed).toBe(true);
+    expect(result.type).toBe('code_only_clarification');
+    expect(result.decisionApplied).toBe(false);
+    expect(result.replyText).toContain('B2C3D4');
+    expect(result.replyText).toContain('approve');
+    expect(result.replyText).toContain('reject');
+    expect(result.replyText).not.toContain('<your answer>');
+
+    const unchanged = getCanonicalGuardianRequest(req.id);
+    expect(unchanged!.status).toBe('pending');
+  });
+
   test('code with decision text does apply the decision', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
@@ -701,6 +764,51 @@ describe('routing invariant: disambiguation stays fail-closed', () => {
     expect(result.replyText).toContain('BBB222');
   });
 
+  test('disambiguation treats tool-backed pending_question as approval request', async () => {
+    const answerRequest = createCanonicalGuardianRequest({
+      kind: 'pending_question',
+      sourceType: 'voice',
+      sourceChannel: 'voice',
+      conversationId: 'conv-1',
+      guardianExternalUserId: 'guardian-1',
+      callSessionId: 'call-answer',
+      pendingQuestionId: 'pq-answer',
+      requestCode: 'ABC123',
+      questionText: 'What time works best?',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const approvalRequest = createCanonicalGuardianRequest({
+      kind: 'pending_question',
+      sourceType: 'voice',
+      sourceChannel: 'voice',
+      conversationId: 'conv-1',
+      guardianExternalUserId: 'guardian-1',
+      callSessionId: 'call-approval',
+      pendingQuestionId: 'pq-approval',
+      requestCode: 'DEF456',
+      questionText: 'Allow send_email to bob@example.com?',
+      toolName: 'send_email',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const result = await routeGuardianReply(replyCtx({
+      messageText: 'approve',
+      conversationId: 'conv-guardian-thread',
+      pendingRequestIds: [answerRequest.id, approvalRequest.id],
+      approvalConversationGenerator: undefined,
+    }));
+
+    expect(result.consumed).toBe(true);
+    expect(result.type).toBe('disambiguation_needed');
+    expect(result.decisionApplied).toBe(false);
+    expect(result.replyText).toContain('ABC123');
+    expect(result.replyText).toContain('DEF456');
+    expect(result.replyText).toContain('send_email');
+    expect(result.replyText).toContain('For questions: reply "ABC123 <your answer>".');
+    expect(result.replyText).toContain('For approvals: reply "DEF456 approve" or "DEF456 reject".');
+  });
+
   test('single pending request does not need disambiguation', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
@@ -1130,4 +1238,74 @@ describe('routing invariant: invite handoff bypass for access requests', () => {
     const resolved = getCanonicalGuardianRequest(req.id);
     expect(resolved!.status).toBe('approved');
   });
+
+  test('trusted desktop access-request approval returns a verification code reply', async () => {
+    const req = createCanonicalGuardianRequest({
+      kind: 'access_request',
+      sourceType: 'channel',
+      sourceChannel: 'telegram',
+      conversationId: 'conv-access-desktop',
+      guardianExternalUserId: 'guardian-1',
+      requestCode: 'C0D3A5',
+      toolName: 'ingress_access_request',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const result = await routeGuardianReply({
+      messageText: 'C0D3A5 approve',
+      channel: 'vellum',
+      actor: trustedActor({ channel: 'vellum' }),
+      conversationId: 'conv-guardian-thread',
+      pendingRequestIds: [req.id],
+      approvalConversationGenerator: undefined,
+    });
+
+    expect(result.consumed).toBe(true);
+    expect(result.decisionApplied).toBe(true);
+    expect(result.replyText).toContain('verification code');
+    expect(result.replyText).toMatch(/\b\d{6}\b/);
+
+    const resolved = getCanonicalGuardianRequest(req.id);
+    expect(resolved!.status).toBe('approved');
+  });
+
+  test('NL decision path preserves resolver verification code reply text', async () => {
+    const req = createCanonicalGuardianRequest({
+      kind: 'access_request',
+      sourceType: 'channel',
+      sourceChannel: 'telegram',
+      conversationId: 'conv-access-desktop-nl',
+      guardianExternalUserId: 'guardian-1',
+      requesterExternalUserId: 'requester-1',
+      requesterChatId: 'chat-1',
+      requestCode: 'A1B2C3',
+      toolName: 'ingress_access_request',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const approvalConversationGenerator = async () => ({
+      disposition: 'approve_once' as const,
+      replyText: 'Access approved.',
+      targetRequestId: req.id,
+    });
+
+    const result = await routeGuardianReply({
+      messageText: 'please approve this request',
+      channel: 'vellum',
+      actor: trustedActor({ channel: 'vellum' }),
+      conversationId: 'conv-guardian-thread',
+      pendingRequestIds: [req.id],
+      approvalConversationGenerator: approvalConversationGenerator as any,
+    });
+
+    expect(result.consumed).toBe(true);
+    expect(result.decisionApplied).toBe(true);
+    expect(result.type).toBe('canonical_decision_applied');
+    expect(result.replyText).toContain('verification code');
+    expect(result.replyText).toMatch(/\b\d{6}\b/);
+    expect(result.replyText).not.toBe('Access approved.');
+
+    const resolved = getCanonicalGuardianRequest(req.id);
+    expect(resolved!.status).toBe('approved');
+  });
 });