@peopl-health/nexus 5.12.4 → 5.12.6

package/lib/clinical/providers/AnthropicProvider.js

@@ -208,7 +208,8 @@ class AnthropicProvider extends BaseLLMProvider {
             const turnContent = Array.isArray(lastUserTurn.content)
               ? lastUserTurn.content
               : [{ type: 'text', text: String(lastUserTurn.content ?? '') }];
-            lastUserTurn.content = [...turnContent, { type: 'text', text: DELIVERY_NUDGE }];
+            const alreadyNudged = turnContent.some(part => part?.type === 'text' && part.text === DELIVERY_NUDGE);
+            if (!alreadyNudged) lastUserTurn.content = [...turnContent, { type: 'text', text: DELIVERY_NUDGE }];
             // The nudge is a model call like any other: gate thinking on it so the per-iteration counter stays honest.
             prepThinking();
             const { result: { result: nudged, retries: nudgeRetries }, durationMs: nudgeDurationMs } = await withTiming(() => makeAPICall(currentMessages));

package/lib/clinical/providers/BaseLLMProvider.js

@@ -16,7 +16,12 @@ const CONVERSATION_CONTINUATION = '(continuar)';
 const NEGATIVE_GUIDANCE_MARKER = '**When NOT to call';
 const TERMINAL_DELIVERY_TOOLS = new Set(['DeliverPatientMessage']);
 const DELIVERY_NUDGE = 'sistema: el turno no puede cerrar sin un mensaje para el paciente. Llama ahora a DeliverPatientMessage con message_text en español. No repitas herramientas clínicas ya ejecutadas en este turno.';
-const MAX_DELIVERY_NUDGES = 1;
+const MAX_DELIVERY_NUDGES = 2;
+const DELIVERY_FALLBACK_MESSAGES = [
+  'Gracias por tu mensaje. Si necesitas apoyo, escríbeme cuando quieras.',
+  'Gracias por escribirme. Aquí estoy cuando necesites algo.',
+  'Recibí tu mensaje. Cuando quieras contarme más o pedir apoyo, escríbeme.',
+];
 
 function isSuperseded(shouldContinue) {
   return typeof shouldContinue === 'function' && !shouldContinue();
@@ -324,7 +329,13 @@ class BaseLLMProvider {
         const result = await this._executeConversation(config);
         // DeliverPatientMessage is the curated patient reply; prefer it over any model narration in the final response.
         const delivered = this._extractDeliveredMessage(config, result);
-        const extractedOutput = delivered?.trim() ? delivered : this._extractMessageOutput(result);
+        let extractedOutput = delivered?.trim() ? delivered : this._extractMessageOutput(result);
+
+        if (!delivered?.trim() && extractedOutput?.trim() && this._deliveryExpected(result)) {
+          logger.warn('[runConversation] Delivery tool offered but never committed — substituting safe fallback for raw narration', { attempt, suppressedLength: extractedOutput.length });
+          config?.assistant?.toolRuntimeContext?.trace?.setSignals?.({ deliveryFallbackUsed: true });
+          extractedOutput = this._deliveryFallbackMessage(config);
+        }
 
         if (extractedOutput?.trim()) {
           result.output_text = extractedOutput;
@@ -371,6 +382,19 @@ class BaseLLMProvider {
     return (toolsExecuted || []).some(t => TERMINAL_DELIVERY_TOOLS.has(t?.tool_name) && this._toolSucceeded(t));
   }
 
+  _deliveryExpected(result) {
+    return (result?.tool_ids || []).some(id => TERMINAL_DELIVERY_TOOLS.has(id));
+  }
+
+  _deliveryFallbackMessage(config) {
+    const key = String(config?.assistant?.toolRuntimeContext?.turnId
+      ?? config?.assistant?.toolRuntimeContext?.patientCode
+      ?? config?.threadId ?? '');
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) hash = (hash * 31 + key.charCodeAt(i)) | 0;
+    return DELIVERY_FALLBACK_MESSAGES[Math.abs(hash) % DELIVERY_FALLBACK_MESSAGES.length];
+  }
+
   _isTerminalOnly(toolNames) {
     return toolNames.length > 0 && toolNames.every(name => TERMINAL_DELIVERY_TOOLS.has(name));
   }
@@ -531,6 +555,7 @@ module.exports = {
   CONVERSATION_CONTINUATION,
   DELIVERY_NUDGE,
   MAX_DELIVERY_NUDGES,
+  DELIVERY_FALLBACK_MESSAGES,
   TERMINAL_DELIVERY_TOOLS,
   isSuperseded,
 };

package/lib/clinical/tools/deliverPatientMessageTool.js

@@ -2,7 +2,7 @@ const { requireGatewayProvider } = require('../config/llmConfig');
 const { renderMessage } = require('../services/composerService');
 const { isComposerEnabled, isAgentSelfRenderEnabled } = require('../flags/composerFlags');
 
-const EMPTY_OUTBOUND_FALLBACK = 'Estoy revisando tu mensaje con detalle, te respondo en un momento.';
+const EMPTY_OUTBOUND_FALLBACK = 'Recibí tu mensaje. Si quieres contarme más o necesitas apoyo, escríbeme.';
 
 const definition = {
   name: 'DeliverPatientMessage',

package/lib/controllers/templateController.js

@@ -216,7 +216,6 @@ const submitForApproval = async (req, res) => {
         $set: {
           status: 'PENDING',
           approvalRequest: {
-            sid: response.sid,
             dateSubmitted: validSubmittedDate,
             dateUpdated: validUpdatedDate,
             rejectionReason: response.rejection_reason || ''
@@ -270,7 +269,6 @@ const checkApprovalStatus = async (req, res) => {
             status.approvalRequest.date_created || status.approvalRequest.dateCreated || status.content.dateCreated
           );
           dbTemplate.approvalRequest = {
-            sid: status.approvalRequest.sid,
             dateSubmitted,
             dateUpdated: parseDate(
               status.approvalRequest.date_updated || status.approvalRequest.dateUpdated || status.content.dateUpdated,
@@ -288,7 +286,7 @@ const checkApprovalStatus = async (req, res) => {
         contentSid,
         content: status.content,
         approvalRequest: status.approvalRequest,
-        template: dbTemplate
+        template: dbTemplate ? _formatTemplate(dbTemplate) : null
       });
     } catch (err) {
       // If Twilio check fails but we have DB record, return what we know
@@ -301,7 +299,7 @@ const checkApprovalStatus = async (req, res) => {
             status: dbTemplate.status
           },
           approvalRequest: dbTemplate.approvalRequest,
-          template: dbTemplate,
+          template: _formatTemplate(dbTemplate),
           warning: 'Could not fetch latest status from Twilio'
         });
       }
@@ -412,7 +410,7 @@ const getCompleteTemplate = async (req, res) => {
     
     return res.status(200).json({
       success: true,
-      template
+      template: _formatTemplate(template)
     });
   } catch (error) {
     return handleApiError(res, error, 'Failed to get complete template');

package/lib/index.d.ts

@@ -116,13 +116,13 @@ declare module '@peopl-health/nexus' {
     name: string;
     description?: string;
     parameters?: any;
-    handler: (args: any) => any;
+    handler: (args: any) => string | Promise<string>;
   }
 
   export interface AssistantConfigDefinition {
     extends?: typeof BaseAssistant;
     create?: (this: BaseAssistant, code: string, context?: any) => Promise<any>;
-    tools?: Array<AssistantToolDefinition | { name: string; definition?: any; handler: (args: any) => any }>;
+    tools?: Array<AssistantToolDefinition | { name: string; definition?: any; handler: (args: any) => string | Promise<string> }>;
     setup?: (this: BaseAssistant, context: { assistantId: string; thread?: any; options?: any }) => void;
   }
 
@@ -138,7 +138,7 @@ declare module '@peopl-health/nexus' {
       assistantId?: string;
       thread?: any;
       client?: any;
-      tools?: Array<AssistantToolDefinition | { name: string; definition?: any; handler: (args: any) => any }>;
+      tools?: Array<AssistantToolDefinition | { name: string; definition?: any; handler: (args: any) => string | Promise<string> }>;
       setup?: (context: { assistantId: string; thread?: any; options?: any }) => void;
       status?: string;
     } | any);
@@ -146,9 +146,9 @@ declare module '@peopl-health/nexus' {
     thread: any;
     status: string;
     createdAt: Date;
-    registerTool(definition: AssistantToolDefinition | string, schema?: any, handler?: (args: any) => any): void;
+    registerTool(definition: AssistantToolDefinition | string, schema?: any, handler?: (args: any) => string | Promise<string>): void;
     getToolSchemas(): any[];
-    executeTool(name: string, args: any): Promise<any>;
+    executeTool(name: string, args: any): Promise<string>;
     getPreviousMessages(thread?: any): Promise<Array<{ role: string; content: any }>>;
     createThread(code: string, context?: any): Promise<any>;
     sendMessage(userId: string, message: string, options?: any): Promise<any>;

package/lib/models/templateModel.js

@@ -36,7 +36,6 @@ const TemplateSchema = new mongoose.Schema({
     }
   ],
   approvalRequest: {
-    sid: String,
     dateSubmitted: Date,
     dateUpdated: Date,
     rejectionReason: String

package/lib/services/templateService.js

@@ -15,7 +15,6 @@ const refreshApprovalStatuses = async (templates) => {
           const reqData = approvalInfo.approvalRequest;
           const updateFields = {
             approvalRequest: {
-              sid: reqData.sid,
               dateSubmitted: reqData.dateCreated ? new Date(reqData.dateCreated) : new Date(),
               dateUpdated: reqData.dateUpdated ? new Date(reqData.dateUpdated) : new Date(),
               rejectionReason: reqData.rejectionReason || ''

package/package.json

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