@peopl-health/nexus 3.13.0 → 3.13.2

package/lib/controllers/assistantController.js

@@ -5,9 +5,9 @@ const { logger } = require('../utils/logger');
 const { getThreadInfo, switchThreadStoppedStatus } = require('../helpers/threadHelper');
 
 const { getRecordByFilter } = require('../services/airtableService');
-const { createAssistant, addMsgAssistant, addInsAssistant, switchAssistant } = require('../services/assistantService');
+const { createAssistant, addMsgAssistant, switchAssistant } = require('../services/assistantService');
 
-const { sendMessage } = require('../core/NexusMessaging');
+const { sendMessage, processInstruction, processSystemMessage } = require('../core/NexusMessaging');
 
 const _updateThreadFlag = async (req, res, field, successMsg, errorMsg) => {
   const { code } = req.body;
@@ -36,8 +36,7 @@ const addInsAssistantController = async (req, res) => {
   if (!code) return res.status(400).json({ success: false, error: 'Code is required' });
 
   try {
-    const reply = await addInsAssistant(code, instruction, 'developer');
-    if (reply) await sendMessage({ code, body: reply, fileType: 'text', origin: 'assistant' });
+    await processInstruction(code, instruction, 'developer');
     return res.status(200).json({ success: true, message: 'Instruction added to assistant' });
   } catch (error) {
     logger.error('[AssistantController] Add instruction error', { error: error.message, code });
@@ -50,8 +49,11 @@ const addMsgAssistantController = async (req, res) => {
   if (!code) return res.status(400).json({ success: false, error: 'Code is required' });
 
   try {
-    const assistantReply = await addMsgAssistant(code, messages, role, reply);
-    if (assistantReply) await sendMessage({ code, body: assistantReply, fileType: 'text', origin: 'assistant' });
+    if (reply) {
+      await processSystemMessage(code, messages, role);
+    } else {
+      await addMsgAssistant(code, messages, role);
+    }
     return res.status(200).json({ success: true, message: 'Message added to assistant' });
   } catch (error) {
     logger.error('[AssistantController] Add message error', { error: error.message, code, role });

package/lib/core/AssistantProcessor.js

@@ -2,8 +2,8 @@
  * Handles assistant message processing with local or queue modes.
  */
 class AssistantProcessor {
-  constructor({ mode = 'local', queueAdapter = null, sendMessage = null, replyAssistant = null }) {
-    Object.assign(this, { mode, queueAdapter, sendMessage, replyAssistant });
+  constructor({ mode = 'local', queueAdapter = null, sendMessage = null, replyAssistant = null, runDirect = null }) {
+    Object.assign(this, { mode, queueAdapter, sendMessage, replyAssistant, runDirect });
     if (mode === 'queue' && queueAdapter) {
       queueAdapter.process('assistant.process', (payload) => this._processLocal(payload));
     }
@@ -33,6 +33,12 @@ class AssistantProcessor {
     return await this.queueAdapter.waitForResult(jobId, 120000);
   }
 
+  async processDirect({ code, runOptions = {} }) {
+    if (!code) throw new Error('code is required for direct processing');
+    if (!this.runDirect) throw new Error('runDirect function not configured');
+    return await this.runDirect(code, runOptions);
+  }
+
   async sendResponse(code, result) {
     if (!this.sendMessage) throw new Error('sendMessage function not configured');
     if (!result?.output) return null;

package/lib/core/BatchingManager.js

@@ -15,6 +15,7 @@ class BatchingManager {
     this.activeRequests = new Map();
     this.abandonedRuns = new Set();
     this.typingIntervals = new Map();
+    this.chatQueues = new Map();
   }
 
   setProvider(provider) {
@@ -38,6 +39,7 @@ class BatchingManager {
 
         if (this.config.immediateRestart) {
           this._clearProcessingState(chatId);
+          this.processingLocks.set(chatId, true);
           await this._runWithLock(chatId, processingFn, sendResponseFn);
         }
       }
@@ -48,7 +50,17 @@ class BatchingManager {
     await this._runWithLock(chatId, processingFn, sendResponseFn);
   }
 
+  async enqueueProcessing(chatId, processingFn, sendResponseFn) {
+    await this._runWithLock(chatId, processingFn, sendResponseFn);
+  }
+
   async _runWithLock(chatId, processingFn, sendResponseFn) {
+    const prev = this.chatQueues.get(chatId) || Promise.resolve();
+    let resolveGate;
+    const gate = new Promise(r => { resolveGate = r; });
+    this.chatQueues.set(chatId, gate);
+    await prev;
+
     this.processingLocks.set(chatId, true);
     const runId = `run_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
     this.activeRequests.set(chatId, runId);
@@ -67,6 +79,8 @@ class BatchingManager {
       if (this.activeRequests.get(chatId) === runId) {
         this._clearProcessingState(chatId);
       }
+      resolveGate();
+      if (this.chatQueues.get(chatId) === gate) this.chatQueues.delete(chatId);
       if (this.abandonedRuns.size > 100) {
         const toKeep = [...this.abandonedRuns].slice(-20);
         this.abandonedRuns.clear();

package/lib/core/NexusMessaging.js

@@ -6,7 +6,7 @@ const { connect } = require('../config/mongoConfig');
 
 const { logger } = require('../utils/logger');
 
-const { Message } = require('../models/messageModel');
+const { Message, insertMessage } = require('../models/messageModel');
 const { Thread } = require('../models/threadModel');
 
 const { setEventBus: setStatusEventBus } = require('../helpers/messageStatusHelper');
@@ -14,7 +14,7 @@ const { ensureThreadExists } = require('../helpers/threadHelper');
 
 const { createMessagingProvider } = require('../adapters/registry');
 
-const { addMsgAssistant, replyAssistant } = require('../services/assistantService');
+const { addMsgAssistant, replyAssistant, runDirect } = require('../services/assistantService');
 const { hasPreprocessingHandler, invokePreprocessingHandler } = require('../services/preprocessingService');
 
 const { BatchingManager } = require('../core/BatchingManager');
@@ -76,7 +76,8 @@ class NexusMessaging {
       mode: config.assistant?.mode || 'local',
       queueAdapter: this.queueAdapter,
       sendMessage: this.sendMessage.bind(this),
-      replyAssistant
+      replyAssistant,
+      runDirect
     });
   }
 
@@ -350,29 +351,112 @@ class NexusMessaging {
   }
 
   /*
-   * MESSAGE BATCHING
+   * PROCESSING PIPELINE
    */
 
-  async _handleWithCheckAfter(chatId) {
+  async _executeWithPipeline(chatId, type, mode, executeFn) {
+    let capturedResult = null;
+
     const processingFn = async (runId) => {
       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);
-        },
+      capturedResult = await this.pipeline.run(
+        { chatId, runId, type },
+        executeFn,
         shouldContinue
       );
+      return capturedResult;
     };
 
     const sendResponseFn = async (result) => {
       await this.assistantProcessor.sendResponse(chatId, result);
     };
 
-    await this.batchingManager.handleBatchedProcessing(chatId, processingFn, sendResponseFn);
+    if (mode === 'queue') {
+      await this.batchingManager.enqueueProcessing(chatId, processingFn, sendResponseFn);
+    } else {
+      await this.batchingManager.handleBatchedProcessing(chatId, processingFn, sendResponseFn);
+    }
+
+    return capturedResult;
+  }
+
+  async _handleWithCheckAfter(chatId) {
+    await this._executeWithPipeline(chatId, 'message', 'preempt',
+      async (preProcessResult, shouldContinue) => {
+        return await this._processMessages(chatId, () =>
+          this.assistantProcessor.process({ code: chatId, runOptions: { prePromptResult: preProcessResult } })
+        , shouldContinue);
+      }
+    );
+  }
+
+  async processInstruction(code, instruction, role = 'developer') {
+    const assistantId = await this._getThreadAssistantId(code);
+    await insertMessage({
+      nombre_whatsapp: 'Instruction',
+      numero: code,
+      body: instruction,
+      message_id: `instruction_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+      from_me: true,
+      processed: true,
+      origin: 'instruction',
+      assistant_id: assistantId,
+      raw: { role }
+    });
+
+    const result = await this._executeWithPipeline(code, 'instruction', 'queue',
+      async (preProcessResult) => {
+        return await this.assistantProcessor.processDirect({
+          code,
+          runOptions: {
+            prePromptResult: preProcessResult,
+            additionalInstructions: instruction,
+            additionalMessages: [{ role, content: instruction }],
+            toolChoice: 'none',
+          }
+        });
+      }
+    );
+
+    return result?.output || null;
+  }
+
+  async processSystemMessage(code, messages, role = 'system') {
+    const normalizedMessages = Array.isArray(messages) ? messages : [messages];
+    const assistantId = await this._getThreadAssistantId(code);
+
+    for (let i = 0; i < normalizedMessages.length; i++) {
+      await insertMessage({
+        nombre_whatsapp: 'System',
+        numero: code,
+        body: normalizedMessages[i],
+        message_id: `system_${Date.now()}_${i}_${Math.random().toString(36).substring(7)}`,
+        from_me: true,
+        processed: true,
+        origin: 'system',
+        assistant_id: assistantId,
+        raw: { role }
+      });
+    }
+
+    const result = await this._executeWithPipeline(code, 'system', 'queue',
+      async (preProcessResult) => {
+        return await this.assistantProcessor.processDirect({
+          code,
+          runOptions: {
+            prePromptResult: preProcessResult,
+            toolChoice: 'none',
+          }
+        });
+      }
+    );
+
+    return result?.output || null;
+  }
+
+  async _getThreadAssistantId(code) {
+    const thread = await Thread.findOne({ code }).select('assistant_id prompt_id').lean();
+    return thread?.prompt_id || thread?.assistant_id || null;
   }
 
   async _processMessages(chatId, processingFn, shouldFinalize = () => true) {
@@ -450,6 +534,14 @@ const sendScheduledMessage = async (scheduledMessage) => {
   return await requireDefaultInstance().sendScheduledMessage(scheduledMessage);
 };
 
+const processInstruction = async (code, instruction, role) => {
+  return await requireDefaultInstance().processInstruction(code, instruction, role);
+};
+
+const processSystemMessage = async (code, messages, role) => {
+  return await requireDefaultInstance().processSystemMessage(code, messages, role);
+};
+
 const getEventBus = () => getDefaultInstance()?.getEventBus();
 
 const _resetDefaultInstance = () => { defaultInstance = null; };
@@ -458,8 +550,11 @@ module.exports = {
   NexusMessaging,
   sendMessage,
   sendScheduledMessage,
+  processInstruction,
+  processSystemMessage,
   setDefaultInstance,
   getDefaultInstance,
+  requireDefaultInstance,
   getProvider,
   requireProvider,
   getEventBus,

package/lib/index.d.ts

@@ -246,6 +246,8 @@ declare module '@peopl-health/nexus' {
     getBatchingManager(): BatchingManager;
     getPipeline(): ProcessingPipeline;
     getAssistantProcessor(): AssistantProcessor;
+    processInstruction(code: string, instruction: string, role?: string): Promise<string | null>;
+    processSystemMessage(code: string, messages: string | string[], role?: string): Promise<string | null>;
     isConnected(): boolean;
     disconnect(): Promise<void>;
   }
@@ -518,6 +520,11 @@ declare module '@peopl-health/nexus' {
       processingFn: (runId: string) => Promise<any>,
       sendResponseFn: (result: any) => Promise<void>
     ): Promise<void>;
+    enqueueProcessing(
+      chatId: string,
+      processingFn: (runId: string) => Promise<any>,
+      sendResponseFn: (result: any) => Promise<void>
+    ): Promise<void>;
   }
 
   // ProcessingPipeline — hook lifecycle for all LLM operations
@@ -552,6 +559,7 @@ declare module '@peopl-health/nexus' {
     queueAdapter?: QueueAdapter;
     sendMessage?: (messageData: MessageData) => Promise<any>;
     replyAssistant?: (code: string, body?: string, thread?: any, options?: any) => Promise<any>;
+    runDirect?: (code: string, runOptions?: Record<string, any>) => Promise<any>;
   }
 
   export interface ProcessInput {
@@ -566,6 +574,7 @@ declare module '@peopl-health/nexus' {
     setReplyAssistant(fn: AssistantProcessorConfig['replyAssistant']): void;
     setSendMessage(fn: AssistantProcessorConfig['sendMessage']): void;
     process(input: ProcessInput): Promise<{ output: string; tools_executed?: any[]; prompt?: string; response_id?: string } | null>;
+    processDirect(input: { code: string; runOptions?: Record<string, any> }): Promise<{ output: string; tools_executed?: any[]; prompt?: string; response_id?: string } | null>;
     sendResponse(code: string, result: any): Promise<string | null>;
   }
 }

package/lib/services/assistantService.js

@@ -66,40 +66,34 @@ const createAssistantCore = async (code, assistant_id, _messages = [], force = f
   }
 };
 
-const addMsgAssistantCore = async (code, inMessages, role = 'system', reply = false, skipSystemMessage = false) => {
+const addMsgAssistantCore = async (code, inMessages, role = 'system') => {
   const thread = await getThread(code);
   if (!thread) return null;
 
   try {
     const messages = Array.isArray(inMessages) ? inMessages : [inMessages];
 
-    if (!skipSystemMessage) {
-      for (let i = 0; i < messages.length; i++) {
-        const message = messages[i];
-        try {
-          const message_id = `system_${Date.now()}_${i}_${Math.random().toString(36).substring(7)}`;
-          await insertMessage({
-            nombre_whatsapp: 'System',
-            numero: code,
-            body: message,
-            message_id: message_id,
-            from_me: true,
-            processed: true,
-            origin: 'system',
-            assistant_id: thread.getAssistantId(),
-            raw: { role: role }
-          });
-        } catch (err) {
-          logger.error('[addMsgAssistant] Error saving system message', { err });
-        }
+    for (let i = 0; i < messages.length; i++) {
+      const message = messages[i];
+      try {
+        const message_id = `system_${Date.now()}_${i}_${Math.random().toString(36).substring(7)}`;
+        await insertMessage({
+          nombre_whatsapp: 'System',
+          numero: code,
+          body: message,
+          message_id: message_id,
+          from_me: true,
+          processed: true,
+          origin: 'system',
+          assistant_id: thread.getAssistantId(),
+          raw: { role: role }
+        });
+      } catch (err) {
+        logger.error('[addMsgAssistant] Error saving system message', { err });
       }
     }
 
-    if (!reply) return null;
-
-    const assistant = getAssistantById(thread.getAssistantId(), thread);
-    const runResult = await runAssistantWithRetries(thread, assistant, { toolChoice: 'none' });
-    return runResult?.output || null;
+    return null;
   } catch (error) {
     logger.error('[addMsgAssistant] Error adding message', { error: error.message, code, role });
     return null;
@@ -111,35 +105,19 @@ const addInstructionCore = async (code, instruction, role = 'system') => {
   if (!thread) return null;
 
   try {
-    const assistant = getAssistantById(thread.getAssistantId(), thread);
-
-    try {
-      const message_id = `instruction_${Date.now()}_${Math.random().toString(36).substring(7)}`;
-      await insertMessage({
-        nombre_whatsapp: 'Instruction',
-        numero: code,
-        body: instruction,
-        message_id: message_id,
-        from_me: true,
-        processed: true,
-        origin: 'instruction',
-        assistant_id: thread.getAssistantId(),
-        raw: { role: role }
-      });
-    } catch (err) {
-      logger.error('[addInstruction] Error saving instruction message', { err });
-    }
-
-    const runResult = await runAssistantWithRetries(thread, assistant, {
-      additionalInstructions: instruction,
-      additionalMessages: [
-        { role: role, content: instruction }
-      ],
-      toolChoice: 'none'
+    const message_id = `instruction_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+    await insertMessage({
+      nombre_whatsapp: 'Instruction',
+      numero: code,
+      body: instruction,
+      message_id: message_id,
+      from_me: true,
+      processed: true,
+      origin: 'instruction',
+      assistant_id: thread.getAssistantId(),
+      raw: { role: role }
     });
-
-    logger.info('[addInstruction] Run response', { output: runResult?.output });
-    return runResult?.output || null;
+    return null;
   } catch (error) {
     logger.error('[addInstruction] Error adding instruction', { error: error.message, code, role });
     return null;
@@ -325,6 +303,27 @@ const replyAssistantCore = async (code, message_ = null, thread_ = null, runOpti
   }
 };
 
+const runDirectCore = async (code, runOptions = {}) => {
+  const thread = await getThread(code);
+  if (!thread) return null;
+
+  try {
+    const assistant = getAssistantById(thread.getAssistantId(), thread);
+    const runResult = await runAssistantWithRetries(thread, assistant, runOptions);
+    const output = sanitizeOutput(runResult?.output);
+    return {
+      output,
+      tools_executed: runResult?.tools_executed,
+      prompt: runResult?.run?.prompt || null,
+      preset: runResult?.run?.preset || null,
+      response_id: runResult?.run?.id || null
+    };
+  } catch (error) {
+    logger.error('[runDirect] Error', { error: error.message, code });
+    throw error;
+  }
+};
+
 const switchAssistantCore = async (code, assistant_id) => {
   try {
     const thread = await Thread.findOne({ code });
@@ -377,6 +376,10 @@ module.exports = {
     'assistant.has_custom_thread': !!thread_,
     'assistant.has_run_options': !!runOptions && Object.keys(runOptions).length > 0
   })),
+  runDirect: withTracing(runDirectCore, 'run_direct', (code) => ({
+    'assistant.thread_code': code,
+    'operation.type': 'run_direct'
+  })),
   switchAssistant: withTracing(switchAssistantCore, 'switch_assistant', (code, assistant_id) => ({
     'assistant.thread_code': code,
     'assistant.new_id': assistant_id,

package/package.json

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