feat: flow escape in local fallback (tmp)

api/src/chat/services/bot.service.spec.ts

@@ -217,7 +217,7 @@ describe('BotService', () => {
     ]);
   });
 
-  afterEach(jest.clearAllMocks);
+  afterEach(jest.resetAllMocks);
   afterAll(closeInMongodConnection);
   describe('startConversation', () => {
     afterAll(() => {

api/src/chat/services/bot.service.ts

@@ -11,6 +11,8 @@ import { EventEmitter2 } from '@nestjs/event-emitter';
 
 import { BotStatsType } from '@/analytics/schemas/bot-stats.schema';
 import EventWrapper from '@/channel/lib/EventWrapper';
+import { HelperService } from '@/helper/helper.service';
+import { FlowEscape, HelperType } from '@/helper/types';
 import { LoggerService } from '@/logger/logger.service';
 import { SettingService } from '@/setting/services/setting.service';
 
@@ -24,7 +26,7 @@ import {
   OutgoingMessageFormat,
   StdOutgoingMessageEnvelope,
 } from '../schemas/types/message';
-import { BlockOptions, FallbackOptions } from '../schemas/types/options';
+import { FallbackOptions } from '../schemas/types/options';
 
 import { BlockService } from './block.service';
 import { ConversationService } from './conversation.service';
@@ -39,6 +41,7 @@ export class BotService {
     private readonly conversationService: ConversationService,
     private readonly subscriberService: SubscriberService,
     private readonly settingService: SettingService,
+    private readonly helperService: HelperService,
   ) {}
 
   /**
@@ -244,10 +247,12 @@ export class BotService {
   /**
    * Handles advancing the conversation to the specified *next* block.
    *
-   * 1. Updates “popular blocks” stats.
-   * 2. Persists the updated conversation context.
-   * 3. Triggers the next block.
-   * 4. Ends the conversation if an unrecoverable error occurs.
+   * @param convo - The current conversation object containing context and state.
+   * @param next - The next block to proceed to in the conversation flow.
+   * @param event - The incoming event that triggered the conversation flow.
+   * @param fallback - Boolean indicating if this is a fallback response in case no appropriate reply was found.
+   *
+   * @returns A promise that resolves to a boolean indicating whether the next block was successfully triggered.
    */
   async proceedToNextBlock(
     convo: ConversationFull,
@@ -348,45 +353,16 @@ export class BotService {
   ) {
     try {
       let fallback = false;
-      const currentBlock = convo.current;
-      const fallbackOptions: BlockOptions['fallback'] = convo.current?.options
-        ?.fallback
-        ? convo.current.options.fallback
-        : {
-            active: false,
-            max_attempts: 0,
-            message: [],
-          };
-
-      // We will avoid having multiple matches when we are not at the start of a conversation
-      // and only if local fallback is enabled
-      const canHaveMultipleMatches = !fallbackOptions.active;
-      // Find the next block that matches
-      const nextBlocks = await this.blockService.findAndPopulate({
-        _id: { $in: convo.next.map(({ id }) => id) },
-      });
-      const matchedBlock = await this.blockService.match(
-        nextBlocks,
-        event,
-        canHaveMultipleMatches,
-      );
-      // If there is no match in next block then loopback (current fallback)
-      // This applies only to text messages + there's a max attempt to be specified
+      this.logger.debug('Handling ongoing conversation message ...', convo.id);
+      const matchedBlock = await this.findNextMatchingBlock(convo, event);
       let fallbackBlock: BlockFull | undefined = undefined;
       if (!matchedBlock && this.shouldAttemptLocalFallback(convo, event)) {
-        // Trigger block fallback
-        // NOTE : current is not populated, this may cause some anomaly
-        fallbackBlock = {
-          ...currentBlock,
-          nextBlocks: convo.next,
-          // If there's labels, they should be already have been assigned
-          assign_labels: [],
-          trigger_labels: [],
-          attachedBlock: null,
-          category: null,
-          previousBlocks: [],
-        };
-        fallback = true;
+        const fallbackResult = await this.handleFlowEscapeFallback(
+          convo,
+          event,
+        );
+        fallbackBlock = fallbackResult.nextBlock;
+        fallback = fallbackResult.fallback;
       }
 
       const next = matchedBlock || fallbackBlock;
@@ -410,6 +386,92 @@ export class BotService {
     }
   }
 
+  /**
+   * Handles the flow escape fallback logic for a conversation.
+   *
+   * This method adjudicates the flow escape event and helps determine the next block to execute based on the helper's response.
+   * It can coerce the event to a specific next block, create a new context, or reprompt the user with a fallback message.
+   * If the helper cannot handle the flow escape, it returns a fallback block with the current conversation's state.
+   *
+   * @param convo - The current conversation object.
+   * @param event - The incoming event that triggered the fallback.
+   *
+   * @returns An object containing the next block to execute (if any) and a flag indicating if a fallback should occur.
+   */
+  async handleFlowEscapeFallback(
+    convo: ConversationFull,
+    event: EventWrapper<any, any>,
+  ): Promise<{ nextBlock?: BlockFull; fallback: boolean }> {
+    const currentBlock = convo.current;
+    const fallbackOptions: FallbackOptions =
+      this.blockService.getFallbackOptions(currentBlock);
+    const fallbackBlock: BlockFull = {
+      ...currentBlock,
+      nextBlocks: convo.next,
+      assign_labels: [],
+      trigger_labels: [],
+      attachedBlock: null,
+      category: null,
+      previousBlocks: [],
+    };
+
+    try {
+      const helper = await this.helperService.getDefaultHelper(
+        HelperType.FLOW_ESCAPE,
+      );
+
+      if (!helper.canHandleFlowEscape(currentBlock)) {
+        return { nextBlock: fallbackBlock, fallback: true };
+      }
+
+      // Adjudicate the flow escape event
+      this.logger.debug(
+        `Adjudicating flow escape for block '${currentBlock.id}' in conversation '${convo.id}'.`,
+      );
+      const result = await helper.adjudicate(event, currentBlock);
+
+      switch (result.action) {
+        case FlowEscape.Action.COERCE: {
+          // Coerce the option to the next block
+          this.logger.debug(`Coercing option to the next block ...`, convo.id);
+          const proxiedEvent = new Proxy(event, {
+            get(target, prop, receiver) {
+              if (prop === 'getText') {
+                return () => result.coercedOption;
+              }
+              return Reflect.get(target, prop, receiver);
+            },
+          });
+          const matchedBlock = await this.findNextMatchingBlock(
+            convo,
+            proxiedEvent,
+          );
+          return { nextBlock: matchedBlock, fallback: true };
+        }
+
+        case FlowEscape.Action.NEW_CTX:
+          this.eventEmitter.emit('hook:conversation:end', convo);
+          return { nextBlock: undefined, fallback: false };
+
+        case FlowEscape.Action.REPROMPT:
+        default:
+          if (result.repromptMessage) {
+            fallbackBlock.options.fallback = {
+              ...fallbackOptions,
+              message: [result.repromptMessage],
+            };
+          }
+          return { nextBlock: fallbackBlock, fallback: true };
+      }
+    } catch (err) {
+      this.logger.warn(
+        'Unable to handle flow escape, using default local fallback ...',
+        err,
+      );
+      return { nextBlock: fallbackBlock, fallback: true };
+    }
+  }
+
   /**
    * Determines if the incoming message belongs to an active conversation and processes it accordingly.
    * If an active conversation is found, the message is handled as part of that conversation.

api/src/utils/test/mocks/block.ts

@@ -81,7 +81,7 @@ const position = {
   y: 0,
 };
 
-export const baseBlockInstance = {
+export const baseBlockInstance: Partial<BlockFull> = {
   trigger_labels: [labelMock],
   assign_labels: [labelMock],
   options: blockOptions,
@@ -90,7 +90,7 @@ export const baseBlockInstance = {
   position,
   builtin: true,
   attachedBlock: null,
-  category: undefined,
+  category: null,
   previousBlocks: [],
   trigger_channels: [],
   nextBlocks: [],