@peopl-health/nexus 2.2.9 → 2.3.0

package/lib/observability/telemetry.js

@@ -0,0 +1,118 @@
+const { NodeSDK } = require('@opentelemetry/sdk-node');
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
+const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
+const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-node');
+
+class TelemetryManager {
+  constructor() {
+    this.sdk = null;
+    this.isInitialized = false;
+  }
+
+  async init(config = {}) {
+    if (this.isInitialized) {
+      console.log('✅ OpenTelemetry already initialized');
+      return;
+    }
+
+    const {
+      serviceName = 'nexus-assistant',
+      serviceVersion = '1.0.0',
+      jaegerEndpoint = 'http://localhost:14268/api/traces',
+      prometheusEndpoint = '/metrics',
+      prometheusPort = 9090
+    } = config;
+
+    try {
+      process.env.OTEL_SERVICE_NAME = serviceName;
+      process.env.OTEL_SERVICE_VERSION = serviceVersion;
+
+      const prometheusExporter = new PrometheusExporter({
+        endpoint: prometheusEndpoint,
+        port: prometheusPort,
+      });
+
+      const jaegerExporter = new JaegerExporter({
+        endpoint: jaegerEndpoint,
+        tags: [],
+        timeout: 10000,
+      });
+
+      const batchSpanProcessor = new BatchSpanProcessor(jaegerExporter, {
+        maxExportBatchSize: process.env.NODE_ENV === 'production' ? 50 : 10,
+        maxQueueSize: process.env.NODE_ENV === 'production' ? 2048 : 100,
+        exportTimeoutMillis: process.env.NODE_ENV === 'production' ? 5000 : 2000,
+        scheduledDelayMillis: process.env.NODE_ENV === 'production' ? 2000 : 500,
+      });
+
+      this.sdk = new NodeSDK({
+        instrumentations: [getNodeAutoInstrumentations({
+          '@opentelemetry/instrumentation-fs': {
+            enabled: false,
+          },
+          '@opentelemetry/instrumentation-dns': {
+            enabled: process.env.NODE_ENV !== 'production',
+          },
+          '@opentelemetry/instrumentation-net': {
+            enabled: process.env.NODE_ENV !== 'production',
+          },
+          '@opentelemetry/instrumentation-http': {
+            enabled: true,
+            requestHook: (span, request) => {
+              span.setAttributes({
+                'http.request.content_length': request.headers['content-length'] || 0,
+                'http.route': request.url,
+              });
+            }
+          },
+          '@opentelemetry/instrumentation-express': {
+            enabled: true,
+          },
+          '@opentelemetry/instrumentation-mongodb': {
+            enabled: true,
+          },
+          '@opentelemetry/instrumentation-mongoose': {
+            enabled: true,
+          }
+        })],
+        spanProcessor: batchSpanProcessor,
+        metricReader: prometheusExporter,
+      });
+
+      await this.sdk.start();
+      this.isInitialized = true;
+
+      console.log(`🚀 OpenTelemetry initialized for "${serviceName}"`);
+      console.log(`📊 Metrics available at: http://localhost:${prometheusPort}${prometheusEndpoint}`);
+      console.log(`🔍 Traces sent to: ${jaegerEndpoint}`);
+
+    } catch (error) {
+      console.error('❌ Failed to initialize OpenTelemetry:', error.message);
+      this.isInitialized = false; // Ensure state is consistent on failure
+      throw error;
+    }
+  }
+
+  async shutdown() {
+    if (this.sdk && this.isInitialized) {
+      try {
+        await this.sdk.shutdown();
+        this.isInitialized = false;
+        console.log('🛑 OpenTelemetry shutdown completed');
+      } catch (error) {
+        console.error('❌ Error during OpenTelemetry shutdown:', error.message);
+        this.isInitialized = false; // Reset state even on error
+        throw error;
+      }
+    }
+  }
+}
+
+const telemetryManager = new TelemetryManager();
+
+module.exports = {
+  telemetryManager,
+  initTelemetry: async (config) => await telemetryManager.init(config),
+  shutdownTelemetry: async () => await telemetryManager.shutdown()
+};

package/lib/providers/OpenAIResponsesProvider.js

@@ -205,7 +205,6 @@ class OpenAIResponsesProvider {
       content: this._normalizeContent(role, content),
       type: 'message',
     });
-    console.log('payload', payload);
 
     if (payload.content) {
       return this._retryWithRateLimit(async () => {
@@ -307,11 +306,9 @@ class OpenAIResponsesProvider {
         tools: transformedTools,
       });
 
-      console.log('payload', payload);
       const response = await this._retryWithRateLimit(() => 
         this.client.responses.create(payload)
       );
-      console.log('response', response);
 
       if (response?.status !== 'completed') {
         await this.cleanupOrphanedFunctionCalls(id, true);

package/lib/services/assistantService.js

@@ -5,11 +5,13 @@ const runtimeConfig = require('../config/runtimeConfig');
 const { BaseAssistant } = require('../assistants/BaseAssistant');
 const { createProvider } = require('../providers/createProvider');
 
-const { Message, formatTimestamp } = require('../models/messageModel.js');
 const { Thread } = require('../models/threadModel.js');
 
 const { getCurRow } = require('../helpers/assistantHelper.js');
-const { processIndividualMessage, getLastMessages } = require('../helpers/assistantHelper.js');
+const { runAssistantAndWait, runAssistantWithRetries } = require('../helpers/assistantHelper.js');
+const { getThread, getThreadInfo } = require('../helpers/threadHelper.js');
+const { withTracing } = require('../utils/tracingDecorator.js');
+const { processIndividualMessage, getLastMessages } = require('../helpers/messageHelper.js');
 const { combineImagesToPDF, cleanupFiles } = require('../helpers/filesHelper.js');
 const { delay } = require('../helpers/whatsappHelper.js');
 
@@ -27,64 +29,6 @@ const configureAssistants = (config) => {
   assistantConfig = config;
 };
 
-const runAssistantAndWait = async ({
-  thread,
-  assistant,
-  runConfig = {}
-}) => {
-  if (!thread || !thread.getConversationId()) {
-    throw new Error('runAssistantAndWait requires a thread with a valid thread_id or conversation_id');
-  }
-
-  if (!assistant) {
-    throw new Error('runAssistantAndWait requires an assistant instance');
-  }
-
-  const provider = createProvider({ variant: process.env.VARIANT || 'assistants' });
-  const { polling, tools: configTools, ...conversationConfig } = runConfig || {};
-  const variant = provider.getVariant ? provider.getVariant() : (process.env.VARIANT || 'assistants');
-
-  // Get tool schemas from assistant if available, fallback to config tools
-  const tools = assistant.getToolSchemas ? assistant.getToolSchemas() : (configTools || []);
-
-  // Only pass assistant for Responses API (needed to handle pending function calls)
-  const runConfigWithAssistant = variant === 'responses'
-    ? { ...conversationConfig, assistant }
-    : conversationConfig;
-
-  let run = await provider.runConversation({
-    threadId: thread.getConversationId(),
-    assistantId: thread.getAssistantId(),
-    tools: tools.length > 0 ? tools : undefined,
-    ...runConfigWithAssistant,
-  });
-
-  const filter = thread.code ? { code: thread.code, active: true } : null;
-  if (filter) {
-    await Thread.updateOne(filter, { $set: { run_id: run.id } });
-  }
-
-  const maxRetries = polling?.maxRetries ?? DEFAULT_MAX_RETRIES;
-  let completed = false;
-
-  try {
-    console.log('RUN ID', run.id, 'THREAD ID', thread.getConversationId(), 'ASSISTANT ID', thread.getAssistantId());
-    ({run, completed} = await provider.checkRunStatus(assistant, thread.getConversationId(), run.id, 0, maxRetries));
-  } finally {
-    if (filter) {
-      await Thread.updateOne(filter, { $set: { run_id: null } });
-    }
-  }
-
-  if (!completed) {
-    return { run: run, completed: false, output: '' };
-  }
-
-  const output = await provider.getRunText({ threadId: thread.getConversationId(), runId: run.id, fallback: '' });
-
-  return { completed: true, output };
-};
-
 const registerAssistant = (assistantId, definition) => {
   if (!assistantId || typeof assistantId !== 'string') {
     throw new Error('registerAssistant requires a string assistantId');
@@ -189,7 +133,6 @@ const getAssistantById = (assistant_id, thread) => {
 
 
 const createAssistant = async (code, assistant_id, messages=[], force=false) => {
-  // If thread already exists, update it
   const findThread = await Thread.findOne({ code: code });
   console.log('[createAssistant] findThread', findThread);
   if (findThread && findThread.getConversationId()) {
@@ -279,162 +222,123 @@ const addMsgAssistant = async (code, inMessages, role = 'user', reply = false) =
   }
 };
 
-const addInsAssistant = async (code, instruction, role = 'user') => {
-  try {
-    const thread = await Thread.findOne({ code: code });
-    console.log(thread);
-    if (thread === null) return null;
-
-    let output, completed;
-    let retries = 0;
-    const maxRetries = DEFAULT_MAX_RETRIES;
-    const assistant = getAssistantById(thread.getAssistantId(), thread);
-    do {
-      ({ output, completed } = await runAssistantAndWait({
-        thread,
-        assistant,
-        runConfig: {
-          additionalInstructions: instruction,
-          additionalMessages: [
-            { role: role, content: instruction }
-          ]
-        }
-      }));
-      console.log(`Attempt ${retries + 1}: completed=${completed}, output=${output || '(empty)'}`);
-      
-      if (completed && output) break;
-      if (retries < maxRetries) await new Promise(resolve => setTimeout(resolve, 2000));
-      retries++;
-    } while (retries <= maxRetries && (!completed || !output));
-    console.log('RUN RESPONSE', output);
-
-    return output;
-  } catch (error) {
-    console.log(error);
-    return null;
-  }
+const addInstructionCore = async (code, instruction, role = 'user') => {
+  const thread = await withTracing(getThread, 'get_thread_operation', 
+    (threadCode) => ({ 
+      'thread.code': threadCode,
+      'operation.type': 'thread_retrieval' 
+    })
+  )(code);
+  if (thread === null) return null;
+
+  const assistant = getAssistantById(thread.getAssistantId(), thread);
+  const { output, completed, retries } = await withTracing(
+    runAssistantWithRetries,
+    'run_assistant_with_retries',
+    (thread, assistant, runConfig, patientReply) => ({
+      'assistant.id': thread.getAssistantId(),
+      'assistant.max_retries': DEFAULT_MAX_RETRIES,
+      'assistant.has_patient_reply': !!patientReply
+    })
+  )(
+    thread,
+    assistant,
+    {
+      additionalInstructions: instruction,
+      additionalMessages: [
+        { role: role, content: instruction }
+      ]
+    },
+    null // no patientReply for instructions
+  );
+
+  console.log('RUN RESPONSE', output);
+  return output;
 };
 
-const getThread = async (code, message = null) => {
-  try {
-    let thread = await Thread.findOne({ code: code });
-    console.log('GET THREAD');
-    console.log(thread);
-
-    if (thread === null) {
-      if (message != null) {
-        const timestamp = formatTimestamp(message.messageTimestamp);
-        await Message.updateOne({ message_id: message.key.id, timestamp: timestamp }, { $set: { processed: true } });
-        
-      }
-      return null;
-    }
-
-    const provider = createProvider({ variant: process.env.VARIANT || 'assistants' });
-    while (thread && thread.run_id) {
-      console.log(`Wait for ${thread.run_id} to be executed`);
-      const activeProvider = provider || llmConfig.requireOpenAIProvider();
-      const run = await activeProvider.getRun({ threadId: thread.getConversationId(), runId: thread.run_id });
-      if (run.status === 'cancelled' || run.status === 'expired' || run.status === 'completed') {
-        await Thread.updateOne({ code: code }, { $set: { run_id: null } });
-      }
-      thread = await Thread.findOne({ code: code });
-      await delay(5000);
-    }
-
-    return thread;
-  } catch (error) {
-    console.error('Error in getThread:', error.message || error);
+const addInsAssistant = withTracing(
+  addInstructionCore,
+  'add_instruction_assistant',
+  (code, instruction, role) => ({
+    'instruction.thread_code': code,
+    'instruction.content_length': instruction?.length || 0,
+    'instruction.role': role,
+    'operation.type': 'add_instruction'
+  })
+);
+
+const replyAssistantCore = async (code, message_ = null, thread_ = null, runOptions = {}) => {
+  const thread = thread_ || await withTracing(getThread, 'get_thread_operation', 
+    (threadCode) => ({ 
+      'thread.code': threadCode,
+      'operation.type': 'thread_retrieval',
+      'thread.provided': !!thread_
+    })
+  )(code);
+  if (!thread) return null;
+
+  const patientReply = await getLastMessages(code);
+  if (!patientReply) {
+    console.log('[replyAssistantCore] No relevant data found for this assistant.');
     return null;
   }
-};
 
-const getThreadInfo = async (code) => {
-  try {
-    let thread = await Thread.findOne({ code: code });
-    return thread;
-  } catch (error) {
-    console.log(error);
-    return null;
+  const provider = createProvider({ variant: process.env.VARIANT || 'assistants' });
+  
+  let patientMsg = false;
+  let urls = [];
+  for (let i = 0; i < patientReply.length; i++) {
+    const reply = patientReply[i];
+    const { isPatient, url } = await processIndividualMessage(code, reply, provider, thread);
+    console.log(`[replyAssistantCore] Processing message ${i + 1}/${patientReply.length}: isPatient=${isPatient}, hasUrl=${!!url}`);
+    patientMsg = patientMsg || isPatient;
+    if (url) urls.push({ 'url': url });
   }
-};
-
-const replyAssistant = async function (code, message_ = null, thread_ = null, runOptions = {}) {
-  try {
-    let thread = thread_ || await getThread(code);
-    console.log('THREAD STOPPED', code, thread?.active);
-    if (!thread) return null;
-
-    const patientReply = await getLastMessages(code);
-    if (!patientReply) {
-      console.log('No relevant data found for this assistant.');
-      return null;
-    }
-
-    const provider = createProvider({ variant: process.env.VARIANT || 'assistants' });
-    let activeRuns = await provider.listRuns({ threadId: thread.getConversationId(), activeOnly: true });
-    let activeRunsCount = activeRuns?.data?.length || 0;
-    console.log('ACTIVE RUNS:', activeRunsCount, activeRuns?.data?.map(run => ({ id: run.id, status: run.status })));
-    while (activeRunsCount > 0) {
-      console.log(`WAITING FOR ${activeRunsCount} ACTIVE RUNS TO COMPLETE - ${thread.getConversationId()}`);
-      activeRuns = await provider.listRuns({ threadId: thread.getConversationId(), activeOnly: true });
-      activeRunsCount = activeRuns?.data?.length || 0;
-      await delay(5000);
-    }
-
-    let patientMsg = false;
-    let urls = [];
-    for (const reply of patientReply) {
-      const { isPatient, url } = await processIndividualMessage(code, reply, provider, thread);
-      console.log(`isPatient ${isPatient} ${url}`);
-      patientMsg = patientMsg || isPatient;
-      if (url) urls.push({ 'url': url });
-    }
-       
-    if (urls.length > 0) {
-      console.log('urls', urls);
-      const { pdfBuffer, processedFiles } = await combineImagesToPDF({ code });
-      console.log('AFTER COMBINED IN BUFFER', processedFiles);
+  
+  if (urls.length > 0) {
+    console.log(`[replyAssistantCore] Processing ${urls.length} URLs for PDF combination`);
+    const { pdfBuffer, processedFiles } = await combineImagesToPDF({ code });
+    console.log(`[replyAssistantCore] PDF combination complete: ${processedFiles?.length || 0} files processed`);
+    
+    if (pdfBuffer) {
       const key = `${code}-${Date.now()}-combined.pdf`;
       const bucket = runtimeConfig.get('AWS_S3_BUCKET_NAME');
-      if (bucket && pdfBuffer) {
+      if (bucket) {
         await AWS.uploadBufferToS3(pdfBuffer, bucket, key, 'application/pdf');
       }
-      if (processedFiles && processedFiles.length) {
-        cleanupFiles(processedFiles);
-      }
     }
+    
+    if (processedFiles && processedFiles.length) {
+      cleanupFiles(processedFiles);
+    }
+  }
 
-    if (!patientMsg || thread.stopped) return null;
+  if (!patientMsg || thread.stopped) return null;
 
-    const assistant = getAssistantById(thread.getAssistantId(), thread);
-    assistant.setReplies(patientReply);
+  const assistant = getAssistantById(thread.getAssistantId(), thread);
+  const { run, output, completed, retries } = await withTracing(
+    runAssistantWithRetries,
+    'run_assistant_with_retries',
+    (thread, assistant, runConfig, patientReply) => ({
+      'assistant.id': thread.getAssistantId(),
+      'assistant.max_retries': DEFAULT_MAX_RETRIES,
+      'assistant.has_patient_reply': !!patientReply
+    })
+  )(thread, assistant, runOptions, patientReply);
 
-    let run, output, completed;
-    let retries = 0;
-    const maxRetries = DEFAULT_MAX_RETRIES;
-    do {
-      ({ run, output, completed } = await runAssistantAndWait({
-        thread,
-        assistant,
-        runConfig: runOptions
-      }));
-      console.log(`Attempt ${retries + 1}: completed=${completed}, output=${output || '(empty)'}`);
-      
-      if (completed && output) break;
-      if (retries < maxRetries) await new Promise(resolve => setTimeout(resolve, 2000));
-      retries++;
-    } while (retries <= maxRetries && (!completed || !output));
-
-    console.log('RUN LAST ERROR:', run?.last_error);
-    console.log('RUN STATUS', completed);
-    console.log(output);
+  return output;
+};
 
-    return output;
-  } catch (err) {
-    console.log(`Error inside reply assistant ${err} ${code}`);
-  }
-}; 
+const replyAssistant = withTracing(
+  replyAssistantCore,
+  'assistant_reply',
+  (code, message_, thread_, runOptions) => ({
+    'assistant.thread_code': code,
+    'assistant.has_message': !!message_,
+    'assistant.has_custom_thread': !!thread_,
+    'assistant.run_options': JSON.stringify(runOptions)
+  })
+);
 
 const switchAssistant = async (code, assistant_id) => {
   try {

package/lib/storage/MongoStorage.js

@@ -43,9 +43,7 @@ class MongoStorage {
   async saveMessage(messageData) {
     try {
       const enrichedMessage = await this._enrichTwilioMedia(messageData);
-      console.log('[MongoStorage] Enriched message', enrichedMessage);
       const values = this.buildMessageValues(enrichedMessage);
-      console.log('[MongoStorage] Message values', values);
       const { insertMessage } = require('../models/messageModel');
       await insertMessage(values);
       console.log('[MongoStorage] Message stored');

package/lib/utils/logger.js

@@ -1,4 +1,5 @@
 const pino = require('pino');
+const { trace, context } = require('@opentelemetry/api');
 
 const createLogger = (config = {}) => {
   const {
@@ -10,13 +11,99 @@ const createLogger = (config = {}) => {
     transport: process.env.NODE_ENV !== 'production' ? {
       target: 'pino-pretty',
       options: {
-        colorize: true
+        colorize: true,
+        ignore: 'trace_id,span_id,trace_flags'
       }
-    } : undefined
+    } : undefined,
+    // Add OpenTelemetry trace context automatically
+    formatters: {
+      log: (object) => {
+        const span = trace.getActiveSpan();
+        if (span) {
+          const spanContext = span.spanContext();
+          return {
+            ...object,
+            trace_id: spanContext.traceId,
+            span_id: spanContext.spanId,
+            trace_flags: spanContext.traceFlags.toString(16).padStart(2, '0')
+          };
+        }
+        return object;
+      }
+    }
   });
 };
 
-// Default logger instance
+// Enhanced logger with observability methods
+const createObservabilityLogger = (serviceName = 'nexus-assistant', config = {}) => {
+  const baseLogger = createLogger(config);
+  
+  return {
+    ...baseLogger,
+    
+    // Trace-aware logging methods
+    traceInfo: (message, extra = {}) => {
+      const span = trace.getActiveSpan();
+      baseLogger.info({
+        ...extra,
+        operation: span?.name || 'unknown',
+        service: serviceName
+      }, message);
+    },
+    
+    traceError: (error, message, extra = {}) => {
+      const span = trace.getActiveSpan();
+      if (span) {
+        span.recordException(error);
+        span.setStatus({ code: 2, message: error.message });
+      }
+      baseLogger.error({
+        ...extra,
+        err: error,
+        operation: span?.name || 'unknown',
+        service: serviceName
+      }, message);
+    },
+    
+    traceWarn: (message, extra = {}) => {
+      const span = trace.getActiveSpan();
+      baseLogger.warn({
+        ...extra,
+        operation: span?.name || 'unknown',
+        service: serviceName
+      }, message);
+    },
+    
+    // Performance logging
+    performance: (operation, duration, extra = {}) => {
+      baseLogger.info({
+        ...extra,
+        operation,
+        duration_ms: duration,
+        service: serviceName,
+        performance: true
+      }, `Operation ${operation} completed in ${duration}ms`);
+    },
+    
+    // Assistant-specific logging
+    assistantOperation: (operation, threadCode, extra = {}) => {
+      baseLogger.info({
+        ...extra,
+        assistant_operation: operation,
+        thread_code: threadCode,
+        service: serviceName
+      }, `Assistant operation: ${operation} for thread ${threadCode}`);
+    }
+  };
+};
+
+// Default logger instances
 const logger = createLogger();
+const observabilityLogger = createObservabilityLogger();
 
-module.exports = { logger, createLogger };
+module.exports = { 
+  logger, 
+  createLogger, 
+  observabilityLogger, 
+  createObservabilityLogger 
+};

package/lib/utils/sanitizer.js

@@ -0,0 +1,62 @@
+/**
+ * Sanitize filename to prevent path traversal and command injection
+ * @param {string} filename - The filename to sanitize
+ * @param {number} maxLength - Maximum length (default: 50)
+ * @returns {string} Sanitized filename
+ */
+function sanitizeFilename(filename, maxLength = 50) {
+  if (typeof filename !== 'string') return 'unknown';
+  
+  return filename
+    .replace(/[^\w.-]/g, '_')
+    .replace(/^\.+/, '')
+    .replace(/\.+$/, '')
+    .slice(0, maxLength);
+}
+
+/**
+ * Sanitize filename for media uploads (more restrictive)
+ * @param {string} filename - The filename to sanitize
+ * @param {number} maxLength - Maximum length (default: 50)
+ * @returns {string} Sanitized filename for media
+ */
+function sanitizeMediaFilename(filename, maxLength = 50) {
+  if (typeof filename !== 'string') return '';
+  
+  return filename
+    .replace(/[^a-zA-Z0-9_-]/g, '')
+    .slice(0, maxLength);
+}
+
+/**
+ * Sanitize log metadata to remove sensitive information
+ * @param {Object} metadata - Metadata object to sanitize
+ * @returns {Object} Sanitized metadata
+ */
+function sanitizeLogMetadata(metadata) {
+  const safe = { ...metadata };
+  
+  delete safe.text;
+  delete safe.content;  
+  delete safe.body;
+  delete safe.phone;
+  delete safe.numero;
+  
+  if (safe.message_id) {
+    safe.message_id = safe.message_id.length > 8 
+      ? `${safe.message_id.slice(0, 4)}***${safe.message_id.slice(-4)}`
+      : '***';
+  }
+  
+  if (safe.code && safe.code.length > 8) {
+    safe.code = `${safe.code.substring(0, 3)}***${safe.code.slice(-4)}`;
+  }
+  
+  return safe;
+}
+
+module.exports = {
+  sanitizeFilename,
+  sanitizeMediaFilename,
+  sanitizeLogMetadata
+};