@vellumai/assistant 0.3.19 → 0.3.21

package/src/__tests__/guardian-action-late-reply.test.ts

@@ -29,7 +29,8 @@ mock.module('../runtime/gateway-client.js', () => ({
   deliverChannelReply: async () => {},
 }));
 
-import { createCallSession, createPendingQuestion } from '../calls/call-store.js';
+import { isTerminalState } from '../calls/call-state-machine.js';
+import { createCallSession, createPendingQuestion, getCallSession, updateCallSession } from '../calls/call-store.js';
 import { getDb, initializeDb, resetDb } from '../memory/db.js';
 import {
   createGuardianActionDelivery,
@@ -41,8 +42,10 @@ import {
   getFollowupDeliveriesByConversation,
   getGuardianActionRequest,
   getPendingDeliveriesByConversation,
+  getPendingRequestByCallSessionId,
   resolveGuardianActionRequest,
   startFollowupFromExpiredRequest,
+  supersedeGuardianActionRequest,
   updateDeliveryStatus,
 } from '../memory/guardian-action-store.js';
 import { conversations } from '../memory/schema.js';
@@ -422,4 +425,546 @@ describe('guardian-action-late-reply', () => {
       expect(answerText).toBe('the answer is 42');
     });
   });
+
+  // ── Superseded late-approval remap semantics ──────────────────────
+
+  describe('superseded late-approval remap', () => {
+    /**
+     * Helper: create two guardian action requests on the same call session.
+     * The first is superseded by the second (which stays pending).
+     * Returns the superseded request, the current pending request, and the call session.
+     */
+    function createSupersededScenario(convId: string, opts?: { chatId?: string; externalUserId?: string; conversationId?: string }) {
+      ensureConversation(convId);
+      const session = createCallSession({
+        conversationId: convId,
+        provider: 'twilio',
+        fromNumber: '+15550001111',
+        toNumber: '+15550002222',
+      });
+      // Keep call in 'initiated' status (non-terminal) — simulates active call
+      const pqOld = createPendingQuestion(session.id, 'What is the old gate code?');
+      const oldRequest = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: convId,
+        callSessionId: session.id,
+        pendingQuestionId: pqOld.id,
+        questionText: pqOld.questionText,
+        expiresAt: Date.now() + 60_000,
+        toolName: 'check_gate',
+        inputDigest: 'digest-old',
+      });
+
+      // Create delivery for the old request
+      const deliveryConvId = opts?.conversationId ?? `delivery-conv-${oldRequest.id}`;
+      if (opts?.conversationId) {
+        ensureConversation(opts.conversationId);
+      } else {
+        ensureConversation(deliveryConvId);
+      }
+      const oldDelivery = createGuardianActionDelivery({
+        requestId: oldRequest.id,
+        destinationChannel: 'telegram',
+        destinationChatId: opts?.chatId ?? 'chat-123',
+        destinationExternalUserId: opts?.externalUserId ?? 'user-456',
+        destinationConversationId: deliveryConvId,
+      });
+      updateDeliveryStatus(oldDelivery.id, 'sent');
+
+      // Create the new (current) pending request
+      const pqNew = createPendingQuestion(session.id, 'What is the new gate code?');
+      const newRequest = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: convId,
+        callSessionId: session.id,
+        pendingQuestionId: pqNew.id,
+        questionText: pqNew.questionText,
+        expiresAt: Date.now() + 60_000,
+        toolName: 'check_gate',
+        inputDigest: 'digest-new',
+      });
+
+      // Supersede the old request
+      supersedeGuardianActionRequest(oldRequest.id, newRequest.id);
+
+      return {
+        session,
+        supersededRequest: getGuardianActionRequest(oldRequest.id)!,
+        currentRequest: getGuardianActionRequest(newRequest.id)!,
+        oldDelivery,
+        deliveryConvId,
+      };
+    }
+
+    test('superseded request has expired_reason=superseded and links to replacement', () => {
+      const { supersededRequest, currentRequest } = createSupersededScenario('conv-supersede-1');
+
+      expect(supersededRequest.status).toBe('expired');
+      expect(supersededRequest.expiredReason).toBe('superseded');
+      expect(supersededRequest.supersededByRequestId).toBe(currentRequest.id);
+      expect(currentRequest.status).toBe('pending');
+    });
+
+    test('superseded request with active call and pending request is remap-eligible', () => {
+      const { session, supersededRequest, currentRequest } = createSupersededScenario('conv-supersede-2');
+
+      // Call should still be active (non-terminal)
+      const callSession = getCallSession(session.id);
+      expect(callSession).not.toBeNull();
+      expect(isTerminalState(callSession!.status)).toBe(false);
+
+      // Should find current pending request for the same call session
+      const pending = getPendingRequestByCallSessionId(supersededRequest.callSessionId);
+      expect(pending).not.toBeNull();
+      expect(pending!.id).toBe(currentRequest.id);
+
+      // The superseded request is expired with reason 'superseded' and followup_state 'none'
+      expect(supersededRequest.expiredReason).toBe('superseded');
+      expect(supersededRequest.followupState).toBe('none');
+    });
+
+    test('superseded request with completed call is NOT remap-eligible — falls through to follow-up', () => {
+      const { session, supersededRequest } = createSupersededScenario('conv-supersede-3');
+
+      // Transition the call to a terminal state
+      updateCallSession(session.id, { status: 'in_progress' });
+      updateCallSession(session.id, { status: 'completed', endedAt: Date.now() });
+
+      // Call is now terminal
+      const callSession = getCallSession(session.id);
+      expect(callSession).not.toBeNull();
+      expect(isTerminalState(callSession!.status)).toBe(true);
+
+      // Even though expired_reason is 'superseded', the remap should not apply
+      // because the call has ended. The follow-up path should be used instead.
+      expect(supersededRequest.expiredReason).toBe('superseded');
+    });
+
+    test('timeout-expired request is NOT remap-eligible even with active call', () => {
+      const convId = 'conv-timeout-no-remap';
+      ensureConversation(convId);
+      const session = createCallSession({
+        conversationId: convId,
+        provider: 'twilio',
+        fromNumber: '+15550001111',
+        toNumber: '+15550002222',
+      });
+
+      const pq = createPendingQuestion(session.id, 'What is the code?');
+      const request = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: convId,
+        callSessionId: session.id,
+        pendingQuestionId: pq.id,
+        questionText: pq.questionText,
+        expiresAt: Date.now() - 10_000,
+      });
+
+      const deliveryConvId = `delivery-conv-${request.id}`;
+      ensureConversation(deliveryConvId);
+      const delivery = createGuardianActionDelivery({
+        requestId: request.id,
+        destinationChannel: 'telegram',
+        destinationChatId: 'chat-timeout',
+        destinationExternalUserId: 'user-timeout',
+        destinationConversationId: deliveryConvId,
+      });
+      updateDeliveryStatus(delivery.id, 'sent');
+
+      // Expire with sweep_timeout (NOT superseded)
+      expireGuardianActionRequest(request.id, 'sweep_timeout');
+
+      const expired = getGuardianActionRequest(request.id)!;
+      expect(expired.expiredReason).toBe('sweep_timeout');
+
+      // Even if the call is active, this should follow the callback/message path
+      // because it's a real timeout, not a supersession
+      const callSession = getCallSession(session.id);
+      expect(callSession).not.toBeNull();
+      expect(isTerminalState(callSession!.status)).toBe(false);
+
+      // startFollowupFromExpiredRequest should work normally for timeouts
+      const followup = startFollowupFromExpiredRequest(request.id, 'late answer');
+      expect(followup).not.toBeNull();
+      expect(followup!.followupState).toBe('awaiting_guardian_choice');
+    });
+
+    test('call_timeout-expired request is NOT remap-eligible', () => {
+      const convId = 'conv-call-timeout-no-remap';
+      ensureConversation(convId);
+      const session = createCallSession({
+        conversationId: convId,
+        provider: 'twilio',
+        fromNumber: '+15550001111',
+        toNumber: '+15550002222',
+      });
+
+      const pq = createPendingQuestion(session.id, 'What is the code?');
+      const request = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: convId,
+        callSessionId: session.id,
+        pendingQuestionId: pq.id,
+        questionText: pq.questionText,
+        expiresAt: Date.now() - 10_000,
+      });
+
+      const deliveryConvId = `delivery-conv-${request.id}`;
+      ensureConversation(deliveryConvId);
+      const delivery = createGuardianActionDelivery({
+        requestId: request.id,
+        destinationChannel: 'telegram',
+        destinationChatId: 'chat-call-timeout',
+        destinationExternalUserId: 'user-call-timeout',
+        destinationConversationId: deliveryConvId,
+      });
+      updateDeliveryStatus(delivery.id, 'sent');
+
+      // Expire with call_timeout (NOT superseded)
+      expireGuardianActionRequest(request.id, 'call_timeout');
+
+      const expired = getGuardianActionRequest(request.id)!;
+      expect(expired.expiredReason).toBe('call_timeout');
+
+      // call_timeout should follow the callback/message path regardless
+      const followup = startFollowupFromExpiredRequest(request.id, 'late answer for timeout');
+      expect(followup).not.toBeNull();
+      expect(followup!.followupState).toBe('awaiting_guardian_choice');
+    });
+
+    test('superseded request with no pending replacement falls through to follow-up', () => {
+      const { supersededRequest, currentRequest } = createSupersededScenario('conv-supersede-no-pending');
+
+      // Resolve the current pending request so there's no pending replacement
+      resolveGuardianActionRequest(currentRequest.id, 'answered already', 'telegram');
+
+      // No pending request for this call session anymore
+      const pending = getPendingRequestByCallSessionId(supersededRequest.callSessionId);
+      expect(pending).toBeNull();
+
+      // The superseded request should fall through to follow-up since
+      // there's no pending request to remap to
+      const followup = startFollowupFromExpiredRequest(supersededRequest.id, 'late answer');
+      expect(followup).not.toBeNull();
+      expect(followup!.followupState).toBe('awaiting_guardian_choice');
+    });
+
+    test('composeGuardianActionMessageGenerative produces remap text for superseded scenario', async () => {
+      const { composeGuardianActionMessageGenerative } = await import('../runtime/guardian-action-message-composer.js');
+
+      const text = await composeGuardianActionMessageGenerative({
+        scenario: 'guardian_superseded_remap',
+        questionText: 'What is the new gate code?',
+      });
+
+      // In test mode, the deterministic fallback is used
+      expect(text).toContain('current active request');
+      expect(text).toContain('What is the new gate code?');
+    });
+
+    test('composeGuardianActionMessageGenerative produces remap text without question', async () => {
+      const { composeGuardianActionMessageGenerative } = await import('../runtime/guardian-action-message-composer.js');
+
+      const text = await composeGuardianActionMessageGenerative({
+        scenario: 'guardian_superseded_remap',
+      });
+
+      expect(text).toContain('current active request');
+    });
+  });
+
+  // ── Disambiguation hardening across states ──────────────────────────
+
+  describe('disambiguation hardening across states', () => {
+    // Helper to create a pending request with delivery in a shared conversation
+    function createPendingInSharedConv(sourceConvId: string, sharedDeliveryConvId: string, opts?: { chatId?: string; externalUserId?: string }) {
+      ensureConversation(sourceConvId);
+      const session = createCallSession({
+        conversationId: sourceConvId,
+        provider: 'twilio',
+        fromNumber: '+15550001111',
+        toNumber: '+15550002222',
+      });
+      const pq = createPendingQuestion(session.id, `Question from ${sourceConvId}`);
+      const request = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: sourceConvId,
+        callSessionId: session.id,
+        pendingQuestionId: pq.id,
+        questionText: pq.questionText,
+        expiresAt: Date.now() + 60_000,
+      });
+      const delivery = createGuardianActionDelivery({
+        requestId: request.id,
+        destinationChannel: 'telegram',
+        destinationChatId: opts?.chatId ?? 'chat-disambig',
+        destinationExternalUserId: opts?.externalUserId ?? 'user-disambig',
+        destinationConversationId: sharedDeliveryConvId,
+      });
+      updateDeliveryStatus(delivery.id, 'sent');
+      return { request: getGuardianActionRequest(request.id)!, delivery, session };
+    }
+
+    test('single pending request auto-matches without code prefix', () => {
+      // When there is only ONE pending request and no expired/follow-up,
+      // the guardian's message should auto-match without needing a code prefix.
+      const sharedConv = 'shared-auto-match-single';
+      ensureConversation(sharedConv);
+      const { request } = createPendingInSharedConv('src-auto-1', sharedConv);
+
+      // There should be exactly one pending delivery
+      const pending = getPendingDeliveriesByConversation(sharedConv);
+      expect(pending).toHaveLength(1);
+
+      // No expired or follow-up deliveries
+      const expired = getExpiredDeliveriesByConversation(sharedConv);
+      const followup = getFollowupDeliveriesByConversation(sharedConv);
+      expect(expired).toHaveLength(0);
+      expect(followup).toHaveLength(0);
+
+      // Total actionable is 1, so auto-match should apply
+      const totalActionable = pending.length + expired.length + followup.length;
+      expect(totalActionable).toBe(1);
+
+      // The request is pending and ready for direct answer
+      expect(request.status).toBe('pending');
+    });
+
+    test('multiple pending requests requires disambiguation', () => {
+      // When multiple pending requests exist, the guardian must prefix with a code.
+      const sharedConv = 'shared-multi-pending-disambig';
+      ensureConversation(sharedConv);
+      const { request: req1 } = createPendingInSharedConv('src-mp1', sharedConv);
+      const { request: req2 } = createPendingInSharedConv('src-mp2', sharedConv);
+
+      const pending = getPendingDeliveriesByConversation(sharedConv);
+      expect(pending).toHaveLength(2);
+
+      // Both have unique codes
+      expect(req1.requestCode).not.toBe(req2.requestCode);
+
+      // Content without a valid code prefix should require disambiguation
+      const testContent = 'just a plain answer';
+      const upperContent = testContent.toUpperCase();
+      const matchesPending = pending.some((d) => {
+        const req = getGuardianActionRequest(d.requestId);
+        return req && upperContent.startsWith(req.requestCode);
+      });
+      expect(matchesPending).toBe(false);
+
+      // Content with a valid code prefix should match
+      const prefixedContent = `${req1.requestCode} the answer is 42`;
+      const upperPrefixed = prefixedContent.toUpperCase();
+      const matchesPrefixed = pending.some((d) => {
+        const req = getGuardianActionRequest(d.requestId);
+        return req && upperPrefixed.startsWith(req.requestCode);
+      });
+      expect(matchesPrefixed).toBe(true);
+    });
+
+    test('explicit code to superseded request with active call remaps with explanation', async () => {
+      // When a guardian uses a code for a superseded request and the call is
+      // still active with a current pending request, the system should remap.
+      const convId = 'conv-remap-with-code';
+      ensureConversation(convId);
+      const session = createCallSession({
+        conversationId: convId,
+        provider: 'twilio',
+        fromNumber: '+15550001111',
+        toNumber: '+15550002222',
+      });
+      const pqOld = createPendingQuestion(session.id, 'Old question?');
+      const oldRequest = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: convId,
+        callSessionId: session.id,
+        pendingQuestionId: pqOld.id,
+        questionText: pqOld.questionText,
+        expiresAt: Date.now() + 60_000,
+        toolName: 'check_gate',
+        inputDigest: 'digest-old-code',
+      });
+
+      const deliveryConvId = 'delivery-remap-code';
+      ensureConversation(deliveryConvId);
+      const oldDelivery = createGuardianActionDelivery({
+        requestId: oldRequest.id,
+        destinationChannel: 'telegram',
+        destinationChatId: 'chat-remap-code',
+        destinationExternalUserId: 'user-remap-code',
+        destinationConversationId: deliveryConvId,
+      });
+      updateDeliveryStatus(oldDelivery.id, 'sent');
+
+      // Create new pending request that supersedes the old one
+      const pqNew = createPendingQuestion(session.id, 'New question?');
+      const newRequest = createGuardianActionRequest({
+        kind: 'ask_guardian',
+        sourceChannel: 'voice',
+        sourceConversationId: convId,
+        callSessionId: session.id,
+        pendingQuestionId: pqNew.id,
+        questionText: pqNew.questionText,
+        expiresAt: Date.now() + 60_000,
+        toolName: 'check_gate',
+        inputDigest: 'digest-new-code',
+      });
+      supersedeGuardianActionRequest(oldRequest.id, newRequest.id);
+
+      // Verify the old request is superseded and the call is active
+      const superseded = getGuardianActionRequest(oldRequest.id)!;
+      expect(superseded.status).toBe('expired');
+      expect(superseded.expiredReason).toBe('superseded');
+
+      const callSession = getCallSession(session.id);
+      expect(isTerminalState(callSession!.status)).toBe(false);
+
+      // There should be a pending request for this call session (the new one)
+      const currentPending = getPendingRequestByCallSessionId(session.id);
+      expect(currentPending).not.toBeNull();
+      expect(currentPending!.id).toBe(newRequest.id);
+
+      // Compose the remap message
+      const { composeGuardianActionMessageGenerative } = await import('../runtime/guardian-action-message-composer.js');
+      const remapText = await composeGuardianActionMessageGenerative({
+        scenario: 'guardian_superseded_remap',
+        questionText: currentPending!.questionText,
+      });
+      expect(remapText).toContain('current active request');
+      expect(remapText).toContain('New question?');
+    });
+
+    test('explicit code to expired/timeout request returns terminal notice', async () => {
+      // When a guardian uses a code for a timed-out expired request,
+      // the system should follow the normal expired path (follow-up or stale).
+      const { request } = createExpiredRequest('conv-expired-terminal', {
+        chatId: 'chat-expired-term',
+        externalUserId: 'user-expired-term',
+      });
+
+      expect(request.status).toBe('expired');
+      expect(request.expiredReason).toBe('sweep_timeout');
+
+      // When a follow-up can't be started (e.g. already handled), a stale notice is returned
+      startFollowupFromExpiredRequest(request.id, 'first answer');
+      const secondAttempt = startFollowupFromExpiredRequest(request.id, 'second answer');
+      expect(secondAttempt).toBeNull();
+
+      // The stale message should be a terminal notice
+      const { composeGuardianActionMessageGenerative } = await import('../runtime/guardian-action-message-composer.js');
+      const staleText = await composeGuardianActionMessageGenerative({
+        scenario: 'guardian_stale_expired',
+      });
+      expect(staleText).toContain('expired');
+      expect(staleText).toContain('No further action');
+    });
+
+    test('unknown code returns clear error message instead of loop', async () => {
+      // When a guardian provides a code that doesn't match any known request,
+      // the system should return a clear "unknown code" message.
+      const { composeGuardianActionMessageGenerative } = await import('../runtime/guardian-action-message-composer.js');
+
+      const unknownText = await composeGuardianActionMessageGenerative({
+        scenario: 'guardian_unknown_code',
+        unknownCode: 'XYZ999',
+      });
+
+      expect(unknownText).toContain('XYZ999');
+      expect(unknownText).toContain("don't recognize");
+      // Should NOT ask to prefix with code — that would create a loop
+      expect(unknownText).not.toContain('prefix your reply');
+    });
+
+    test('priority order: pending is matched before follow-up before expired', () => {
+      // Create deliveries in all three states in a shared conversation
+      const sharedConv = 'shared-priority-order';
+      ensureConversation(sharedConv);
+
+      // Create a pending request
+      const { request: pendingReq } = createPendingInSharedConv('src-prio-pending', sharedConv);
+
+      // Create an expired request
+      const { request: expReq } = createPendingInSharedConv('src-prio-expired', sharedConv);
+      expireGuardianActionRequest(expReq.id, 'sweep_timeout');
+
+      // Create a follow-up request (expired then started follow-up)
+      const { request: fuReq } = createPendingInSharedConv('src-prio-followup', sharedConv);
+      expireGuardianActionRequest(fuReq.id, 'sweep_timeout');
+      startFollowupFromExpiredRequest(fuReq.id, 'late answer');
+
+      // Gather all deliveries
+      const pending = getPendingDeliveriesByConversation(sharedConv);
+      const followup = getFollowupDeliveriesByConversation(sharedConv);
+      const expired = getExpiredDeliveriesByConversation(sharedConv);
+
+      expect(pending.length).toBeGreaterThan(0);
+      expect(followup.length).toBeGreaterThan(0);
+      expect(expired.length).toBeGreaterThan(0);
+
+      // Simulate the priority matching order from the unified handler:
+      // pending → follow-up → expired
+      const orderedSets = [
+        { deliveries: pending, state: 'pending' },
+        { deliveries: followup, state: 'followup' },
+        { deliveries: expired, state: 'expired' },
+      ];
+
+      // When prefixed with the pending request's code, it should match pending first
+      const pendingCode = pendingReq.requestCode;
+      const pendingMessage = `${pendingCode} approve`;
+      let matchedState: string | null = null;
+      for (const { deliveries, state } of orderedSets) {
+        for (const d of deliveries) {
+          const req = getGuardianActionRequest(d.requestId);
+          if (req && pendingMessage.toUpperCase().startsWith(req.requestCode)) {
+            matchedState = state;
+            break;
+          }
+        }
+        if (matchedState) break;
+      }
+      expect(matchedState).toBe('pending');
+
+      // When prefixed with the follow-up request's code, it should match follow-up
+      // (because the pending check won't match that code)
+      const fuRequest = getGuardianActionRequest(fuReq.id)!;
+      const fuCode = fuRequest.requestCode;
+      const fuMessage = `${fuCode} call back`;
+      matchedState = null;
+      for (const { deliveries, state } of orderedSets) {
+        for (const d of deliveries) {
+          const req = getGuardianActionRequest(d.requestId);
+          if (req && fuMessage.toUpperCase().startsWith(req.requestCode)) {
+            matchedState = state;
+            break;
+          }
+        }
+        if (matchedState) break;
+      }
+      expect(matchedState).toBe('followup');
+
+      // When prefixed with the expired request's code, it should match expired
+      const expRequest = getGuardianActionRequest(expReq.id)!;
+      const expCode = expRequest.requestCode;
+      const expMessage = `${expCode} yes`;
+      matchedState = null;
+      for (const { deliveries, state } of orderedSets) {
+        for (const d of deliveries) {
+          const req = getGuardianActionRequest(d.requestId);
+          if (req && expMessage.toUpperCase().startsWith(req.requestCode)) {
+            matchedState = state;
+            break;
+          }
+        }
+        if (matchedState) break;
+      }
+      expect(matchedState).toBe('expired');
+    });
+  });
 });