@peopl-health/nexus 3.12.0 → 3.13.0

package/lib/core/BatchingManager.js

@@ -1,11 +1,6 @@
 const { logger } = require('../utils/logger');
 const { Message } = require('../models/messageModel');
 
-const VALID_HOOKS = ['preBatch', 'postBatch', 'onBatchError', 'prePromptBuild'];
-
-/**
- * Manages message batching, processing locks, run abandonment, and lifecycle hooks.
- */
 class BatchingManager {
   constructor({ provider = null, config = {} }) {
     this.provider = provider;
@@ -20,33 +15,6 @@ class BatchingManager {
     this.activeRequests = new Map();
     this.abandonedRuns = new Set();
     this.typingIntervals = new Map();
-
-    this._hooks = {
-      preBatch: [],
-      postBatch: [],
-      onBatchError: [],
-      prePromptBuild: [],
-    };
-
-    if (config.hooks) {
-      for (const [name, handlers] of Object.entries(config.hooks)) {
-        const fns = Array.isArray(handlers) ? handlers : [handlers];
-        for (const fn of fns) {
-          this.addHook(name, fn);
-        }
-      }
-    }
-  }
-
-  addHook(name, fn) {
-    if (!VALID_HOOKS.includes(name)) {
-      throw new Error(`[BatchingManager] Unknown hook: "${name}". Valid hooks: ${VALID_HOOKS.join(', ')}`);
-    }
-    if (typeof fn !== 'function') {
-      throw new Error(`[BatchingManager] Hook "${name}" must be a function`);
-    }
-    this._hooks[name].push(fn);
-    return this;
   }
 
   setProvider(provider) {
@@ -70,28 +38,22 @@ class BatchingManager {
 
         if (this.config.immediateRestart) {
           this._clearProcessingState(chatId);
-          await this._processWithLock(chatId, processingFn, sendResponseFn);
+          await this._runWithLock(chatId, processingFn, sendResponseFn);
         }
       }
       return;
     }
 
     this.processingLocks.set(chatId, true);
-    await this._processWithLock(chatId, processingFn, sendResponseFn);
+    await this._runWithLock(chatId, processingFn, sendResponseFn);
   }
 
-  async _processWithLock(chatId, processingFn, sendResponseFn) {
+  async _runWithLock(chatId, processingFn, sendResponseFn) {
     this.processingLocks.set(chatId, true);
     const runId = `run_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
     this.activeRequests.set(chatId, runId);
 
     try {
-      const pre = await this._runSequentialHooks(chatId, runId);
-      if (pre?.skip) {
-        logger.debug('[BatchingManager] Batch skipped by preBatch hook', { chatId, runId });
-        return;
-      }
-
       await this._startTypingRefresh(chatId, runId);
       if (this._checkAbandoned(runId)) return;
 
@@ -101,11 +63,9 @@ class BatchingManager {
       if (sendResponseFn && result) await sendResponseFn(result);
     } catch (error) {
       logger.error('[BatchingManager] Error processing messages', { chatId, error: error.message });
-      this._runDeferredHooks('onBatchError', chatId, error);
     } finally {
       if (this.activeRequests.get(chatId) === runId) {
         this._clearProcessingState(chatId);
-        this._runDeferredHooks('postBatch', chatId);
       }
       if (this.abandonedRuns.size > 100) {
         const toKeep = [...this.abandonedRuns].slice(-20);
@@ -121,63 +81,6 @@ class BatchingManager {
     this._stopTyping(chatId);
   }
 
-  async _runSequentialHooks(chatId, runId) {
-    const hooks = this._hooks.preBatch;
-    if (hooks.length === 0) return;
-
-    const context = { chatId, runId, metadata: {} };
-
-    for (const fn of hooks) {
-      const result = await fn(context);
-      if (result?.skip) return { skip: true };
-    }
-  }
-
-  async runPromptBuildHooks(context) {
-    const hooks = this._hooks.prePromptBuild;
-    if (hooks.length === 0) return null;
-
-    let additionalInstructions = '';
-    const additionalMessages = [];
-    let toolChoice = null;
-    for (const fn of hooks) {
-      const result = await fn(context);
-      if (result?.additionalInstructions) {
-        additionalInstructions += additionalInstructions
-          ? `\n\n${result.additionalInstructions}`
-          : result.additionalInstructions;
-      }
-      if (Array.isArray(result?.additionalMessages) && result.additionalMessages.length > 0) {
-        additionalMessages.push(...result.additionalMessages);
-      }
-      if (result?.toolChoice) {
-        toolChoice = result.toolChoice;
-      }
-    }
-    return { additionalInstructions, additionalMessages, toolChoice };
-  }
-
-  _runDeferredHooks(name, chatId, error) {
-    const hooks = this._hooks[name];
-    if (hooks.length === 0) return;
-
-    setImmediate(() => {
-      if (this.isProcessing(chatId)) return;
-
-      const context = { chatId };
-      if (error) context.error = error;
-
-      Promise.allSettled(hooks.map(fn => fn(context)))
-        .then(results => {
-          for (const result of results) {
-            if (result.status === 'rejected') {
-              logger.error(`[BatchingManager] ${name} hook failed`, { chatId, error: result.reason?.message });
-            }
-          }
-        });
-    });
-  }
-
   _stopTyping(chatId) {
     const interval = this.typingIntervals.get(chatId);
     if (interval) {

package/lib/core/NexusMessaging.js

@@ -18,6 +18,7 @@ const { addMsgAssistant, replyAssistant } = require('../services/assistantServic
 const { hasPreprocessingHandler, invokePreprocessingHandler } = require('../services/preprocessingService');
 
 const { BatchingManager } = require('../core/BatchingManager');
+const { ProcessingPipeline } = require('../core/ProcessingPipeline');
 const { AssistantProcessor } = require('../core/AssistantProcessor');
 
 const { createQueueAdapter } = require('../queue');
@@ -65,6 +66,8 @@ class NexusMessaging {
       config: this.batchingConfig
     });
 
+    this.pipeline = new ProcessingPipeline(this.batchingConfig.hooks);
+
     const queueType = config.queue?.type || 'local';
     const queueConfig = config.queue?.config || {};
     this.queueAdapter = createQueueAdapter(queueType, queueConfig);
@@ -155,6 +158,7 @@ class NexusMessaging {
   getLLMProvider() { return this.llmProvider; }
   getEventBus() { return this.events; }
   getBatchingManager() { return this.batchingManager; }
+  getPipeline() { return this.pipeline; }
   getAssistantProcessor() { return this.assistantProcessor; }
   getQueueAdapter() { return this.queueAdapter; }
   isConnected() { return this.provider?.getConnectionStatus() ?? false; }
@@ -351,9 +355,17 @@ class NexusMessaging {
 
   async _handleWithCheckAfter(chatId) {
     const processingFn = async (runId) => {
-      const prePromptResult = await this.batchingManager.runPromptBuildHooks({ chatId, runId });
-      const shouldFinalize = () => this.batchingManager.isActiveRun(chatId, runId);
-      return await this._processMessages(chatId, () => this.assistantProcessor.process({ code: chatId, runOptions: { runId, prePromptResult } }), shouldFinalize);
+      const shouldContinue = () => this.batchingManager.isActiveRun(chatId, runId);
+
+      return await this.pipeline.run(
+        { chatId, runId, type: 'message' },
+        async (preProcessResult) => {
+          return await this._processMessages(chatId, () =>
+            this.assistantProcessor.process({ code: chatId, runOptions: { runId, prePromptResult: preProcessResult } })
+          , shouldContinue);
+        },
+        shouldContinue
+      );
     };
 
     const sendResponseFn = async (result) => {

package/lib/core/ProcessingPipeline.js

@@ -0,0 +1,145 @@
+const { logger } = require('../utils/logger');
+
+const VALID_HOOKS = ['preProcess', 'postProcess'];
+
+const LEGACY_MAP = {
+  preBatch: 'preProcess',
+  prePromptBuild: 'preProcess',
+  postBatch: 'postProcess',
+  onBatchError: 'postProcess',
+};
+
+class ProcessingPipeline {
+  constructor(hooks = {}) {
+    this._hooks = {
+      preProcess: [],
+      postProcess: [],
+    };
+
+    this._hookMeta = new WeakMap();
+
+    if (hooks && typeof hooks === 'object') {
+      for (const [name, handlers] of Object.entries(hooks)) {
+        const fns = Array.isArray(handlers) ? handlers : [handlers];
+        for (const fn of fns) {
+          this.addHook(name, fn);
+        }
+      }
+    }
+  }
+
+  addHook(name, fn) {
+    const resolved = LEGACY_MAP[name] || name;
+
+    if (!VALID_HOOKS.includes(resolved)) {
+      throw new Error(`[ProcessingPipeline] Unknown hook: "${name}". Valid hooks: ${VALID_HOOKS.join(', ')}`);
+    }
+    if (typeof fn !== 'function') {
+      throw new Error(`[ProcessingPipeline] Hook "${name}" must be a function`);
+    }
+
+    this._hooks[resolved].push(fn);
+    this._hookMeta.set(fn, { originalName: name });
+    return this;
+  }
+
+  async run(context, executeFn, shouldContinue = () => true) {
+    const ctx = { metadata: {}, ...context };
+
+    try {
+      const preProcessResult = await this._runPreProcessHooks(ctx);
+      if (preProcessResult.skip) {
+        logger.debug('[ProcessingPipeline] Skipped by preProcess hook', { chatId: ctx.chatId, type: ctx.type });
+        this._runPostProcessHooks(ctx, null, null);
+        return null;
+      }
+
+      if (!shouldContinue()) return null;
+
+      const result = await executeFn(preProcessResult, shouldContinue);
+
+      if (!shouldContinue()) return null;
+
+      this._runPostProcessHooks(ctx, result, null);
+      return result;
+    } catch (error) {
+      logger.error('[ProcessingPipeline] Error during processing', { chatId: ctx.chatId, type: ctx.type, error: error.message });
+      this._runPostProcessHooks(ctx, null, error);
+      throw error;
+    }
+  }
+
+  async _runPreProcessHooks(context) {
+    const hooks = this._hooks.preProcess;
+    const merged = {
+      skip: false,
+      additionalInstructions: '',
+      additionalMessages: [],
+      toolChoice: null,
+      metadata: context.metadata || {},
+    };
+
+    if (hooks.length === 0) return merged;
+
+    for (const fn of hooks) {
+      const result = await fn(context);
+      if (!result) continue;
+
+      if (result.skip) {
+        merged.skip = true;
+        return merged;
+      }
+
+      if (result.additionalInstructions) {
+        merged.additionalInstructions = merged.additionalInstructions
+          ? `${merged.additionalInstructions}\n\n${result.additionalInstructions}`
+          : result.additionalInstructions;
+      }
+      if (Array.isArray(result.additionalMessages) && result.additionalMessages.length > 0) {
+        merged.additionalMessages.push(...result.additionalMessages);
+      }
+      if (result.toolChoice) {
+        merged.toolChoice = result.toolChoice;
+      }
+      if (result.metadata && typeof result.metadata === 'object') {
+        Object.assign(context.metadata, result.metadata);
+        merged.metadata = context.metadata;
+      }
+    }
+
+    return merged;
+  }
+
+  _runPostProcessHooks(context, result, error) {
+    const hooks = this._hooks.postProcess;
+    if (hooks.length === 0) return;
+
+    setImmediate(() => {
+      const postContext = { chatId: context.chatId, type: context.type };
+      if (result) postContext.result = result;
+      if (error) postContext.error = error;
+
+      // onBatchError: error only. postBatch: always (original used finally block).
+      // postProcess and untagged: always.
+      const applicable = hooks.filter(fn => {
+        const meta = this._hookMeta.get(fn);
+        if (meta?.originalName === 'onBatchError') return !!error;
+        return true;
+      });
+
+      Promise.allSettled(applicable.map(fn => fn(postContext)))
+        .then(results => {
+          for (const r of results) {
+            if (r.status === 'rejected') {
+              logger.error('[ProcessingPipeline] postProcess hook failed', {
+                chatId: context.chatId,
+                error: r.reason?.message
+              });
+            }
+          }
+        });
+    });
+  }
+}
+
+module.exports = { ProcessingPipeline };

package/lib/index.d.ts

@@ -244,6 +244,7 @@ declare module '@peopl-health/nexus' {
     processIncomingMessage(messageData: MessageData): Promise<any>;
     getEventBus(): import('events').EventEmitter;
     getBatchingManager(): BatchingManager;
+    getPipeline(): ProcessingPipeline;
     getAssistantProcessor(): AssistantProcessor;
     isConnected(): boolean;
     disconnect(): Promise<void>;
@@ -495,12 +496,13 @@ declare module '@peopl-health/nexus' {
   export function getPatientMemory(): any;
   export function getConversationSummary(): any;
 
-  // BatchingManager
+  // BatchingManager — per-chatId concurrency control
   export interface BatchingConfig {
     enabled?: boolean;
     abortOnNewMessage?: boolean;
     immediateRestart?: boolean;
     typingIndicator?: boolean;
+    hooks?: Record<string, Function | Function[]>;
   }
 
   export class BatchingManager {
@@ -510,6 +512,7 @@ declare module '@peopl-health/nexus' {
     });
     setProvider(provider: MessageProvider): void;
     isProcessing(chatId: string): boolean;
+    isActiveRun(chatId: string, runId: string): boolean;
     handleBatchedProcessing(
       chatId: string,
       processingFn: (runId: string) => Promise<any>,
@@ -517,6 +520,32 @@ declare module '@peopl-health/nexus' {
     ): Promise<void>;
   }
 
+  // ProcessingPipeline — hook lifecycle for all LLM operations
+  export interface PreProcessResult {
+    skip?: boolean;
+    additionalInstructions?: string;
+    additionalMessages?: Array<Record<string, any>>;
+    toolChoice?: Record<string, any> | null;
+    metadata?: Record<string, any>;
+  }
+
+  export interface ProcessingContext {
+    chatId: string;
+    runId: string;
+    type: string;
+    metadata?: Record<string, any>;
+  }
+
+  export class ProcessingPipeline {
+    constructor(hooks?: Record<string, Function | Function[]>);
+    addHook(name: string, fn: Function): this;
+    run(
+      context: ProcessingContext,
+      executeFn: (preProcessResult: PreProcessResult, shouldContinue: () => boolean) => Promise<any>,
+      shouldContinue?: () => boolean
+    ): Promise<any>;
+  }
+
   // AssistantProcessor
   export interface AssistantProcessorConfig {
     mode?: 'local' | 'queue';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",